Agent Init#

Two-phase workflow for generating a comprehensive AGENTS.md (or updating an existing CLAUDE.md) for any project:

1. Phase 1 — Run /init to produce raw project intelligence
2. Phase 2 — Restructure that output into the 9-section universal template, adapting all tech-specific references to what the project actually uses

Why This Structure#

A well-structured AGENTS.md is the "onboarding doc" for AI agents. The 9-section template ensures every agent gets consistent context: what the project is, how to build and run it, what conventions to follow, and where to find deeper docs. Raw /init output tends to be uneven — it lists files well but misses conventions, workflows, and cross-references. Phase 2 fixes that.

---

Phase 1: Base Analysis#

Run /init in the project root. This analyzes the codebase and writes a preliminary CLAUDE.md.

• If a CLAUDE.md or AGENTS.md already exists, /init incorporates existing content
• The output is a starting point — expectations: file tree, dependency list, build file detection
• Do not skip this phase even if the project looks simple; the analysis provides useful raw material

Phase 2: Restructure into Universal Template#

Read the CLAUDE.md that /init produced, then rewrite it into the target AGENTS.md following the template below.

Information Sources (use all three)#

1. From /init output — file tree, dependencies, detected frameworks
2. From project inspection — read key config files, source layouts, existing docs to verify and supplement
3. From inference — conventions implied by the stack (e.g., Maven → mvn test, npm → npm test)

Core Principle#

Adapt the template to the project, not the project to the template. If the template says "Spotless" but the project uses ESLint, write ESLint. If the template assumes a backend but the project is frontend-only, merge the architecture sections.

Target Filename#

• AGENTS.md already exists → update it in-place
• Only CLAUDE.md exists → update it in-place (preserve filename to avoid breaking existing references)
• Neither exists → create AGENTS.md

Language#

Match the language of the project's existing documentation (README, comments). For Chinese projects, write in Chinese. When uncertain, default to Chinese.

When Information Is Missing#

Mark genuinely unavailable sections with <!-- TODO: 待补充 — <reason> -->. Never fabricate doc links, command names, or conventions. An honest TODO is better than a wrong instruction.

---

9-Section Universal Template#

1. 项目概述 (Project Overview)#

One paragraph: what the project does, the detected tech stack (real frameworks, not template placeholders), and repository structure (monorepo with subproject list, or single-project with key directories).

Fill from: README, package.json/pom.xml/build.gradle, top-level directory listing.

2. 快速命令 (Quick Commands)#

Quick-reference table:

操作命令构建(from Makefile / package.json scripts / mvnw / gradlew)启动(dev server or application start command)测试(test runner command)格式化(formatter command, or "N/A")Lint(linter command, or "N/A")

Environment variables (only if the project uses them): document ~/.<project>_env or .env file loading priority. If the project has no env file convention, skip this subsection entirely.

Fill from: package.json scripts, Makefile, pom.xml plugins, build.gradle tasks, CI workflow files.

3. 后端架构 (Backend Architecture)#

If the project has no backend: rename to "项目架构" and describe the single codebase.

• ASCII package tree — indent-based tree of key source directories (not every file, just meaningful packages)
• Package annotations — one-line purpose comment per package
• Core subsystems — 2-3 sentences each for major modules (auth, data layer, API, etc.)
• Pointer: → 详见 docs/architecture.md only if that file exists

Fill from: /init file tree + spot-reading key source files in each package.

4. 前端架构 (Frontend Architecture)#

If the project has no frontend, omit this section entirely.

• Tech stack: framework, state management, build tool (detected, not assumed)
• Routing scheme: file-based or config-based, with an example route
• API layer: how the frontend calls the backend (axios instance, base URL config, error interceptor)
• Component library: which UI library is used (or "无，使用原生组件")
• Pointer: → 详见 docs/design-docs/frontend-architecture.md only if that file exists

Fill from: package.json dependencies, grep for router setup and API client initialization.

5. 关键约定 (Key Conventions)#

Bullet list of enforced conventions. Each convention must be verifiable in the codebase — search for the actual pattern, don't copy from the template blindly.

Template examples (replace with detected equivalents):

• Error handling: search for custom exception base classes ( BusinessException, AppException, etc.). If found → document. If the project throws raw RuntimeException → note that as a finding, not a convention.
• Response wrapping: search for ApiResponse, R, Result<T>, or global response advice/controller. If a unified wrapper exists → document it.
• Layering rules: check for ArchUnit tests, lint-arch Makefile targets, or package structure conventions that enforce layer boundaries. If none → omit.
• Code style: detect from .editorconfig, .prettierrc, checkstyle.xml, spotless config, .eslintrc. Document the actual tooling.
• Auth: detect JWT, session, OAuth2 from code. Document the actual mechanism.

Every convention needs a doc link (only if the doc exists):

text

→ 详见 docs/conventions/<topic>.md

6. 本地开发及验证流程 (Local Development)#

Complete "edit → build → start → verify" loop:

text

1. 改 (Edit)   — source directories to modify
2. 构建 (Build) — exact command
3. 启动 (Start) — how to start the dev server
4. 验证 (Verify) — curl example or browser URL

Include (if applicable):

• Token acquisition — how to get an auth token for API testing
• Log paths — where application logs are written
• Pointer: → 详见 docs/design-docs/api-verification.md only if that file exists

Fill from: README, CONTRIBUTING.md, docker-compose.yml. Construct a realistic curl example based on an actual API route found in the code.

7. 质量检查 (Quality Checks)#

Single line listing available check commands:

text

make lint-arch / make lint-format / make format / make build / make test

Replace with the project's actual equivalents. If no formal checks exist, list the closest equivalents (e.g., npm run lint && npm test && npm run build).

8. 参考项目约定 (Reference Projects)#

If the project references sibling repos or template projects for conventions, list them with priority rules. If none exist, omit this section entirely.

9. 文档导航 (Document Navigation)#

Index table of existing detailed docs, grouped by category:

类别文档路径说明architecturedocs/architecture.md架构设计design-docsdocs/design-docs/*设计文档conventionsdocs/conventions/*编码约定

Fill from: Glob for docs/**/*.md, ref-*/, and any *.md files outside the root. Only include files that actually exist — never fabricate paths.

---

Preserving Existing Content#

If the project already has a hand-written CLAUDE.md or AGENTS.md, /init incorporates it. During Phase 2:

• Preserve hand-written insights that can't be discovered from code (historical context, team decisions, gotchas)
• Reorganize them into the matching template section
• Don't discard content just because it doesn't fit neatly — add it to the most relevant section, or create an additional subsection

Verification Checklist#

After writing, verify:

1. Every command in section 2 actually runs (at minimum, confirm the build and test commands work)
2. Every file path in section 9 exists on disk
3. Every convention in section 5 is observable in the codebase
4. No fabricated doc links or guessed commands

Self-Evolution Mechanism#

After each execution of this Skill:

1. Evaluate whether the output achieved the intended goal: pass / fail.
2. If it fails, reflect on the cause of failure and append a “failure case + improvement suggestion” to diary/YYYY-MM-DD.md.
3. If a certain improvement suggestion is repeatedly mentioned in the most recent three executions, refine it into a formal rule and submit a PR to modify this SKILL.md.