AI Skills Server

MCP server that compiles ai-skills skill definitions and serves them to AI agents over the Model Context Protocol. Skills are bundled — zero config required.

npx ai-skills-mcp start

Register in your MCP client config:

{
  "mcpServers": {
    "ai-skills": {
      "command": "npx",
      "args": ["ai-skills-mcp", "start"]
    }
  }
}

How the AI Uses Skills

Skills are not automatically injected into the AI's context. The MCP server exposes tools that the AI chooses to call. The typical flow:

1. AI receives a task (e.g. "install python dependencies")
2. AI calls pack_context("install python dependencies") — the server finds relevant skills (uv, anti-global-install, etc.), resolves their transitive dependencies, and returns packed skill content within token limits
3. AI reads the returned skill instructions and follows them

This requires the AI to know about pack_context. See docs/ai-workflow.md for setup guidance and the skill-loader skill which teaches this pattern.

Commands

Command	Description
start	Start MCP server (stdio or SSE)
compile	Compile skills and save registry
list	List all compiled skills

start flags

Flag	Default	Description
-d, --skills-dir	(bundled)	Override path to skills directory
-t, --transport	stdio	stdio or sse
-p, --port	3000	Port for SSE transport
-r, --registry	registry.json	JSON registry path
--sqlite <path>	—	Use SQLite registry instead of JSON
--no-registry	—	Skip registry persistence

MCP Tools

Tool	Description
list_skills	List all compiled skills
get_skill	Get full compiled skill by name
search_skills	Search skills by keyword
resolve_dependencies	Get dependency graph for a skill
pack_context	Build a context pack for a task
get_dependents	Find skills that reference a given skill
get_stats	Registry statistics

MCP Resources

URI	Description
skill://{name}	Full compiled skill
skill://{name}/deps	Dependencies of a skill
skill://{name}/dependents	Skills that reference this one

Documentation

Doc	Description
docs/ai-workflow.md	How the AI discovers and uses skills
docs/how-it-works.md	Compiler, resolver, packer internals
docs/architecture.md	Project design and data flow
docs/api.md	Full MCP tool and resource reference
docs/skill-format.md	How to write a SKILL.md
docs/project-scope.md	Scope, limitations, roadmap

Architecture

flowchart LR
  Skills["skills/"] --> Compiler["SkillCompiler"]
  Compiler --> Resolver["DependencyResolver"]
  Compiler --> Packer["ContextPacker"]
  Compiler --> Registry["Registry"]
  Resolver --> MCP["MCP Server"]
  Packer --> MCP
  Registry --> MCP
  MCP --> Tools["7 tools"]
  MCP --> Resources["3 resource URIs"]

  style Skills fill:#1a1a2e,color:#eee
  style Compiler fill:#4a90d9,color:#fff
  style Resolver fill:#50b86c,color:#fff
  style Packer fill:#e6a020,color:#fff
  style Registry fill:#9b59b6,color:#fff
  style MCP fill:#1abc9c,color:#fff
  style Tools fill:#34495e,color:#eee
  style Resources fill:#34495e,color:#eee

See docs/architecture.md for the full import graph and docs/how-it-works.md for the pipeline.

Transports

• stdio (default) — Claude Desktop, Cursor, etc.
• SSE — remote deployments: --transport sse --port 3000

Registries

• JSON (default) — file-based, easy to debug
• SQLite — persistent, queryable: --sqlite ./registry.db
• Memory — ephemeral, --no-registry

Development

npm install
npm run build
npm start -- --no-registry
npm test