Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@skill-store use the local/diagnosing-bugs skill"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Skill Store serves persistent skills through the Model Context Protocol (MCP). It runs over standard input and output as one mcpflow child. The store supports directory, read-only Git, and S3 backends.
Install Python 3.12 or later.
Run uv pip install . in your environment.
Create separate state and library directories:
mkdir -p /data/skill-state /data/skill-library
SKILLS_STATE_DIR=/data/skill-state skill-storeThe state directory must exist and permit writes. Run only one process per state directory. Do not place a directory store inside the state directory.
Related MCP server: mcp-skills
Register the server under namespace skills.
Use package: skill-store, actions: true, and cache_ttl: 0.
Set SKILLS_STATE_DIR to the persistent state directory.
The production source is a pinned commit in the separate skill-store repository.
For local testing, use an installed executable as a custom child.
Open the child's Actions page.
Call add_store with name local, kind directory, and the absolute library path.
Call set_writable with name local.
use_skill(name) returns the skill body and supporting resource addresses.
Use qualified names such as local/diagnosing-bugs.
An ambiguous short name returns all matching qualified names.
list_skills(offset, limit) returns a page of the catalog.
write_skill(name, files, message, replace) writes into the selected writable store.
The files object maps relative paths to UTF-8 text.
Include SKILL.md with YAML front matter and a description.
Use the optional binary_files object for base64 content.
Set replace to true to replace an existing skill and remove obsolete files.
The message is a caller note. The store does not provide version history.
The server exposes one prompt per skill and every supporting file as a concrete resource.
Its live catalog is available at instructions://self.
Gateway resource addresses start with skill://skills/.
Set SKILLS_NAMESPACE to a different gateway namespace when required.
Set it to an empty string for direct stdio clients.
Set SKILLS_PROMPT_SEPARATOR=__ if a client rejects slash-separated prompt names.
This setting changes the listed prompt names, so gateway lookup supports the fallback.
The eight actions are add_store, update_store, remove_store, set_writable,
refresh_store, migrate_skill, migrate_store, and list_stores.
The gateway restricts these actions to administrators.
The store itself has no authentication or HTTP listener.
Store credentials remain in stores.json with file mode 0600.
Protect volume snapshots because this file contains plaintext credentials.
Action results mask credential fields.
Removing a store removes its registration and preserves its contents.
Removing the writable store clears the writable selection.
Use update_store to change a location, ref, or credential.
Remove and add a store to change its name or kind.
Migration requires the destination to be writable.
It copies and verifies every file before deleting a writable source.
Git sources remain intact.
An identical destination supports retry after interruption.
A different destination requires explicit replacement through write_skill first.
The store permits 8 MiB per file and 32 MiB per skill.
It permits 256 files per skill, 1,024 skills per store, and 256 MiB per store.
The registry permits 128 stores and at most 1 MiB of configuration.
Loaded skill bytes remain in memory to keep reads independent of backend latency.
Instructions use at most 8,192 bytes. Use list_skills for the complete catalog.
Directory replacement uses an atomic native exchange on macOS and Linux.
An unsupported filesystem refuses replacement before changing the public tree.
S3 replacement writes supporting files before SKILL.md, then removes obsolete objects.
External readers can observe mixed generations during a failed or interrupted S3 replacement.
Refresh or restart can import that mixed state. S3 has no transaction across objects.
Use S3 versioning or volume snapshots when recovery history is required.
Git stores refresh every 60 seconds and support immediate refresh_store calls.
A failed backend refresh preserves the last published catalog for that store.
Backend calls have request limits and finite scan deadlines.
No agent needs a local skill directory or an offline cache.
uv pip install '.[dev]'
pytest
ruff check src tests
python openspec/changes/remote-skill-store/check_models.pyStart disposable MinIO and run the integration test:
docker compose -f compose.minio.yml up -d
SKILL_STORE_MINIO_ENDPOINT=http://127.0.0.1:19000 \
SKILL_STORE_MINIO_ACCESS_KEY=skillstoretest \
SKILL_STORE_MINIO_SECRET_KEY=skillstore-local-test-only pytest -m integration
docker compose -f compose.minio.yml downThese credentials are for local disposable tests only. The service listens on loopback and stores no persistent data.
Run the stdio demonstration with a new directory:
python scripts/demo.py --root /tmp/skill-store-demoThe demonstration starts three real child processes. It verifies restart persistence, prompt content, resource bytes, and migration. It writes a report into the demonstration directory.
Import a local library without changing its source:
python scripts/import_skills.py --source ~/.agents/skills \
--target /data/shared-skills --report /data/shared-import.json
python scripts/import_skills.py --source ~/.claude/skills --skip-linked-skills \
--target /data/claude-skills --report /data/claude-import.jsonEach target must be new. Register the two targets under different store names. This preserves same-named skills without a hidden precedence rule. The importer verifies every copied file with SHA-256. Retain local source directories until deployed client acceptance succeeds.
The original product documents in docs/ are historical references.
The implementation design records corrections to their persistence assumptions.
Register a directory, Git, or S3 store without a restart.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | HEAD | |
| url | No | ||
| kind | Yes | ||
| name | Yes | ||
| path | No | ||
| bucket | No | ||
| prefix | No | ||
| region | No | us-east-1 | |
| endpoint | No | ||
| access_key | No | ||
| credential | No | ||
| secret_key | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full burden of behavioral disclosure. It adds one useful behavioral fact (no restart required), but omits what happens on duplicate names, whether registration validates connectivity to the store, whether it persists, and what side effects occur beyond registration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded and wastes no words, which is good. However, it is under-specified for a 12-parameter, 3-kind tool; conciseness here crosses into insufficiency rather than appropriate brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the output schema covering return values, the description is far from complete for a tool with 12 parameters, 3 store kinds, and no annotations. An agent cannot determine which optional parameters are required for each store kind or how the fields interact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with 12 parameters, so the description must compensate by explaining parameter meaning, but it names none of them. It does not clarify that url/path apply to git/directory while bucket/prefix/region/endpoint/access_key/secret_key apply to S3, leaving the agent to guess the per-kind parameter mapping.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Register') with a concrete resource ('a directory, Git, or S3 store') and adds a useful qualifier ('without a restart'). The three store kinds help distinguish it from sibling tools like remove_store and update_store by implying creation semantics, though it never explicitly contrasts itself with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use add_store versus update_store, refresh_store, or migrate_store, and no conditions or prerequisites for registering a store. 'Without a restart' implies a hot-registration benefit but does not tell the agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List qualified names and descriptions with pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the operation returns names/descriptions and supports pagination, implying a read-only list operation. However, it does not explicitly state lack of side effects, ordering behavior, or whether the list spans all stores or a current context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the resource, the returned data, and the pagination capability efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list operation with an output schema present, the description covers the core purpose. However, it lacks explicit guidance on when to use this tool over sibling list/use/write tools, and omits context about scope or limitations, leaving some gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for limit and offset. It merely says 'with pagination,' which hints at the parameters but does not explain their meaning, defaults, maximum values, or interaction. The parameter names are somewhat self-evident, but the description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), identifies the resource ('skills'), and states the exact payload ('qualified names and descriptions'). It clearly differentiates from siblings like list_stores by the resource type and from mutating siblings like write_skill/use_skill by the read-only list action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage context is provided beyond pagination. The description does not say when to call list_skills versus alternatives such as list_stores, use_skill, or write_skill, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List store configuration with credentials masked.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal a valuable trait—that credentials are masked—but does not mention read-only guarantees, completeness of results, or potential error cases. The read-only nature is implied by 'list' but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the primary action and scope. Every word earns its place, and no redundant restatement of the tool name appears.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema, the description is largely sufficient. It states what is returned (store configuration), notes the masking behavior, and the output schema covers return value details. A brief mention that it lists all stores could improve completeness, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (0 parameters), so there are no parameter semantics to explain. Per the baseline for zero-parameter tools, the description is not penalized for missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('store configuration'), and adds a distinguishing detail ('with credentials masked'). It clearly separates this tool from siblings like add_store, update_store, and remove_store.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as list_skills or the mutation operations. Usage must be inferred entirely from the verb and resource name, with no exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy and verify a skill before removing a writable source.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| to_store | Yes | ||
| from_store | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of side-effect disclosure, and it does reveal a copy-then-verify workflow tied to a later removal. However, it leaves ambiguous whether the tool itself removes the source, what 'verify' entails, and what happens on verification failure. This is useful but incomplete behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler, and it front-loads the core action. The brevity is a strength even though it leaves some context gaps scored elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-required-parameter migration tool with no annotations, this is minimally adequate: the agent knows the operation, can infer source and destination from parameter names, and an output schema exists for the return shape. However, it lacks guidance on store-identifier semantics, conflict or overwrite behavior, and whether the source is actually deleted, so the tool is not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not define 'from_store', 'to_store', or 'name'; it only alludes to 'a skill' and 'writable source'. Parameter names are somewhat self-explanatory, but the description does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action ('Copy and verify') and identifies the resource ('a skill') and the migration context ('before removing a writable source'). This distinguishes it from the sibling migrate_store, which concerns stores rather than skills. It is not a tautology of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before removing a writable source' provides a clear workflow condition: use this tool when a skill needs to be safely relocated off a writable source. It does not explicitly name alternatives or when-not-to-use cases, so it is clear but not fully exclusionary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Migrate each skill, stopping at the first error with progress counts.
| Name | Required | Description | Default |
|---|---|---|---|
| to_store | Yes | ||
| from_store | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does add valuable behavior: per-skill iteration, stopping at the first error, and progress counts. However, it does not state whether migration copies or moves skills, whether the destination store must already exist, or whether existing destination skills are overwritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler: it front-loads the action and scope, then adds error-handling behavior. Every word contributes useful information, making it appropriately concise given the simplicity of the two-parameter schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values, so that is not a major gap. However, with no annotations and 0% parameter schema coverage, the description should provide more operational context. It omits when to use this tool over migrate_skill, whether to_store must be pre-created, and what happens on conflict or partial migration, making the overall call context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention from_store or to_store at all. The parameter names are somewhat self-explanatory as source and destination, but no format, valid store identifiers, prerequisites, or expected relationship between stores is provided, so the description does not compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Migrate') with a clear resource ('each skill'), and adds scope by saying it iterates over each skill. It is reasonably distinguishable from the sibling migrate_skill through the plural 'each skill', though it does not explicitly name the sibling or say 'all skills in from_store'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use migrate_store instead of migrate_skill, write_skill, or other store-related tools. The intended use is only implied by the tool name and parameters, leaving the agent to infer the difference between migrating a single skill and migrating every skill.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh a store and atomically publish the rebuilt catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does disclose a meaningful behavioral trait: the refresh is atomic and publishes the rebuilt catalog. However, it doesn't mention whether the store must exist, whether this is destructive to the current catalog, whether it requires writable permissions, or what the output schema contains. The atomicity disclosure is valuable but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and the key behavioral guarantee (atomic publish). Every word earns its place. No fluff or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description is mostly adequate, but it lacks context about prerequisites (e.g., store must exist), side effects on the existing catalog, and relationship to sibling tools like set_writable or migrate_store. The atomic publish detail is good, but an agent might not know whether refresh requires the store to be writable or what happens to the old catalog if the rebuild fails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single 'name' parameter. The description says 'a store' but does not explicitly state that 'name' identifies which store to refresh, nor does it explain the format or constraints. The parameter is simple and self-evident from the schema, but the description adds no direct parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('refresh') and resource ('store'), and adds the key outcome 'atomically publish the rebuilt catalog.' It distinguishes the action from siblings like add_store, update_store, and remove_store, though it doesn't explicitly name them. The atomic publish detail adds precision beyond a generic 'refresh'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to use when you want to rebuild and publish a store's catalog, but it doesn't explicitly state when to use it versus alternatives like update_store or migrate_store. There is no mention of prerequisites, side effects, or when not to use it. The context is clear enough for a simple tool, but no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a registration without deleting backend data.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses one key behavioral trait—that backend data is preserved—but omits other details like idempotency, reversibility, or error behavior. This partial transparency earns a mid-range score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. It is efficient but arguably too sparse, sacrificing important detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and an output schema exists, the description leaves critical gaps: it does not explain the parameter's role or provide usage context. An agent would need to infer the purpose of 'name' and when to invoke this tool, making the definition incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'name' with no description, and the tool description does not explain what 'name' refers to (presumably the store name). Since schema description coverage is 0%, the description fails to compensate and leaves the parameter's meaning entirely ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Remove') and resource ('a registration'), and the qualifier 'without deleting backend data' adds precision, distinguishing it from a hypothetical hard-delete. Among siblings like add_store and update_store, the removal purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or when not to use it. The usage is only implied from the purpose, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select one writable-capable store. Git stores are read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It only discloses that Git stores are read-only; it does not say whether this sets global state, whether non-writable stores are rejected or accepted as read-only, what happens to a previously selected store, or what errors may occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler: the first states the action, the second states the critical constraint. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a store-selection tool with no annotations, the description omits important operational context: what 'select' means for subsequent write operations, whether Git stores can still be selected but remain read-only, and how this relates to write_skill or use_skill. The output schema may cover return values, but not the runtime behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the 'name' parameter, how the store is identified, or any constraints on the value. The agent must infer from the property name and tool title that 'name' is the target store's name, which is insufficient compensation for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Select') and a specific resource ('one writable-capable store'), and immediately clarifies that Git stores are read-only. It does not explicitly name sibling alternatives or say that this sets the active writable store, but the core action is identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a selection criterion: choose a writable-capable store, with Git stores excluded because they are read-only. However, it does not mention when to use this tool instead of add_store, update_store, or remove_store, nor does it state prerequisites such as the store already existing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update specified fields. Omitted fields retain their existing values.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | ||
| url | No | ||
| name | Yes | ||
| path | No | ||
| bucket | No | ||
| prefix | No | ||
| region | No | ||
| endpoint | No | ||
| access_key | No | ||
| credential | No | ||
| secret_key | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states the update semantics ('Omitted fields retain their existing values') but does not disclose side effects like whether credentials are partially updated, whether changes are reversible, or whether updates require authentication. The ambiguity of 'specified fields' is vague and leaves much unsaid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (one sentence) and front-loads the core semantics. It avoids verbosity. However, the conciseness comes at the cost of essential details, so it is not effectively structured for the agent's needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, no annotations, and an output schema) the description is incomplete. It fails to clarify concepts like partial update semantics beyond omissions, how to identify the store (likely via 'name' or 'ref'), and what fields are used for. The description does not explain what happens on failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 11 parameters with 0% description coverage, so the description must compensate, but it does not describe any individual parameter's purpose. It only gives a generic 'specified fields' which is not helpful for an agent to know what to put in fields like 'bucket', 'credential', or 'endpoint'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool updates specified fields of a store, which is a clear verb+resource. However, it is somewhat generic and doesn't explicitly distinguish it from sibling tools like add_store or migrate_store. The agent must infer the context from field names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It does imply that only fields needing changes are provided (omitted fields retain values), which is a usage hint, but there is no mention of prerequisites, such as whether the store must already exist, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a skill and its supporting resources.
Use a matching skill before starting a task. Load it with use_skill and its qualified name. No skills are available.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'load' and supporting resources, with no mention of side effects, state changes, errors, or prerequisites. The statement 'No skills are available' also undercuts the described behavior and makes the tool's actual effect unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first two sentences are concise and front-loaded with the core purpose and usage. The third sentence, 'No skills are available,' is extraneous, confusing, and contradicts the rest of the description, preventing a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool an output schema may cover return values, but the description still misses basic behavioral context such as what loading entails or what happens if no skill matches. The contradictory claim that no skills are available makes the tool's intended invocation unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero description coverage for the single 'name' parameter. The description adds value by calling it a 'qualified name', but it never explains what qualifies as qualified or provides an example, so the compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Load a skill and its supporting resources') and identifies the resource clearly, which distinguishes it from siblings like write_skill or migrate_skill. However, the closing line 'No skills are available' muddles the purpose by implying the tool has nothing to load.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage context: use a matching skill before starting a task and load it with use_skill by its qualified name. It does not name alternatives or exclusions, but the sibling tools are sufficiently different that no direct comparison is necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a complete skill into the writable store; binary files use base64.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| files | Yes | ||
| message | No | ||
| replace | No | ||
| binary_files | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It adds one useful detail (binary files use base64) but is silent on overwrite/replace semantics, whether 'complete' means the entire skill is replaced, what happens when replace=false, and what side effects writing into the store has.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler; the core action and the non-obvious base64 note are both present. It is concise to a fault, lacking supporting context, but the wording that exists earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, nested file maps, a replace flag, and no annotations, the description is incomplete for correct invocation. It does not explain what files expects, what message is for, what replace controls, or how binary_files relates to files; the output schema may cover return values, but input semantics are under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the five parameters. It only clarifies the binary_files/base64 aspect; name, files, message, and replace remain effectively unexplained, leaving critical invocation behavior ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Write'), a resource ('a complete skill'), and a target ('the writable store'), so the tool's core purpose is understandable. It does not explicitly contrast with siblings like migrate_skill or add_store, but the phrasing is clear enough to distinguish it from list/remove/use tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use write_skill versus alternatives such as migrate_skill, add_store, or update_store. The phrase 'writable store' hints at a prerequisite, but it is not stated as a condition or exclusion, and the replace/message parameters are not framed in terms of usage flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_storelist_skillslist_storesmigrate_skillmigrate_storerefresh_storeremove_storeset_writableupdate_storeuse_skillwrite_skillScored across 11 tools
Most tools target a distinct resource and action: store lifecycle verbs are clearly separated from skill operations. The main risk is migrate_skill vs migrate_store, but their descriptions clarify single-skill vs batch migration.
The dominant pattern is verb_noun (add_store, list_skills, write_skill) and is easy to predict. set_writable breaks the pattern by omitting the store object, and migrate_skill/migrate_store are easy to typo but still follow the convention.
Eleven tools is within the well-scoped range and each tool covers a distinct management action for stores or skills. The count feels appropriate for a skill-store management server without bloat.
Store lifecycle is well covered with add/update/remove/refresh/list and writable selection, and skills support use/write/list/migrate. The obvious gap is no generic delete/remove skill operation, so a stale skill in a writable store cannot be directly removed.
Manage portable AI agent playbooks, Agent Skills, MCP configurations, personas, and memory.
Git-backed platform for skills, tools, and context for AI agents
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
Cross-tool persistent memory and context for AI assistants over MCP.
