Skip to main content

​
Overview

Claude Code reads skills directly from the skills directory (.claude/skills/ by default). FastSkill’s job is to get the right skills onto disk and keep them reconciled with your manifest — once a skill is installed, Claude Code discovers it natively. There is no metadata file to generate or keep in sync.

​
Quick start

# Install the skills declared in skill-project.toml
fastskill install

# ...or add one directly
fastskill add scope/pptx@1.0.0

# Verify what Claude Code will see
fastskill list
That’s it — the next time Claude Code runs in this project, the installed skills are available.

​
How it works

  1. fastskill install / fastskill add materializes skills into the configured skills_directory (default .claude/skills/).
  2. Each skill is a folder containing SKILL.md plus its resources.
  3. Claude Code scans that directory and loads skills by their SKILL.md frontmatter — no export or sync step is involved.
  4. Use fastskill read <skill-id> to see exactly what an agent loads, or fastskill read <skill-id> --meta for just the metadata.

​
GitHub Actions

Keep the skills directory reconciled in CI so commits always carry the resolved skill set: 
name: Reconcile skills
on:
  push:
    paths:
      - 'skill-project.toml'
      - 'skills.lock'

jobs:
  install-skills:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install FastSkill
        run: curl -fsSL https://raw.githubusercontent.com/gofastskill/fastskill/main/scripts/install.sh | bash
      - name: Install skills from lock
        run: fastskill install --lock
      - name: Verify
        run: fastskill list

​
Troubleshooting

Claude Code doesn’t see a skill: Confirm it is installed with fastskill list, and that the skills directory contains a valid SKILL.md for it. fastskill read <skill-id> should print its content. Wrong skills directory: Claude Code and FastSkill must agree on the location. The default is .claude/skills/; override it via skills_directory in .fastskill/config.yaml or the --skills-dir flag.

​
MCP Registration

Register fastskill as an MCP server inside Claude Code with a single command: 
# Register for the current project (stdio transport, recommended)
fastskill mcp install --agent claude --stdio --scope project --overwrite

# Register globally (writes to ~/.claude.json)
fastskill mcp install --agent claude --stdio --scope global --overwrite

# Preview the config change without writing any files
fastskill mcp install --agent claude --stdio --dry-run
After running the command, reload Claude Code. The tools exposed by fastskill mcp serve --transport stdio will be callable from the agent.
Deprecated: Manually editing ~/.claude.json or .mcp.json to add a fastskill MCP entry is deprecated. Use fastskill mcp install instead.

​
HTTP API

fastskill serve exposes FastSkill’s versioned application API under /api/v1/…, for example GET /api/v1/status and GET /api/v1/skills. The old Claude-compatible /v1/skills… HTTP surface is no longer part of the public server. Use the MCP integration above for Claude Code and use /api/v1/… for HTTP clients.