SuperAPI AI Directory

docs-manager

Coding & development

View repository

Updated 10-16 08:48

About this skill

Docs Manager

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

  1. First read the full text of the existing documentation
  2. Analyze where the content to be supplemented should be placed
  3. Choose an appropriate method:
    • Append content to an existing section
    • Add a new section
    • Modify existing descriptions to make them more accurate
  4. Keep the documentation style consistent

Step 3b: New addition mode

  1. Based on the directory structure output by tree, determine an appropriate category directory
  2. If a new category directory needs to be added, first confirm whether it is reasonable
  3. 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:

  1. 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
  2. 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
  3. 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:

  1. Split by usage scenario(recommended)

    • Content needed when developing different features → split
    • The original document retains an overview + link index
  2. 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:

  1. 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    # 配置功能
    
  2. Use the archive subdirectory

    • Place historical documents and implementation records in archive/
    • Keep the main directory concise
    • Example:docs/features/observability/archive/
  3. 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

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

  1. Check whether the format of the new documents/modified documents is correct
  2. Confirm that the link paths are correct
  3. 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

  1. Has specific specifications - Tells readers "how to write", not "what it is"
  2. Has code examples - Example code that can be copied and used directly
  3. Has prohibitions - Clearly states ❌ prohibited writing styles
  4. Concise and not verbose - Every sentence has value in existing

❌ Characteristics of poor documentation

  1. Only feature introduction - Only says "what features there are", not "how to write"
  2. Lack of code examples - All text descriptions, no referenceable code
  3. Overly verbose - Long explanations with no key points
  4. 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 和开发者看的,要简洁明了
- 避免冗余,一个信息只在一处记录
- 优先记录"怎么做"而非"是什么"
- 规范类文档要有具体示例
- 功能文档要说明核心代码路径