Init Agent Config

Generate agent configuration that reflects the actual repository, not a generic template. Use AGENTS.md for universal cross-agent guidance. Use CLAUDE.md for Claude Code memory and Claude-only features. When both are needed, AGENTS.md is the shared source of truth and CLAUDE.md stays thin.

Use this skill for

• creating new AGENTS.md and/or CLAUDE.md from repo evidence
• tightening noisy or stale agent config
• migrating standalone CLAUDE.md into a dual-file setup
• extracting universal project rules from .cursorrules, copilot-instructions.md, or other agent config
• designing repo-level plus monorepo/package-level instruction boundaries

Do not use this skill for

• .github/copilot-instructions.md or *.instructions.md review config -> use init-copilot-review
• REVIEW.md or Devin-specific review setup -> use init-devin-review
• Greptile config setup -> use init-greptile-review
• writing generic "AI coding guidelines" without inspecting a real repository

Non-negotiables

• Inspect the repository before drafting anything.
• Verify commands and paths against real files; never invent them.
• Keep universal guidance in AGENTS.md. Keep Claude-only syntax and features out of AGENTS.md.
• Complement existing config; do not blindly replace it.
• Preserve existing Always, Ask, Never, WARNING, CRITICAL, and DO NOT rules unless the repo proves they are obsolete.
• Prefer high-signal directives over long prose. If a line would not prevent a mistake, cut it from the config file (the instruction, not the repo).

Anti-derail guardrails

• If the draft starts to read like a generic style guide, stop and replace broad advice with repo-specific facts or remove it.
• Do not create shared defaults in AGENTS.override.md or CLAUDE.local.md; those are override/personal layers.
• Do not invent .claude/, agent_docs/, or nested AGENTS.md structure without a concrete repo need.
• If the correct agent surface is unclear, default to the smallest verified setup and explain the tradeoff instead of emitting speculative extra files.
• If existing config is already mostly correct, switch from rewrite mode to audit/tighten mode.
• Do not reference .claude/rules/ in the thin wrapper unless you are actually creating rule files or the directory already exists. See steering experience S-01.

Workflow

1) Scope the request first

Classify the job before reading deeply. A quick file-existence check (e.g., ls AGENTS.md CLAUDE.md .cursorrules 2>/dev/null) is allowed here to inform scoping -- deep reads happen in Step 2.

Then determine the agent surface actually in use:

If the user mentions another agent-specific file (.cursorrules, GEMINI.md, .github/copilot-instructions.md, etc.), treat it as input to mine rules from unless they explicitly want that format as output.

2) Inspect the repository before drafting

Read only enough to ground the config. Work through tiers in order; stop when you have (1) verified commands, (2) identified non-obvious conventions, and (3) found architecture boundaries. Only proceed to the next tier if a specific convention needs deeper evidence.

Tier 1 -- Scan: Existing agent and contributor docs

• AGENTS.md, AGENTS.override.md
• CLAUDE.md, CLAUDE.local.md, .claude/rules/, .claude/settings.json
• .cursorrules, .windsurfrules, GEMINI.md
• .github/copilot-instructions.md
• README.md, CONTRIBUTING.md

Tier 2 -- Extract: Command sources

• package.json scripts
• Makefile / Justfile
• pyproject.toml
• Cargo.toml, .cargo/config.toml
• CI workflows in .github/workflows/

Tier 3 -- Map: Repo structure and tech-stack anchors

• framework/tool configs (tsconfig.json, next.config.*, go.mod, docker-compose.yml, workspace manifests)
• monorepo layout, package/service boundaries, non-standard directories

Tier 4 -- Mine: Code-level evidence for non-obvious rules

• validate only conventions agents would not reliably infer on their own
• capture WHY when the repo encodes an intentional trade-off

Stopping condition: Stop after completing a tier if no new actionable facts emerged from it. Do not continue to Tier 4 "just to be thorough."

Recovery rules

• If a command is not verified, write See [file] or mark it as [unverified].
• If an existing config file is mostly good, switch from rewrite mode to audit/tighten mode.
• If repo facts conflict across files, prefer the stricter or more current source and call out the conflict.

3) Choose the file strategy deliberately

Use the simplest setup that matches the repo:

• Standalone CLAUDE.md when the team uses Claude Code only, or Claude-specific imports/rules are the real center of gravity.
• AGENTS.md only when shared, agent-agnostic instructions are enough.
• Dual-file pattern when the repo needs both portability and Claude-specific features.

Dual-file rule:

1. Put all universal instructions in AGENTS.md.
2. Keep CLAUDE.md thin -- this is the canonical thin wrapper template:

   @AGENTS.md
   
   ## Claude-Specific
   <!-- Only add the next line if .claude/rules/ exists or you are creating rule files -->
   - See `.claude/rules/` for path-scoped rules
   - Add only Claude-only features or memory notes here
   

3. Do not copy AGENTS.md content into CLAUDE.md.

Monorepo rule (applies only when workspace config exists -- e.g., workspaces in package.json, pnpm-workspace.yaml, nx.json, lerna.json):

• Root file = universal repo-wide guidance
• Nested AGENTS.md or .claude/rules/ = package/path-specific rules
• Never dump every package-specific rule into the root file

4) Draft only high-signal instructions

Use the WHAT / WHY / HOW filter:

Create a section in the output file only when 3+ repo-specific facts justify it. Do not add a section for a single bullet point.

Every generated file should strongly prefer:

• imperative voice: Use pnpm, Run tests before commit
• measurable rules: Never edit existing migrations
• project-specific boundaries: Always, Ask, Never
• non-obvious context over generic advice

Cut aggressively -- remove from the config file any line that would not prevent a mistake:

• linter/formatter rules already enforced by tooling
• obvious facts the agent can infer from code
• copied README.md content (reference it instead)
• exhaustive file trees or dependency lists
• motivational filler like write clean code

5) Control scope and disclosure

Root config files should contain only instructions needed in most sessions.

Use progressive disclosure only when it improves signal:

• AGENTS.md -> universal shared guidance, with pointer references only
• CLAUDE.md -> may use @import or .claude/rules/
• nested AGENTS.md -> package/service-specific rules
• .claude/rules/ -> path-scoped Claude-only rules

Do not create extra support files just because the platform allows them. Add @import files, .claude/rules/, or agent_docs/ only when the repo is complex enough to justify them and the content can stay lean.

6) Audit or migrate without losing signal

Skip this step entirely for new setups -- go directly to Step 7. This step applies only when auditing or migrating existing config.

When auditing or migrating:

• preserve valid warning/boundary rules from the current files
• separate universal content from agent-specific content
• rewrite vague suggestions as direct instructions or remove them
• remove duplication between AGENTS.md and CLAUDE.md
• keep format rules strict:
  • AGENTS.md = plain markdown only, no frontmatter, no @import
  • CLAUDE.md = Claude-only memory, imports, .claude/ references allowed

If the input is noisy, extract only the lines that would cause a real mistake if missing.

7) Validate before finalizing

Check all of the following:

• commands and paths are verified against repo files; mark any remaining unknowns as [unverified]
• instructions document non-obvious repo reality, not framework defaults
• AGENTS.md contains only universal content
• CLAUDE.md contains only Claude-specific additions beyond shared guidance
• no duplicated content across both files
• file sizes stay lean
  • root AGENTS.md: ideally <80 lines
  • thin CLAUDE.md: ideally <20 lines
  • standalone CLAUDE.md: ideally <60 lines
• unresolved unknowns are called out in your response to the user, not buried in the generated files

Recovery paths for Step 7 failures:

• If a command cannot be verified -> mark [unverified] and note in response
• If file size exceeds target -> split into nested files or cut lowest-signal content
• If unknowns remain -> list them in response text with suggested follow-up actions

Steering experiences

These are common mistakes observed during real-world execution. See references/steering-experiences.md for detailed patterns with triggers and corrections.

Do this, not that

Reference routing

Read the smallest reference set that unblocks the current decision:

Quick-start mapping -- if you know the project type, start here:

Start with one or two references. Expand only if the current task truly needs more detail.

Final output expectations

When you generate or revise files, provide:

1. the chosen file strategy and why it fits this repo
2. a file tree of created/updated files
3. the actual file contents or precise edits
4. any remaining unknowns or follow-up checks -- present these in your response to the user, not inside the generated files
5. for audits, a concise score or findings summary