documentation
GitHub用于生成和更新 docs/ 目录下的项目文档。面向开发者，遵循特定格式规范（如 Mermaid 图表、无表情符号），确保内容简洁一致。需先查阅现有文档和索引，维护 Last Updated 时间戳，适用于显式请求或新特性记录场景。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill documentation -g -y
SKILL.md
Frontmatter
{
"name": "documentation",
"description": "Generate and update project documentation under docs\/. Uses Mermaid for diagrams. Invoked explicitly when the user requests documentation work."
}
Documentation Generation Skill
Purpose
Generate, update, and maintain documentation files under docs/. This skill ensures consistency with existing project conventions, structure, and formatting patterns.
Audience
The documentation targets developers and engineers working on the project. It serves as a reference and knowledge source for understanding the codebase, architecture, flows, and conventions. Write with the assumption that the reader has development experience but may be new to this project.
When to Use
- User explicitly asks to create, update, or review documentation
- User asks to document a new feature, flow, model, or architectural decision
Documentation Structure
All documentation lives under docs/, organized by domain subfolders. The folder structure evolves over time — always check the current state of docs/ before creating or updating files. docs/README.md serves as the main index and must be updated when adding new documentation areas.
Conventions
Formatting Rules
- Headings:
#for title (H1),##for sections,###for subsections - Tables: Use markdown tables for comparisons, feature matrices, config layers
- Code blocks: Triple backticks with language tag (
python,json,bash,mermaid) - Inline code: Backticks for variable names, file paths, CLI commands
- Links: Relative markdown links —
[Display Text](relative/path.md) - Lists: Bullet points for descriptions, numbered lists for sequential steps
- No emojis in documentation content
- Short and concise — keep docs brief, avoid verbose explanations and filler words
Structure of a Documentation File
Every doc file should follow this pattern:
- H1 title — short, clear name
- Overview section — 1–3 sentences explaining the purpose
- Detail sections — organized with H2/H3 headings
- Tables — for structured comparisons or reference data
- Last updated — every doc file must end with a "Last Updated" line at the bottom, formatted as:
*Last updated: YYYY-MM-DD*- When creating a new doc, add the current date
- When updating an existing doc, update the date to the current date
Diagrams
- Use Mermaid for all diagrams — flowcharts, sequence diagrams, C4, etc. (embed in fenced code blocks with
mermaidtag) - Use ASCII text diagrams for simple layered architectures
- Do not use PlantUML for new diagrams
Code Examples
- Avoid specific code examples from the codebase — code changes frequently and concrete examples become outdated quickly
- Prefer describing patterns and conventions in prose or pseudocode
- Only include code snippets when they illustrate a stable API or convention unlikely to change
Workflow
- Read existing docs in the target domain folder before writing — match tone and depth
- Check
docs/README.md— if adding a new documentation area, update the index - Place the file in the correct domain subfolder
- Follow the conventions listed above
- Cross-reference related docs with relative links where helpful
Version History
- e0220ca Current 2026-07-05 23:24
