🔌 agent-skills-mcp

MCP server that exposes the same agent-skills catalog to any MCP-compatible AI client. Use it when you want the agent to consult skills on demand during a session — search by intent, then fetch only what's needed.

CLI vs MCP

Both use the same catalog and the same CDN. Choose by workflow:

| | CLI (@tech-leads-club/agent-skills) | MCP (this package) | | :-------------- | :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | | Use when | You want skills installed in your agent (project or global) so they're always available. | You want the agent to look up skills during a chat — no installation. | | Persistence | Skills live in .agents/, ~/.cursor/skills/, etc. | No local install; agent fetches from CDN when it needs a skill. | | Best for | Curated set of skills you use often; lockfile, updates, multi-agent install. | One-off help, exploring the catalog, or trying a skill before installing via CLI. |

You can use both: install your go-to skills with the CLI and add the MCP so the agent can pull in others on demand.

Why use this MCP

When the agent needs a skill mid-session, loading the full catalog would be wasteful. This server provides a three-step workflow — search by intent, load the right skill, then fetch only the references needed — so the agent finds skills in one tool call and doesn't overfetch or guess names.

For explicit catalog browsing requests, there is also a dedicated list_skills tool that returns a compact category-grouped list with truncated descriptions.

Search is powered by Fuse.js: fuzzy matching over name, extracted trigger keywords, description, and category, with extended operators and relevance scoring (0–100 + match quality).

🛠️ Tools

list_skills

Catalog browse tool (explicit request only). When: The user explicitly asks to list/browse available skills. Input: explicit_request: true (required) and optional description_max_chars (default 120, range 40..240). Returns: Available skills grouped by category, each with name and truncated description, plus total_skills and total_categories. Constraints: Do not call proactively during normal search/read/fetch workflow.

• Designed for low token usage with compact JSON output
• Uses in-memory index data (no extra registry fetch on execution)
• Returns only currently available skills for use

search_skills

Step 1 of 3 in the skill workflow. Always call this before read_skill. When: The user needs help with a technical task (implement, refactor, test, deploy, review, etc.). Input: A concise intent phrase, e.g. typescript api error handling, react component testing. Returns: Up to 5 skills ranked by relevance with name, description, category, usage_hint, score (0-100), and match_quality. Then: Pick the highest-scoring match and call read_skill with its name. Tips: Multi-word queries use AND logic. Use | for OR (e.g. react | vue testing). Use = for exact match.

Search features:

• Fuzzy matching via Fuse.js with extended search operators (AND, OR |, exact =, prefix ^)
• Weighted fields: name (0.45), extracted triggers (0.30), description (0.20), category (0.05)
• Trigger extraction: Automatically parses "Triggers on...", "Use when...", and "Keywords -..." patterns from descriptions into a high-signal index field
• Relevance scoring: Each result includes a 0-100 score and a human-readable match_quality label (exact / strong / partial / weak)
• Minimum match character length of 2 to avoid noise
• Empty query → UserError("Query cannot be empty")
• No matches → empty array with explanatory message

read_skill

Step 2 of 3. Call after search_skills — never call directly without searching first. Input: The skill name from search_skills results. Returns: [0] The skill's main instructions (SKILL.md). [1] A list of available reference file paths (scripts/, references/, assets/). Then: Apply the skill instructions. Only call fetch_skill_files if the instructions reference specific files you need.

• Fetches SKILL.md explicitly from files[] as the main skill instructions
• Reference list includes only paths under scripts/, references/, and assets/
• Returns two separate content blocks: main content + compact reference list (capped at 50 paths)
• Skill with only one file returns a single content block (no empty second block)
• Invalid skill_name → UserError("Skill '{name}' not found. Use search_skills to find valid names.")
• CDN failure → UserError("CDN unavailable. Try again shortly.")

fetch_skill_files

Step 3 of 3 (optional). Fetch reference files that a skill's instructions told you to load. Input: skill_name + up to 5 file_paths from the reference list returned by read_skill. Returns: The content of each requested file, separated by --- delimiters. Constraints: Only paths from read_skill's reference list are valid — never guess or construct paths. Make multiple calls if you need more than 5 files.

• Validates all paths against skill.files[] before any network call — rejects with the full list of invalid paths
• Accepts only paths under scripts/, references/, and assets/ from read_skill
• Fetches valid files in parallel (Promise.allSettled)
• Partial failure: returns successful content and notes failed paths — does not abort the entire response

📦 Resource & Prompts

skills://catalog

Full registry JSON (application/json). MCP clients that support Resources can cache this natively, eliminating round-trips for catalog data.

Prompts (Slash Commands)

MCP prompts are surfaced as slash commands (/) in compatible clients (Claude Desktop, Cursor, VS Code + Copilot, Claude Code). They give users instant access to skills without typing tool names.

/skills — Main entrypoint

The easiest way to use the catalog. Give your task in natural language and the prompt guides the agent through search_skills → read_skill → apply.

| Argument | Required | Description | | :------- | :------- | :-------------------------------------------------------------------- | | task | Yes | What you are trying to accomplish (e.g. "optimize React performance") |

Examples:

• /skills task:"refactor a large React component"
• /skills task:"review accessibility issues in my UI"
• /skills task:"plan migration from monolith to modular architecture"

/use — Direct skill shortcut

Use when you already know the exact skill name and want a direct shortcut.

| Argument | Required | Description | | :-------- | :------- | :------------------------------------- | | name | Yes | Exact skill name (e.g. docs-writer) | | context | No | What specifically you need help with |

Examples:

• /use name:"docs-writer" context:"write a README for this package"
• /use name:"react-best-practices" context:"improve Next.js page performance"

/skills-help — Quick usage examples

Shows quick examples and when to use /skills vs /use.

/find-skill — Compatibility alias

Alias for /skills with the same task argument.

🚀 Quick Start

Plugin Install (Recommended)

The fastest way — no manual config, no JSON editing.

Cursor

Browse cursor.com/marketplace and search for agent-skills, or type inside Cursor:

/add-plugin agent-skills

Claude Code

Add the Tech Leads Club marketplace, then install the plugin:

/plugin marketplace add tech-leads-club/agent-skills
/plugin install agent-skills-mcp@tech-leads-club

Or browse the official Anthropic plugin directory and search for agent-skills-mcp.

Manual Install (Any MCP-compatible agent)

Add the MCP server directly to your agent's config. The block below is the standard MCP format — works for most agents:

{
  "mcpServers": {
    "agent-skills": {
      "command": "npx",
      "args": ["-y", "@tech-leads-club/agent-skills-mcp"]
    }
  }
}

Claude Code (CLI)

claude mcp add agent-skills -- npx -y @tech-leads-club/agent-skills-mcp

VS Code (GitHub Copilot)

.vscode/mcp.json uses a slightly different schema:

{
  "servers": {
    "agent-skills": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tech-leads-club/agent-skills-mcp"]
    }
  }
}

⚡ Caching

The registry is fetched from jsDelivr CDN and cached in memory:

• TTL: 15 minutes — cache hit returns immediately with no network call
• ETag revalidation: on TTL expiry, sends If-None-Match; a 304 Not Modified renews the TTL without re-downloading the payload
• Cold start retry: 3 attempts with exponential backoff — server won't start if CDN is unreachable
• Stale fallback: if CDN fails after warmup, stale cache is returned rather than erroring
• All cache events are logged to stderr (never stdout — stdout is reserved for JSON-RPC)

🔒 Error Reference

| Scenario | Behaviour | | :------------------------------------- | :------------------------------------------------------------------------------ | | Registry CDN unreachable at cold start | Retries 3× with exponential backoff, then server exits with error | | Registry CDN unreachable after warmup | Stale cache returned; warning logged to stderr | | Malformed registry JSON | Logged to stderr; stale cache used if available | | skill_name not in registry | UserError: "Skill '{name}' not found. Use search_skills to find valid names." | | file_paths contains invalid path | UserError listing all invalid paths — no files fetched | | search_skills with empty query | UserError: "Query cannot be empty" | | One parallel file fetch fails | Partial success: successful files returned, failed path noted in output |

🧪 Development

From the repo root:

npm run build              # Build all (or: npx nx build @tech-leads-club/agent-skills-mcp)
npx nx lint @tech-leads-club/agent-skills-mcp
npx nx test @tech-leads-club/agent-skills-mcp
npm run start:dev:mcp      # Build MCP and open Inspector

From packages/mcp:

npx nx build @tech-leads-club/agent-skills-mcp
npx nx lint @tech-leads-club/agent-skills-mcp
npx nx test @tech-leads-club/agent-skills-mcp
npm run start:dev          # Build + Inspector (uses ../../dist/packages/mcp)

⚙️ Requirements

• Node.js ≥ 24

📄 License & repo

MIT — Tech Leads Club. Same repo as the CLI and the skills catalog.