Skill Directory:
.agents/skills/docs-manager/All bundled resource paths below (scripts, references, assets) are relative to this directory.
Responsibilities
Maintain project documentation and ensure that documentation stays consistent with the code implementation. Documentation is the core and soul of the code repository.
Workflow
Step 1: Understand user requirements
Clarify what content the user wants to record:
- Documentation for a new feature/module?
- Supplementary explanation for an existing feature?
- Code standards/conventions?![alt text]![alt text]
- Technical solution/architecture design?
Step 2: Obtain the current documentation directory structure
tree docs
Determine through the directory tree whether related documentation already exists:
- Related documentation already exists → Enter "supplement mode"
- Related documentation does not exist → Enter "new addition mode"
Step 3a: Supplement mode
Principles:Make minimal changes and do not make unnecessary changes
- First read the full text of the existing documentation
- Analyze where the content to be supplemented should be placed
- Choose an appropriate method:
- Append content to an existing section
- Add a new section
- Modify existing descriptions to make them more accurate
- Keep the documentation style consistent
Step 3b: New addition mode
- Based on the directory structure output by tree, determine an appropriate category directory
- If a new category directory needs to be added, first confirm whether it is reasonable
- Create documentation following the project style:
- Use Chinese
- Clear heading hierarchy
- Include necessary code examples
- Use relative paths when specifying file paths
Step 3c: Splitting mode
Core principle: The purpose of splitting is to let the code agent read on demand and avoid reading a large amount of irrelevant content.
Determine whether splitting is needed:
-
Whether the usage scenarios are consistent(most important)
- When writing a certain feature, do these sections need to be referenced together?
- If yes → do not split, even if it exceeds 800 lines
- If no → consider splitting
-
Whether the topics are closely related
- Does the content belong to the same knowledge domain?
- Example: Schema + Migration + operations in DATABASE.md → closely related, do not split
-
Use line count as an auxiliary reference
- When it exceeds 800 linesConsiderWhether there is content with different usage scenarios
- Not a hard splitting criterion
Splitting examples:
# UI_PATTERNS.md 的拆分分析
章节 1-7(头像、标签、图标)→ 写列表/卡片组件时需要
章节 8-11(管理端页面、表格)→ 写管理后台时需要
章节 12(思考过程)→ 写对话组件时需要
分析:使用场景有差异,但内容都是 UI 规范,可以保持一个文档
结论:暂不拆分,通过章节标题定位即可
Splitting strategy:
-
Split by usage scenario(recommended)
- Content needed when developing different features → split
- The original document retains an overview + link index
-
Hierarchical reference structure
- CLAUDE.md → large module documentation (index) → small module documentation (details)
- Large module documentation is responsible for: overview + links referencing sub-documents
- Small module documentation is responsible for: specific specification content
Hierarchy reference example:
# CLAUDE.md 中
- [意图控制](docs/features/intent-control/README.md) - 意图识别与路由
# docs/features/intent-control/README.md 中
## 详细文档
- [Intent Router](INTENT_ROUTER.md) - Two-Pass 意图路由引擎
- [意图配置](INTENT_CONFIG.md) - 意图库管理
Step 3d: Directory organization mode
Trigger conditions:
- A category has more than 5 documents
- There is an obvious subcategory relationship between documents
- It is unclear which category a new document should be placed in
Organization strategy:
-
Add subdirectories
# 整理前 docs/features/ ├── agent-edit.md ├── agent-list.md ├── agent-config.md └── ... # 整理后 docs/features/agent-management/ ├── README.md # 概述 + 索引 ├── AGENT_EDIT.md # 编辑功能 └── AGENT_CONFIG.md # 配置功能 -
Use the archive subdirectory
- Place historical documents and implementation records in
archive/ - Keep the main directory concise
- Example:
docs/features/observability/archive/
- Place historical documents and implementation records in
-
README.md as a directory index
- Every feature directory should have
README.md - List the brief descriptions and links of all documents under that directory
- Every feature directory should have
Step 4: Check document length
After completing content writing, check the number of lines in the document:
wc -l <文档路径>
| Number of lines | Status | Handling method |
|---|---|---|
| < 300 | ✅ Good | No handling needed |
| 300-600 | ⚠️ Attention | Check whether the usage scenarios are consistent |
| 600-1000 | ⚠️ Evaluate | Analyze whether there is content for different usage scenarios |
| > 1000 | ❌ Strongly recommend splitting | There is a high probability of content that can be split |
Note: The number of lines is only a reference; the core criterion is "usage scenario consistency".
Step 5: Check whether CLAUDE.md needs to be updated
⚠️ Changes to CLAUDE.md must be handled with caution; only the document index section may be modified, and other unrelated content must not be modified.
Situations requiring updates:
- Added a document → add the link under the corresponding category
- Deleted a document → remove the corresponding link
- Major changes to document functionality → update the document's brief description
- Split a document → update the original document description and add links to the new documents
Operating principle: minimal changes
- Only modify the document link list section
- Keep the existing format and indentation
- Do not modify other sections
Step 6: Verify
- Check whether the format of the new documents/modified documents is correct
- Confirm that the link paths are correct
- If CLAUDE.md was modified, confirm that the index structure is complete
Documentation style guide
Heading conventions
# 一级标题(文档名)
## 二级标题(主要章节)
### 三级标题(子章节)
Code example conventions
- Explicitly specify the language:```typescript / ```bash
- Include file path comments (if it is project code)
// apps/web/src/pages/xxx/index.tsx
export function XxxPage() { ... }
File path conventions
- Use paths relative to the project root directory
- Example:
apps/web/src/components/instead of absolute paths
Documentation quality requirements
Core principles
Documentation isconcise specification documents, intended to let AI/developers write code according to the specification and ensure consistent style.
✅ Characteristics of good documentation
- Has specific specifications - Tells readers "how to write", not "what it is"
- Has code examples - Example code that can be copied and used directly
- Has prohibitions - Clearly states ❌ prohibited writing styles
- Concise and not verbose - Every sentence has value in existing
❌ Characteristics of poor documentation
- Only feature introduction - Only says "what features there are", not "how to write"
- Lack of code examples - All text descriptions, no referenceable code
- Overly verbose - Long explanations with no key points
- Duplicate information - The same content repeated in multiple places
Reference Template
Good specification document structure:
# 功能/模块名
> 一句话说明
---
## 核心规范
### 规范 1:XXX
**规则**:具体要求
```tsx
// ✅ 正确写法
代码示例
// ❌ 错误写法
反例代码
Specification 2: YYY
...
Code Location
| Module | Path | Description |
|---|---|---|
| Frontend Page | pages/xxx/ |
... |
| Backend Service | services/xxx.ts |
... |
FAQ
Q: ... A: ...
## 注意事项
- 文档是给 AI Agent 和开发者看的,要简洁明了
- 避免冗余,一个信息只在一处记录
- 优先记录"怎么做"而非"是什么"
- 规范类文档要有具体示例
- 功能文档要说明核心代码路径