# AI Skills MCP Server

MCP server that compiles [`ai-skills`](https://github.com/anomalyco/ai-skills) skill definitions and serves them to AI agents over the Model Context Protocol. Skills are bundled — zero config required.

```bash
npx ai-skills-mcp start
```

Register in your MCP client config:
```json
{
  "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`](docs/ai-workflow.md) for setup guidance and the [`skill-loader`](skill://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](docs/ai-workflow.md) | How the AI discovers and uses skills |
| [docs/how-it-works.md](docs/how-it-works.md) | Compiler, resolver, packer internals |
| [docs/architecture.md](docs/architecture.md) | Project design and data flow |
| [docs/api.md](docs/api.md) | Full MCP tool and resource reference |
| [docs/skill-format.md](docs/skill-format.md) | How to write a SKILL.md |
| [docs/project-scope.md](docs/project-scope.md) | Scope, limitations, roadmap |

## Architecture

```mermaid
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](docs/architecture.md) for the full import graph and [docs/how-it-works.md](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

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