ai-kit

Your AI skills and MCP servers, in one repo.

Centralize your Agent Skills and MCP server configs in a single git repo. Install them to Claude Code, Codex, Pi, or OpenCode — per-repo or globally — with one command.

---

Why

You use multiple AI coding tools. Each has its own config format and file locations. You've got skills scattered across repos, MCP configs copy-pasted between projects, and no single source of truth.

ai-kit is a personal monorepo for all of it:

your-ai-kit/
├── skills/
│   ├── writing-style/SKILL.md       # your skills
│   ├── frontend-design/SKILL.md     # third-party skills
│   └── ...
├── mcps/
│   ├── playwright.json              # external MCP configs
│   └── ...
├── servers/
│   └── image-gen/index.ts           # your own MCP servers
└── package.json

One ai-kit install claude and everything lands in the right place.

How it works

┌─────────────────────────────────────────────────────────────┐
│                         ai-kit repo                         │
│                                                             │
│  skills/               mcps/                servers/        │
│  ├── writing-style/    ├── playwright.json  ├── image-gen/  │
│  ├── humanizer/        └── context7.json                    │
│  └── frontend-design/                                       │
└───────────────┬─────────────────────────────┬───────────────┘
                │       ai-kit install        │
         ┌──────┴──────┐               ┌──────┴──────┐
         │  per-repo   │               │   global    │
         └──────┬──────┘               └──────┬──────┘
                │                             │
       ┌────────┼────────┐        ┌──────┬────┴────┬──────┐
       ▼        ▼        ▼        ▼      ▼         ▼      ▼
    Repo A   Repo B   Repo C   Claude  Codex   OpenCode   Pi

Skills use the Agent Skills standard — a SKILL.md format natively supported by Claude Code, Codex, Pi, Cursor, Gemini CLI, and 30+ other tools.

Quick start

1. Fork or clone

# Fork this repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/ai-kit.git ~/ai-kit
cd ~/ai-kit
bun install && bun link

Requires Bun. Zero runtime dependencies.

2. Add your skills

# Create a new skill from template
ai-kit add skill writing-style

# Or grab one from the skills.sh ecosystem
ai-kit add skill frontend-design --from anthropics/skills

3. Add your MCPs

# Create a new MCP config from template
ai-kit add mcp playwright

Then edit mcps/playwright.json. Local stdio MCPs look like this:

{
  "description": "Browser automation with Playwright",
  "config": {
    "command": "npx",
    "args": ["-y", "@playwright/mcp"]
  }
}

Remote HTTP MCPs work too:

{
  "description": "Documentation search",
  "config": {
    "url": "https://mcp.example.com/docs"
  }
}

Keep committed MCP configs secret-free. Use ${VAR} placeholders for machine-local secrets and paths:

{
  "description": "Analytics MCP",
  "config": {
    "url": "https://mcp.example.com/analytics",
    "headers": {
      "Authorization": "Bearer ${ANALYTICS_API_TOKEN}"
    }
  }
}

4. Write your own MCP servers

For services that don't have an MCP server, write one directly in the repo using FastMCP:

ai-kit add server image-gen

This scaffolds servers/image-gen/index.ts with a FastMCP boilerplate. Add your tools:

import { FastMCP } from "fastmcp";
import { z } from "zod";

const server = new FastMCP("image-gen");

server.addTool({
  name: "generate_image",
  description: "Generate an image from a text prompt",
  parameters: z.object({
    prompt: z.string().describe("What to generate"),
  }),
  execute: async ({ prompt }) => {
    // call your image API here
    return "image generated";
  },
});

server.start({ transportType: "stdio" });

When you run ai-kit install, local servers are installed with their absolute path resolved automatically — no extra config needed.

5. Install to your tools

# Install to Claude Code in the current repo
ai-kit install claude

# Install globally
ai-kit install claude --global

# Install to Codex, Pi, or OpenCode
ai-kit install codex
ai-kit install pi
ai-kit install opencode

# Cherry-pick what you need
ai-kit install claude --skills writing-style,humanizer --mcps playwright

That's it. Commit your repo, and you have a portable, versioned collection of AI skills and MCP configs.

Secret-free MCP configs

ai-kit treats the files in mcps/ as the canonical source of truth. Keep them portable and secret-free:

• Use exact ${VAR} placeholders for env values, headers, and machine-local paths
• Use Authorization: "Bearer ${VAR}" for bearer-token HTTP auth
• Don't commit real API keys, passwords, or local credential file paths

Example stdio MCP with secret placeholders:

{
  "description": "Example service",
  "config": {
    "command": "npx",
    "args": ["-y", "example-mcp-server"],
    "env": {
      "SERVICE_USERNAME": "${SERVICE_USERNAME}",
      "SERVICE_PASSWORD": "${SERVICE_PASSWORD}",
      "CREDENTIALS_FILE": "${CREDENTIALS_FILE}"
    }
  }
}

At install time, ai-kit renders those placeholders into each target's native config format:

• Claude Code: ${VAR} is written through as-is
• OpenCode: ${VAR} becomes {env:VAR}
• Codex: stdio env placeholders become env_vars; HTTP header placeholders become env_http_headers; bearer auth becomes bearer_token_env_var
• Pi: no MCP support

Only two placeholder forms are supported in committed MCP JSON:

• Exact ${VAR}
• Bearer ${VAR}

Other interpolation forms like prefix-${VAR} or /path/${VAR}/file.json are intentionally not supported.

Where things land

Both skills and MCPs (including local servers) support two install scopes:

• Per-repo (default) — installed into the current project directory. Only available when working in that repo.
• Global (--global) — installed into your home directory. Available in every project.

Per-repo (default)

Target	Skills	MCPs
Claude	.agents/skills/<name>/SKILL.md	.mcp.json
Codex	.agents/skills/<name>/SKILL.md	.codex/config.toml
Pi	.agents/skills/<name>/SKILL.md	—
OpenCode	.opencode/skills/<name>/SKILL.md	opencode.json

Global (--global)

Target	Skills	MCPs
Claude	~/.claude/commands/<name>.md	~/.claude/settings.json
Codex	~/.agents/skills/<name>/SKILL.md	~/.codex/config.toml
Pi	~/.pi/agent/skills/<name>/SKILL.md	—
OpenCode	~/.config/opencode/skills/<name>/SKILL.md	~/.config/opencode/opencode.json

You can mix both — install some skills globally and others per-repo. ai-kit sync re-installs to all tracked locations.

All commands

Command	What it does
ai-kit install <target>	Install skills + MCPs to a target
ai-kit install <target> --global	Install globally instead of per-repo
ai-kit install <target> --skills a,b	Install only specific skills
ai-kit install <target> --mcps x,y	Install only specific MCPs
ai-kit list	List all available skills and MCPs
ai-kit add skill <name>	Scaffold a new skill
ai-kit add skill <name> --from <source>	Fetch a skill from the ecosystem
ai-kit add mcp <name>	Scaffold a new MCP config
ai-kit add server <name>	Scaffold a local MCP server (FastMCP)
ai-kit update	Re-fetch all third-party skills
ai-kit update <name>	Re-fetch a specific third-party skill
ai-kit detach <name>	Detach a skill from its upstream source
ai-kit sync	Re-install to all previously tracked targets

Third-party skills

Not every skill is yours — some come from other people's repos. ai-kit tracks where they came from so you can update them later when the original author makes changes.

# Add a third-party skill
ai-kit add skill frontend-design --from anthropics/skills

# Update all third-party skills from their origins
ai-kit update

# Update a specific one
ai-kit update frontend-design

# Third-party skills are marked in the list
ai-kit list

# Customized a skill? Detach it so update won't overwrite your changes
ai-kit detach frontend-design

Under the hood this uses Vercel's skills CLI to fetch the skill. --from accepts any source format supported by that CLI, including GitHub shorthand like anthropics/skills and full URLs like https://github.com/anthropics/skills. A source.json is saved alongside the SKILL.md to record the origin. Running ai-kit detach <name> removes that source.json, converting it to a local skill that update will skip.

Browse available third-party skills at skills.sh.

Design

• Copy, not symlink — portable across Docker, CI, and tools that don't follow symlinks
• Merge, not overwrite — MCP configs are merged into existing JSON/TOML, preserving your other entries
• Safe per-server merge — ai-kit only overrides the target-native MCP keys it emits for a given server, preserving unrelated local metadata in that same server entry
• Secret-free MCP placeholders — commit ${VAR} references once, then render them to each harness at install time
• Agent Skills standard — SKILL.md works across 30+ tools without conversion (Claude global commands are the one exception — the CLI handles it)
• Local MCP servers — write your own with FastMCP, paths resolved automatically at install time

Using as a template

This repo is designed to be forked:

1. Fork this repo to your GitHub
2. Clone and run bun install && bun link
3. Delete the example skills/MCPs/servers (or keep the ones you want)
4. Add your own skills, MCPs, and local servers
5. Commit and push — your AI toolkit is now versioned and portable

When you set up a new machine, clone your fork and run ai-kit install claude --global to get everything in place.

Contributing

PRs welcome. If you add a new install target, drop it in src/targets/ and register it in src/install.ts.

bun test          # run all tests
bun test --watch  # watch mode

License

MIT