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

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

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/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.