Generate AI Rules

Generate configuration files that help AI coding assistants work effectively with a codebase. Three targets, generated from the same analysis so they stay consistent:

1. AGENTS.md, the cross-tool standard (agents.md), read by most AI coding tools including Claude Code, Cursor, Codex, and Gemini CLI.
2. CLAUDE.md, Claude Code's project instructions file.
3. .cursor/rules/*.mdc, Cursor's scoped project rules.

Workflow

1. Determine targets and gather data

• Generate all three targets by default; the user may skip any (e.g., "skip cursor rules", "keep my existing CLAUDE.md").
• If a target file already exists and the user didn't say to regenerate it, ask whether to update it or leave it alone.
• Check <repo>/.ai/docs/ for analysis documents from the analyze-codebase skill. If present, use them as the primary source (spot-check against the code, they may be stale). If absent, offer to run analyze-codebase first, or explore the codebase directly for a quicker pass.

2. Generate the files

Shared principles for all targets:

• Accuracy: every command, path, and convention must come from the actual project. Test that commands at least look right against the manifest files (e.g., scripts in package.json, tasks in Makefile, uv run vs pip).
• Actionability: specific, executable instructions beat vague guidance. "Run uv run ruff format src/" beats "format your code".
• Conciseness: these files are loaded into every AI session, every line costs context. Only include what the AI cannot cheaply discover by reading the code: commands, non-obvious conventions, gotchas, things that have gone wrong before. Do not restate what the code structure makes obvious.
• Consistency: same terminology and architecture descriptions across all generated files.

AGENTS.md

The primary file, write it first, and write it best. Target well under 150 lines.