| name | ai-context-kit |
| description | Use when authoring context modules, scopes, or skills in this repo; when adding new agent context; when running `ai-context build/verify/doctor`; or when an agent needs to understand how this repo's AGENTS.md / CLAUDE.md / .claude/rules / .agents/skills / .claude/skills are generated. Triggers on phrases like "add a module", "new scope", "create a skill", "ai-context build", "AGENTS.md is generated", or any question about the .ai/ directory layout. |
ai-context-kit
This repo's AGENTS.md, CLAUDE.md, .claude/rules/*.md, .agents/skills/*, and .claude/skills/* are all generated by ai-context-kit from sources under .ai/.
One rule: edit .ai/, never edit the generated outputs.
Quickstart
| You want to... | See |
|---|
| Add a new context module (lands in AGENTS.md/CLAUDE.md) | references/authoring-modules.md |
| Add a new scope (per-package context targeting) | references/authoring-scopes.md |
| Add a new skill (cross-CLI agent capability) | references/authoring-skills.md |
Understand .ai/context/manifest.json | references/manifest-schema.md |
Look up an ai-context CLI command | references/cli-commands.md |
| Pick what kind of content to put in a module vs a skill vs a rule | references/content-guide.md |
| Register an MCP server (fans out to client configs) | references/authoring-mcp.md |
Authoring workflow (read this first)
When creating or editing a skill, follow this exact sequence:
- Create/edit the source at
.ai/skills/<name>/SKILL.md — this is the only file you touch.
- Run
ai-context build from the repo root. This step is non-optional. The mirrors at .agents/skills/<name> and .claude/skills/<name> are NOT real-time-synced — they only exist after you run the build.
- Verify with
ai-context skills list — your skill should appear with mirror state symlink.
Easy mode: ai-context skills create <name> --description "..." does all three steps for you. Prefer it over manual scaffold-then-build.
What NOT to do
- Do NOT create files directly in
.agents/skills/<name>/ or .claude/skills/<name>/. Those paths are symlinks managed by the kit. Any file you write there will either be clobbered on the next ai-context build or persist as a broken non-symlink that diverges silently from the source.
- Do NOT skip
ai-context build after creating or editing a skill source. Without it, no agent CLI will discover your skill — the mirrors simply don't exist yet.
- Do NOT use
cp, ln -s, or manual mkdir on the mirror paths. Always let ai-context build manage them.
After any edit
ai-context build
ai-context verify
ai-context doctor
MCP servers (1.2+)
Register MCP servers once in .ai/mcp.json; ai-context build fans them out to each agent client's native config (Claude .mcp.json, Codex .codex/config.toml) and lists context: true servers in the AGENTS.md/CLAUDE.md catalog. See references/authoring-mcp.md.
Principles:
- One registry, many clients. Declare a server once; the build emits per-client config. Add a client by listing it in the server's
targets and manifest.mcp.clients.
- Secrets are references, never literals. Use
${VAR} in env; values resolve from .ai/secrets.local.env. ai-context verify fails if a credential literal lands in a generated file.
- Declaration is shared; auth is per-user.
project-scope servers are committed; user-scope servers are installed per-machine via ai-context mcp install <name> --user and authenticated with /mcp.
- Back a server with knowledge, not just config. Set
skill (or co-name a .ai/skills/<name>) and context: true so agents know what the tool is for.
Commands: ai-context mcp list, ai-context mcp install <name> --user, ai-context mcp setup <name>.
Directory map
| Path | What lives here | Who edits |
|---|
.ai/context/modules/*.md | Module content (composed into AGENTS.md/CLAUDE.md per target) | You |
.ai/context/scopes.json | Scope definitions: which modules go to which targets | You |
.ai/context/manifest.json | Top-level kit configuration | You |
.ai/mcp.json | MCP server registry (fans out to client configs) | You |
.mcp.json, .codex/config.toml | Per-client MCP config | Kit (generated) |
.ai/skills/<name>/ | Skill source (SKILL.md + optional references/, scripts/, assets/) | You |
.agents/skills/<name> | Symlink to .ai/skills/<name>/ — discovered by Codex, Gemini, Cursor, Goose, etc. | Kit (symlink) |
.claude/skills/<name> | Symlink to .ai/skills/<name>/ — discovered by Claude Code | Kit (symlink) |
.claude/rules/*.md | Path-glob rule files for Claude | Kit (generated) |
AGENTS.md, CLAUDE.md (root + scoped) | Aggregated context for agents | Kit (generated) |
Don't
- Don't edit generated
AGENTS.md / CLAUDE.md / .claude/rules/*.md — edits get overwritten on next ai-context build.
- Don't write skill files directly into
.agents/skills/ or .claude/skills/ — these are symlinks. Write to .ai/skills/<name>/, then run ai-context build.
- Don't commit broken symlinks in
.agents/skills/ or .claude/skills/. Run ai-context doctor to detect them.
- Don't duplicate content between a module and a skill. Modules are always-in-context summary; skills are on-demand depth.
