From stash-mcp
Behavioral guide for working with a Stash-MCP content store. Use when the user asks to "read from stash", "update docs in the content store", "search the knowledge base", "create a document", "find documentation", or any task involving Stash-MCP tools (create_content, read_content, edit_content, search_content, list_content, move_content, etc.). Teaches efficient navigation, surgical editing, transaction safety, and semantic search strategy.
How this skill is triggered — by the user, by Claude, or both
Slash command
/stash-mcp:stash-mcp-usageThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Stash-MCP is a file-backed content store accessed through MCP tools. Content lives as files on disk, optionally git-tracked, with semantic search available when enabled. Only README.md files surface as MCP resources — everything else goes through tools.
Stash-MCP is a file-backed content store accessed through MCP tools. Content lives as files on disk, optionally git-tracked, with semantic search available when enabled. Only README.md files surface as MCP resources — everything else goes through tools.
This skill covers server-universal patterns: how to use the tools efficiently regardless of what content is in the store. For deployment-specific conventions (directory layout, templates, naming), read .stash/SKILL.md from the content store itself — the SessionStart hook handles this automatically.
Think of Stash-MCP as a filesystem with guardrails:
Stash stores files as-is on disk. Anything text-based round-trips losslessly through the tools; binary types (images, etc.) are stored and served as assets but should not be opened with read_content — you'll get raw bytes.
| Class | Extensions | Notes |
|---|---|---|
| Markdown (primary) | .md, .markdown | First-class. Heading hierarchy parsed by inspect_content_structure. Only README.md surfaces as an MCP resource — everything else is tool-only. |
| Diagrams | .mmd, .mermaid, .gantt | Rendered as diagrams in the UI viewer. Plain text under the hood — edit like any text file. .gantt is YAML-based. |
| API specs | .json with an openapi root key | Rendered as an OpenAPI viewer in the UI. Stored as plain JSON. |
| Tabular | .csv, .tsv | Rendered as HTML tables in the UI. |
| Web | .html, .htm | Rendered in a sandboxed iframe. |
| Structured text | .json, .yaml, .yml, .toml, .xml, .ini, .cfg | Stored as text, no special rendering. |
| Code | .py, .js, .ts, .css, .rst, .txt, .log, plus any other text extension | Stored as text. Searchable. |
| Image assets | .png, .jpg, .jpeg, .gif, .webp, .svg, .ico, .bmp | Served via /ui/raw/<path> for embedding. Do not read_content these — store and link instead. |
There is no extension allowlist for storage. Files with unknown extensions are accepted and served as text/plain.
Markdown is the host format — several other types can be embedded inline so a single document renders as a richer view:
. Relative paths are rewritten to /ui/raw/ URLs at render time, so the image just needs to live in the content store. Absolute URLs and data: URIs also pass through.```mermaid renders inline. Use this for one-off diagrams; reserve standalone .mmd files for diagrams you want to reuse or link to.```gantt (YAML body) renders inline. Standalone .gantt files work the same way. The YAML schema is Stash-specific (not Mermaid gantt syntax) — see references/gantt-format.md before authoring.```csv or ```tsv renders as an HTML table inline. Good for small, document-scoped tables; use standalone .csv files when the data is the artifact.<details>, <img>, <video>, <iframe>, <div> all work. Use sparingly; markdown syntax is preferable when it covers the case.Cannot be embedded inline: PDFs, Office documents (.docx, .xlsx, .pptx), Jupyter notebooks (.ipynb), and other binary formats. Link to them as assets if needed, but Stash has no native renderer for these — read_content will return unreadable bytes.
Rule of thumb: if the asset is referenced from one document, embed it as a fenced block. If multiple documents reference it, store it as a standalone file and link.
Stash exposes 21+ tools across five categories. Not all are always available — availability depends on server configuration. Only use tools that appear in the tool list.
| Category | Tools | Always Available |
|---|---|---|
| Discovery | list_content, inspect_content_structure(_batch), search_content | list/inspect yes, search conditional |
| Reading | read_content(_batch) | Yes |
| Writing | create_content, edit_content(_batch), overwrite_content, delete_content, move_content(_batch/_directory) | Only when not read-only |
| Transactions | start_content_transaction, commit_content_transaction, abort_content_transaction, list_content_transactions | Only with git tracking enabled |
| Git History | log_content, diff_content, blame_content | Only with git tracking enabled |
Each discovery step narrows scope before the next. Never skip straight to reading full files.
list_content(recursive=true) → map the territory
inspect_content_structure(path) → understand doc shape without reading content
search_content(query) → find specific content by meaning
read_content(path, max_lines=50) → sample before committing to full read
read_content(path) → read only what you actually need
inspect_content_structure is the most underused tool. It returns heading outlines without reading file content — use it to understand document organization before deciding what to read.
edit_content applies targeted string replacements. overwrite_content replaces the entire file. Prefer edit because:
Use overwrite_content only when regenerating an entire file from scratch.
When the server has git tracking enabled, every write tool requires an active transaction owned by your session — create_content, overwrite_content, edit_content, edit_content_batch, delete_content, move_content, move_content_batch, and move_content_directory are all gated. Calling any of them without an active transaction raises:
TransactionError: No active transaction. Call start_content_transaction first.
The choreography is the same whether you're touching one file or twenty:
list_content_transactions() → check for orphans first
start_content_transaction() → acquire the global lock
[... one or more write operations (create/overwrite/edit/delete/move, including batch variants) ...]
commit_content_transaction(message="descriptive commit message")
Multi-file changes are simply the case where the transaction spans more than one operation — same mechanism, same atomicity guarantee. If something goes wrong mid-transaction, call abort_content_transaction() to roll back all staged changes.
When git tracking is off, writes go straight to disk and the transaction tools aren't registered. Check the tool list to know which mode you're in.
Every read_content call returns a SHA-256 hash. Pass this hash to write operations. If the file changed between your read and your write, the operation fails — this is intentional. Re-read the file, check what changed, then retry with the new SHA.
Batch operations (edit_content_batch) validate all SHAs before writing anything. One stale SHA aborts the entire batch.
Semantic search works on meaning, not keywords. Write queries as natural language questions or phrases:
Scores: 0.65+ is a strong match, 0.50–0.65 is worth reading to verify, below 0.50 is likely noise. Use file_types to filter (e.g., .md for docs only). Multiple short queries often beat one complex query.
See references/search-strategy.md for detailed guidance.
inspect_content_structureedit_content is almost always saferTransactionError: No active transaction. Call start_content_transaction first.For in-depth coverage beyond this overview:
references/tool-reference.md — behavioral guide for every tool, organized by categoryreferences/workflow-patterns.md — complete choreography patterns with rationalereferences/search-strategy.md — embedding model characteristics, score interpretation, query techniquesreferences/gantt-format.md — schema and examples for .gantt files and ```gantt blocks (Stash-specific, not Mermaid)npx claudepluginhub dylanturn/stash-mcp --plugin stash-mcpGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.