claude-code-integration.mdx

title	Claude Code Integration
description	Integrate FastSkill with Claude Code for intelligent skill discovery.

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 project install

# ...or configure a catalog and add one directly
fastskill repo add team --repo-type git-marketplace https://github.com/your-org/skills.git
fastskill skill add scope/pptx@1.0.0 --repository team

# Verify what Claude Code will see
fastskill skill list

That's it — the next time Claude Code runs in this project, the installed skills are available.

How it works

1. fastskill project install / fastskill skill 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 skill read <skill-id> to see exactly what an agent loads, or fastskill skill 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://github.com/gofastskill/fastskill/releases/latest/download/install.sh | FASTSKILL_UNMANAGED=1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Install skills from lock
        run: fastskill project install --lock
      - name: Verify
        run: fastskill skill list

Troubleshooting

Claude Code doesn't see a skill: Confirm it is installed with fastskill skill list, and that the skills directory contains a valid SKILL.md for it. fastskill skill 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 under [tool.fastskill] in skill-project.toml 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 — the read-only ones only. Mutating tools (fastskill_project_install, fastskill_skill_add, fastskill_skill_remove, …) require mcp serve --enable-write; see Write access.

HTTP API

fastskill server 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.

See the agent’s skill documentation for native discovery behavior.