| name | skill-mcp-master |
| description | Master reference for the Skill MCP server - a self-hosted agent skills registry that delivers curated, expert instructions for common AI tasks via 6 MCP tools. Covers the full 3-tier progressive disclosure workflow: Tier 1 discovery (skills_find_relevant), Tier 2 loading (skills_get_body, skills_get_options), and Tier 3 supplementary resources (skills_get_reference, skills_run_script, skills_get_asset). Use this skill whenever you need to understand, operate, or get the most out of the Skill MCP server.
|
| license | Apache-2.0 |
| metadata | {"author":"skill-mcp","version":"1.0","tags":["mcp","skills","workflow","meta","reference","registry"],"platforms":["claude-code","cursor","windsurf","codex","cline","copilot","aider","any"],"triggers":["how do I use the skill MCP","what skills are available","skill workflow","MCP skills reference","use a skill","check skills","find a skill for this task"]} |
Skill MCP - Master Usage Guide
What Is the Skill MCP?
The Skill MCP server is a self-hosted agent skills registry accessible to any
MCP-compatible AI agent or tool. It stores curated, expert-authored instruction sets
("skills") and delivers them on demand through a structured 3-tier disclosure model.
Each skill contains:
| Tier | Content | Tools |
|---|
| 1 | Frontmatter - name, description, tags, score | skills_find_relevant |
| 2 | Instructions, system prompt addition | skills_get_body, skills_get_options |
| 3 | Reference docs, executable scripts, asset templates | skills_get_reference, skills_run_script, skills_get_asset |
The Canonical 3-Step Workflow
Follow this sequence for every task where a skill might apply.
Step 1 - Discover (skills_find_relevant)
skills_find_relevant(query="<specific description of your task>", top_k=5)
Interpret scores:
score > 0.6 → strong match - proceed to Step 2score 0.4–0.6 → possible match - read description to decidescore < 0.4 → no relevant skill - proceed without one
Query tips:
- ✅
"write pytest unit tests for a Flask REST API endpoint"
- ✅
"extract tables from a multi-page PDF and output as CSV"
- ✅
"review Python code for security vulnerabilities"
- ❌
"testing" (too generic - poor embedding)
- ❌
"help me" (no task signal)
Step 2 - Load (skills_get_body)
skills_get_body(skill_id="<top result from Step 1>")
The response contains:
{
"skill_id": "test-writer",
"instructions": "## Testing Workflow\n1. Identify the function under test ...",
"system_prompt_addition": "You are a senior test engineer ...",
"tier3_manifest": {
"references": ["TESTING-GUIDE.md", "COVERAGE-POLICY.md"],
"scripts": ["coverage_check.py"],
"assets": ["test-template.py"]
}
}
After loading:
- Read and apply
instructions - this is the authoritative guidance
- If
system_prompt_addition is non-empty, incorporate it into your context
- Check
tier3_manifest - only proceed to Step 3 if instructions reference specific files
Optional: load config (skills_get_options)
skills_get_options(skill_id="<skill_id>")
Only needed when customising skill behaviour or checking constraints/dependencies.
Step 3 - Supplement (only when needed)
3a - Reference documents:
# First: get the manifest
skills_get_reference(skill_id="test-writer", filename="list")
# Then: fetch the specific file the instructions mentioned
skills_get_reference(skill_id="test-writer", filename="TESTING-GUIDE.md")
3b - Execute a helper script:
# First: see available scripts
skills_run_script(skill_id="test-writer", filename="list")
# Then: run with optional inputs
skills_run_script(skill_id="test-writer", filename="coverage_check.py",
input_data={"TARGET_DIR": "./src", "MIN_COVERAGE": "80"})
# Returns: exit_code, stdout, stderr - source is never exposed
3c - Fetch a template or asset:
# First: get the manifest
skills_get_asset(skill_id="test-writer", filename="list")
# Then: fetch the template
skills_get_asset(skill_id="test-writer", filename="test-template.py")
# Use as a starting template - adapt it to the specific task
Rule: Only load Tier 3 resources that the Tier 2 instructions explicitly
reference. Do not load them speculatively - it wastes context and latency.
Complete Example
# 1. Discover
results = skills_find_relevant(
query="write integration tests for a Python REST API using pytest"
)
# → test-writer: 0.84 ← strong match
# 2. Load instructions
body = skills_get_body(skill_id="test-writer")
# → instructions: "## Testing Workflow ..."
# → tier3_manifest.references: ["TESTING-GUIDE.md"]
# → tier3_manifest.assets: ["test-template.py"]
# 3. The instructions say "follow TESTING-GUIDE.md for project conventions"
guide = skills_get_reference(skill_id="test-writer", filename="TESTING-GUIDE.md")
# 4. The instructions say "use test-template.py as your file scaffold"
template = skills_get_asset(skill_id="test-writer", filename="test-template.py")
# 5. Apply instructions using the guide and template
Decision Rules
| Situation | Action |
|---|
| Starting any non-trivial task | Always call skills_find_relevant first |
| All scores < 0.4 | No relevant skill - proceed without one |
| Score > 0.4 | Call skills_get_body to load instructions |
| Instructions are complete | Apply them - stop, do not load Tier 3 |
| Instructions mention a file | Load that specific file via Tier 3 |
| User asks to customise skill | Call skills_get_options |
| Task is trivial (< 2 min) | Skip skill lookup if confidence is high |
Available Skills (current registry)
| skill_id | Domain |
|---|
api-integration | REST/GraphQL API integration patterns |
code-review | Security, quality, and bug review |
data-analysis | CSV/tabular data analysis and EDA |
docx-creator | Word document generation |
git-commit-writer | Conventional commit messages |
pdf-processing | PDF extraction and form filling |
readme-writer | Project README generation |
sql-query-writer | SQL query authoring and validation |
test-writer | Unit, integration, and E2E test writing |
web-scraper | Web scraping and data extraction |
Query skills_find_relevant for semantic discovery - the above is a reference snapshot.
Tool Quick-Reference
| Tool | When to call | Returns |
|---|
skills_find_relevant(query, top_k=5) | Start of every task | Ranked skill list with scores |
skills_get_body(skill_id) | After finding a match | Instructions + tier3_manifest |
skills_get_options(skill_id) | When customising behaviour | Config schema, variants, limits |
skills_get_reference(skill_id, filename="list") | To see/fetch reference docs | Manifest or file content |
skills_run_script(skill_id, filename, input_data={}) | To run a helper script | exit_code, stdout, stderr |
skills_get_asset(skill_id, filename="list") | To see/fetch templates | Manifest or file content |
Notes
- Skills are read-only - calling any tool does not modify registry state
- Script execution is only available on the local server
(
MCP_TRANSPORT=streamable-http python -m skill_mcp.server).
The Cloudflare Workers deployment returns the script manifest only.
- Skills are versioned -
skills_get_options returns the version of each skill
- The MCP server URL for SSE transport:
https://skill-mcp.<your-subdomain>.workers.dev/sse
