AgentSkillsCN

documenting-repositories

面向代理优化的仓库文档标准。当您需要创建或更新文档时，可调用此技能，以确保文档格式正确、抽象层次恰当，并合理规划前言部分。该技能覆盖 AGENTS.md、CLAUDE.md 以及 docs/*.md 的结构，并支持对文档陈旧程度的跟踪。此外，当文档内容过于详尽，或需要频繁更新时，也可调用此技能。

SKILL.md
--- frontmatter
name: documenting-repositories
description: Standards for agent-optimized repository documentation. Use when creating or updating documentation to ensure correct format, abstraction level, and front-matter. Covers AGENTS.md, CLAUDE.md, docs/*.md structure with staleness tracking. Also use when documentation seems too detailed or needs frequent updates.
user-invocable: false

Documentation Standards

Core Philosophy

Documentation provides context, not implementation details.

If a document needs frequent updates, it's documenting at the wrong level.

AvoidTarget
Lists every functionModule purpose and key abstractions
Documents every parameterAPI design patterns
Copies code verbatimIllustrative examples

Audience Split

TypeDocumentsAudience
Human-focusedREADME.md, docs/development.mdUsers, contributors
Agent-optimizedAGENTS.md, docs/architecture.md, docs/domain.md, docs/patterns.mdAI agents

Output Structure

code
repo/
├── AGENTS.md              # Main agent docs (quick start, key directories)
├── CLAUDE.md              # Single line: @AGENTS.md
├── README.md              # User-facing (optional tracking)
├── docs/
│   ├── architecture.md    # System design
│   ├── domain.md          # Business concepts
│   ├── patterns.md        # Code conventions
│   └── development.md     # Build/test/run
└── src/
    └── <complex-module>/
        ├── AGENTS.md      # Module-specific docs
        └── CLAUDE.md      # @AGENTS.md

Build System Priority

Commands must use the project's build system interfaces.

If project has...Document thisNOT this
Makefilemake testgo test ./...
package.jsonnpm testjest
docker-composedocker-compose updocker run ...

AGENTS.md Format

Uses dual-format references for compatibility:

markdown
@docs/architecture.md

- [Architecture](docs/architecture.md) - System design

CLAUDE.md Format

Single line only:

markdown
@AGENTS.md

Reference Documentation

For detailed specifications: