agent-init

SKILL.md

---
name: agent-init
description: Initialize or update AGENTS.md/CLAUDE.md for a project. Use this skill whenever the user wants to create, initialize, generate, setup, or update a project-level AGENTS.md or CLAUDE.md file. Triggers on requests like "initialize AGENTS.md", "create CLAUDE.md", "generate project doc for AI", "setup agent guidelines", "create project rules", or any mention of AGENTS.md/CLAUDE.md creation or initialization.
---

# 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):
```
→ 详见 docs/conventions/<topic>.md
```

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

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

```
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:
```
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:

| 类别 | 文档路径 | 说明 |
|------|---------|------|
| architecture | docs/architecture.md | 架构设计 |
| design-docs | docs/design-docs/* | 设计文档 |
| conventions | docs/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`.