init-agent-config（初始化 Agent 配置）

Init Agent Config

Build AGENTS-first instruction systems from repo evidence. AGENTS.md is the source of truth for how agents should work. REVIEW.md is the standardization layer for what changes should be scrutinized or blocked during review. Explore the repository in waves, write root plus folder-scoped AGENTS.md files, then finish with a repo-grounded review context layer and any needed native adapters.

Default Claude compatibility model: every finalized AGENTS.md gets a sibling CLAUDE.md symlink. If the environment cannot preserve symlinks, fall back to a one-line wrapper and call out the exception in your response.

Use this skill for

• creating new root and folder-scoped AGENTS.md files from real repo evidence
• creating or tightening a repo-grounded REVIEW.md standardization layer after the AGENTS hierarchy is done
• auditing or tightening existing agent instructions before rewriting them
• migrating CLAUDE.md, .cursorrules, Copilot, Gemini, or mixed agent config into an AGENTS-first layout
• building nested instruction boundaries for src/, packages, apps, services, or docs areas
• coordinating multi-agent exploration before instruction writing

Do not use this skill for

• reviewing a PR directly
• writing generic "AI coding guidelines" without inspecting a real repository
• runtime subagent orchestration unrelated to repo instruction files -> use the matching orchestration skill

Review context and native adapters

The main job is still AGENTS standardization, but every finished repo should also get a review-context layer. Treat REVIEW.md as mandatory. Treat platform-native review adapters as configurable last-step outputs driven by the completed AGENTS.md + REVIEW.md pair.

Keep the split clear:

Quick boundary:

• AGENTS.md = how to work
• REVIEW.md = what to scrutinize in changes
• native review adapters = platform-specific translations of the review context

Non-negotiables

• Inspect the repository before drafting anything.
• AGENTS.md comes first. Agent-specific files come after the AGENTS hierarchy exists.
• REVIEW.md comes after the AGENTS hierarchy, not before it.
• Do not ask about Copilot, Devin, or Greptile adapters until both the AGENTS.md hierarchy and REVIEW.md are complete.
• Every project should leave this skill with a useful review-context layer, even if it never adopts a PR review tool.
• Native review adapters are configurable last-step outputs, not the default deliverable.
• Use wave-based discovery: broad architecture first, folder architecture second, writing only after both waves are merged.
• If the environment supports explorer subagents, use up to 10 across the discovery waves.
• Explorer prompts must be substantive: minimum 500 words, maximum 2500 words.
• Writer prompts may be more detailed, but cap them at 5000 words.
• Default folder rule: create root AGENTS.md plus a local AGENTS.md for each meaningful src subfolder discovered in Wave 2. If a src tree has first-level folders, each first-level folder should end with its own AGENTS.md unless repo evidence proves there is no distinct workflow there.
• Every folder-level AGENTS.md must answer the question: What does a coder working in this folder need to know to avoid mistakes here?
• The root REVIEW.md must answer: What kinds of changes should be flagged or scrutinized because they break this repo's intended standards or risk boundaries?
• After each AGENTS.md is finalized, create sibling CLAUDE.md as a symlink to it. If symlinks are impossible in the target environment, fall back to a one-line wrapper and call out the exception in your response.
• Verify commands and paths against real files; never invent them.
• Keep universal guidance in AGENTS.md. Keep agent-native syntax and features out of AGENTS.md.
• Keep review criteria in REVIEW.md. Do not hide diff-review rules inside AGENTS.md unless the repo already uses that pattern and you are preserving it intentionally.
• 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).
• For existing files, output the audit/quality report before applying updates unless the user explicitly skips the audit phase.

Anti-derail guardrails

• Do not write from templates before discovery is complete.
• Do not skip Wave 2 just because Wave 1 already found the stack.
• Do not let writer agents start from partial findings.
• Do not duplicate root rules in child AGENTS.md files.
• Do not let REVIEW.md turn into a second copy of AGENTS.md.
• Do not keep universal content trapped inside CLAUDE.md or any other agent-native file.
• Do not grow CLAUDE.md into a second source of truth. Keep Claude-only behavior in .claude/ or other native surfaces.
• Do not create support files only because an agent supports them; create them only when discovery proves they are useful.
• Do not create shared defaults in AGENTS.override.md or CLAUDE.local.md; those are override/personal layers.
• If existing config is already mostly correct, switch from rewrite mode to audit/tighten mode.

Workflow

1) Scope the request and current instruction surfaces

Classify the job before reading deeply.

Check which instruction surfaces already exist:

• AGENTS.md, nested AGENTS.md, AGENTS.override.md
• REVIEW.md, nested REVIEW.md
• CLAUDE.md, .claude/, GEMINI.md, .gemini/
• .cursor/rules/, .cursorrules, .windsurfrules
• .github/copilot-instructions.md
• .greptile/, greptile.json
• README.md, CONTRIBUTING.md, architecture docs

2) Build the folder map locally

Use the filesystem before dispatching explorers.

• Run tree -d. or tree -dL 2. to map top-level and src folders.
• Mark candidate instruction boundaries: repo root, each src/*, each app/package/service root, and any docs/standards subtree with separate workflows.
• Decide which folders will get dedicated exploration coverage.
• Do not draft yet. This step exists so Wave 2 can be assigned cleanly.

3) Wave 1 exploration: broad architecture

Wave 1 answers the repo-wide questions before folder specialization begins.

Goal

• identify architecture shape, command sources, critical workflows, major boundaries, and existing instruction debt

Agent count

• 2 to 10 explorer agents, depending on repo size and how many independent questions exist

Required outputs

• repo-wide command sources and verified entrypoints
• top-level architecture map
• existing instruction files and conflicts
• candidate folders that need their own AGENTS.md
• candidate folders that may need scoped REVIEW.md
• risks, unknowns, and questions to resolve in Wave 2

Wave 1 prompt template Use a 500-2500 word prompt built from this scaffold:

You are Wave 1 of an AGENTS-first repo-instruction discovery pass.

Mission:
Map the repository at a broad architectural level so the main agent can design an AGENTS.md hierarchy before any writing begins.

Repository:
- Root: <repo path>
- Current tree snapshot: <paste `tree -dL 2 .` or equivalent>
- Existing instruction surfaces: <list any AGENTS.md, CLAUDE.md, .claude, Copilot, Cursor, Gemini, README, CONTRIBUTING files already found>

What you must discover:
1. The repo's real command sources and which commands are verified versus missing.
2. The top-level architecture, major folders, and which areas appear to have distinct workflows or risks.
3. Existing agent-instruction files, duplicated guidance, stale guidance, or CLAUDE-first anti-patterns.
4. Which folders are strong candidates for local AGENTS.md files, especially under `src/`, `apps/`, `packages/`, `services/`, or similar roots.
5. What a future folder-level writer would need to know before drafting local instructions.
6. Which review-critical areas should later become the backbone of `REVIEW.md`.

How to work:
- Read only enough repo evidence to support claims.
- Separate documented facts from inference.
- Cite exact file paths for every important claim.
- Call out conflicts between files.
- Do not write AGENTS.md yet.
- Do not propose generic best practices.
- Focus on information that prevents mistakes.

Deliverable:
Produce a concise architecture brief with:
- verified commands and their sources
- repo-wide boundaries
- candidate AGENTS.md folders
- candidate review-critical areas
- missing information that must be resolved in Wave 2
- risks if the main agent writes before deeper folder exploration

Wait for all Wave 1 findings. Compare overlap, contradictions, and gaps before moving on.

4) Wave 2 exploration: folder-specific deep dives

Wave 2 uses the folder map plus Wave 1 findings to inspect the inner folders that will actually receive local instructions.

Trigger

• launch only after Wave 1 has been merged and the main agent knows which folders need local coverage

Assignment model

• base assignments on tree -d. or tree -dL 2.
• give each explorer one folder or one tightly-related cluster
• default coverage includes every meaningful src first-level subfolder

Required outputs

• folder-local commands or workflows
• local architecture and entry points
• conventions, risks, boundaries, and non-obvious WHY context
• exact recommendation for that folder's AGENTS.md
• exact recommendation for whether that folder needs scoped review guidance
• whether the folder needs additional agent-native files beyond the default CLAUDE.md symlink

Wave 2 prompt template Use a 500-2500 word prompt built from this scaffold:

You are Wave 2 of an AGENTS-first repo-instruction discovery pass.

Mission:
Investigate one subtree deeply enough that the main agent can write a local AGENTS.md for that folder without guessing.

Assigned subtree:
- Folder: <folder path>
- Parent/root context: <one paragraph from Wave 1 summary>
- Tree excerpt: <paste relevant lines from `tree -d .` or `tree -dL 2 .`>

What you must answer for this folder:
1. What does a coder working in this folder need to know before making changes here?
2. Which commands, entry points, or test workflows are local to this folder?
3. Which patterns are non-obvious and would cause mistakes if omitted?
4. Which rules belong in the parent AGENTS.md instead of this folder file?
5. Which changes in this folder deserve special scrutiny in review?
6. Should this folder also receive a sibling `CLAUDE.md` symlink and any extra native agent files?

How to work:
- Read only files that materially improve the folder brief.
- Ground every rule in repo evidence.
- Prefer local conventions over generic advice.
- Distinguish facts from inference.
- Avoid repeating parent-level instructions unless the folder overrides them.
- Do not write the final AGENTS.md file. Hand the main agent the evidence needed to write it.

Deliverable:
Return a folder brief with:
- the folder's purpose
- local commands and boundaries
- non-obvious patterns plus WHY
- content that must appear in this folder's AGENTS.md
- content that must stay in the parent file
- content that should later shape the review-context layer
- unresolved unknowns that still block writing

Wait for all Wave 2 findings. Merge overlaps and resolve contradictions before writing.

5) Synthesize the AGENTS hierarchy before writing

Translate the discovery findings into a file plan.

• Root AGENTS.md carries repo-wide commands, architecture, shared conventions, and top-level boundaries.
• Each folder AGENTS.md carries only what is local to that subtree.
• Child files may assume the parent already provided global rules.
• If a folder needs only a small local delta, keep that file short rather than folding it back into the root.
• If a src folder has first-level subfolders, default to one local AGENTS.md per first-level subfolder.
• Each planned file should have a one-sentence purpose before writing begins.

6) Audit existing files before rewriting them

Use references/audit-and-migration.md when the repo already has agent instructions.

• find all existing instruction and wrapper files
• score them before editing
• show the report first
• then propose targeted changes, migrations, or deletions

Use this output structure for audit work:

1. ## Agent Instructions Quality Report
2. summary counts and average score
3. file-by-file scores with concrete evidence
4. recommended changes
5. apply edits only after the report step unless the user explicitly waives it

7) Draft AGENTS.md files

Write the hierarchy from the top down.

• Use the WHAT / WHY / HOW filter from references/agents-md-format.md.
• Prefer direct instructions and measurable boundaries.
• Keep root and child files lean.
• Create a section only when 3+ repo-specific facts justify it.
• Ask while drafting: Would a coder editing this folder make a mistake if this line were missing?
• If the answer is no, cut the line.

8) Create companion entrypoints after AGENTS.md exists

After the AGENTS hierarchy is stable:

• create sibling CLAUDE.md as a symlink to the corresponding AGENTS.md
• if symlink creation is impossible, use a one-line wrapper: @AGENTS.md
• keep Claude-only behavior in .claude/ rather than expanding CLAUDE.md
• point Gemini, Copilot, Aider, Cursor, or other agent-native surfaces back to the AGENTS source of truth unless they genuinely need agent-only behavior

See references/agent-entrypoints.md.

9) Writer-agent pass

After both discovery waves are merged, the main agent may dispatch writers.

Rules

• writers get disjoint folder ownership
• writer prompts may be longer than explorer prompts, but must stay under 5000 words
• a writer prompt must include the relevant wave findings for that folder, the target file path, the parent-child boundary, and the question What does a coder working in this folder need to know?
• do not send a writer until the main agent has all needed context from both discovery waves

Writer prompt scaffold Expand this scaffold with repo-specific findings, up to 5000 words:

You are the writer for one folder in an AGENTS-first instruction hierarchy.

Ownership:
- Target file: <path/to/AGENTS.md>
- Folder scope: <folder>
- Parent instruction file: <parent AGENTS path>
- Companion entrypoint policy: create `CLAUDE.md` as a symlink to this AGENTS.md after the content is finalized

Context you must use:
- Repo summary from Wave 1: <insert synthesized summary>
- Folder brief from Wave 2: <insert subtree findings>
- Existing files to preserve or tighten: <list>
- Verified commands and paths: <list>

Writing objective:
Produce the smallest high-signal AGENTS.md that tells a coder working in this folder exactly what they need to know here and nothing they already know from the parent file.

Requirements:
- Keep only folder-local instructions.
- Preserve valid warnings and boundary rules.
- Ground every rule in evidence.
- Include commands only if they are verified and local to this folder.
- Do not duplicate parent instructions.
- Prefer imperative, measurable language.
- Call out non-obvious WHY context where it prevents mistakes.
- If the folder truly has minimal unique guidance, write a short local AGENTS.md rather than skipping the file.

Deliverable:
Return the final AGENTS.md content plus any notes the main agent needs before creating the companion `CLAUDE.md` symlink.

10) Generate the review-context layer

After the AGENTS hierarchy is written, draft the review-context layer from the same repo evidence.

Purpose

• standardize what kinds of diffs should be flagged
• encode repo-specific code standards that matter during review
• capture the places where AI agents may act outside intended architectural or safety bounds
• strengthen future AGENTS updates by forcing the repo's risk model to be explicit

Default outputs

• root REVIEW.md
• scoped REVIEW.md files only when a subtree has review risks or standards that diverge materially from the root

Split of responsibility

• AGENTS.md = how to work and where things belong
• REVIEW.md = what to flag, protect, or verify in diffs

Review-writing rules

• use repo evidence, not generic best practices
• keep rules specific, measurable, actionable, and semantic
• put highest-risk rules first
• skip anything already enforced by lint, format, or deterministic tooling
• prefer 5-10 strong rules over a long checklist
• use scoped REVIEW.md only when the root file would become contradictory or bloated

Suggested section order for root REVIEW.md

• ## Critical Areas
• ## Security
• ## Conventions
• ## Performance
• ## Patterns
• ## Ignore
• ## Testing

After drafting review context

• compare it back against the AGENTS hierarchy
• if the review pass exposed missing boundaries or safety rules, update the relevant AGENTS.md files
• keep the two surfaces complementary rather than duplicative

11) Validate before finalizing

Check all of the following:

• root and folder AGENTS.md files exist where the wave plan said they should
• each created CLAUDE.md points to the correct sibling AGENTS.md, or the fallback wrapper is documented as an exception
• root REVIEW.md exists and reflects the repo's real risk areas
• scoped REVIEW.md files exist only where the repo truly needs them
• commands and paths are verified
• child AGENTS.md files do not restate root rules unnecessarily
• REVIEW.md rules are specific, reviewable, and not duplicates of linter rules
• agent-specific files do not become a second source of truth
• unresolved unknowns are called out in your response, not buried in the files

12) Final configurable step: ask which native review adapters to generate

Only after Step 11 passes, ask one concise question about platform adapters.

Use this exact question pattern: The AGENTS.md and REVIEW.md hierarchy is complete. Which native review adapters should also be generated for this repo: Copilot, Devin, Greptile, or none?

Rules for this step:

• ask only after both AGENTS and REVIEW are done
• the generic review-context layer is not optional; only the platform adapters are configurable
• if the user says none, stop
• if the user names one or more platforms, generate the matching native adapter files in this same skill
• if the user says all, still confirm the repo actually uses them before writing files
• treat platform-native review files as translations of the completed review context, not as a separate source of truth

Adapter defaults:

• Copilot -> generate .github/copilot-instructions.md plus scoped .github/instructions/*.instructions.md; keep files below the platform limit and note base-branch behavior
• Devin -> keep REVIEW.md as the main review surface, add scoped REVIEW.md only where needed, and reuse the completed AGENTS.md hierarchy for coding behavior
• Greptile -> generate .greptile/config.json plus optional rules.md and files.json; keep scope as arrays, ignorePatterns as a newline string, and note source-branch behavior

Steering experiences

These are common mistakes observed during real-world execution. See references/agents-md-format.md for the detailed authoring and derailment guidance behind them.

Do this, not that

Reference routing

Read the smallest reference set that unblocks the current decision:

Quick-start mapping

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 AGENTS hierarchy and why it fits the repo
2. the folder map or tree excerpt that drove the hierarchy
3. the audit report first when existing files were present
4. the review-context outputs and how they complement the AGENTS hierarchy
5. the created or updated files, including any symlinked companion entrypoints and configured review adapters
6. remaining unknowns or follow-up checks in your response text, not inside the instruction files