ai-context-kit

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:

1. Create/edit the source at .ai/skills/<name>/SKILL.md — this is the only file you touch.
2. 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.
3. 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       # regenerate outputs — always run this after editing .ai/
ai-context verify      # CI-friendly: fails if outputs are stale
ai-context doctor      # diagnose config / mirror issues

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.