AgentSkillsCN

docs-update

Documentation update workflow. Use when modifying files in docs/ directory or any markdown files (*.md).

SKILL.md
--- frontmatter
name: docs-update
description: Documentation update workflow. Use when modifying files in docs/ directory or any markdown files (*.md).

Documentation Update Workflow

Workflow for documentation changes with SSOT awareness.

Prerequisites

  • •Use git-workflow Skill for branch, commit, and PR workflow.
  • •Understand SSOT structure before editing any documentation.

SSOT Awareness

Critical: Before editing documentation, identify if the file is an SSOT or references one.

SSOT Locations

CategorySSOT LocationDescription
Agent behaviorAGENTS.mdEntry point for all agents
Agent instruction designdocs/ai/design.mdCommand/Skill/Rule architecture
Label definitionsdocs/guidelines/task-classification.mdAll label types and meanings
Label → Skill mapping.claude/skills/label-context-mapping/Operational routing
Coding conventionsdocs/guidelines/coding-conventions.mdCode style rules
Security rulesdocs/guidelines/security.mdSecurity requirements
Testing standardsdocs/guidelines/testing.mdTest requirements
Workflowdocs/guidelines/workflow.mdDevelopment workflow

SSOT Rules

  1. •If editing an SSOT file: Update carefully, as other files reference it
  2. •If editing a non-SSOT file: Ensure it references the SSOT, don't duplicate information
  3. •If information conflicts: The SSOT is authoritative; update the referencing file

Applicable Files

PathTypeDescription
AGENTS.mdSSOTAgent behavior entry point
ARCHITECTURE.mdSSOTSystem architecture
docs/guidelines/SSOTProject guidelines and standards
docs/design/ReferenceDesign documents
docs/chains/ReferenceChain-specific documentation
docs/ai/task-contexts/ContextTask-specific procedures
internal/AGENTS.mdScoped SSOTInternal package guidelines
pkg/AGENTS.mdScoped SSOTPublic package guidelines

Documentation Hierarchy

code
AGENTS.md (entry point)
    │
    ├─ docs/ai/design.md (instruction system design)
    │
    ├─ docs/guidelines/ (guidelines and standards)
    │   ├─ task-classification.md (label definitions, SSOT)
    │   ├─ coding-conventions.md
    │   ├─ security.md
    │   ├─ testing.md
    │   ├─ workflow.md
    │   ├─ architecture.md
    │   ├─ code-generation.md
    │   └─ ...
    │
    └─ docs/ai/task-contexts/ (task-specific context)
        ├─ bug-fix.md, feature-add.md, etc.
        └─ chains/ (chain-specific)

Workflow

1. Identify Document Type

Before editing, determine:

  • •Is this file an SSOT?
  • •Does this file reference an SSOT?
  • •What other files might be affected?

2. Check for Duplicated Information

If the information you're adding already exists elsewhere:

  • •Find the SSOT location
  • •Add a reference instead of duplicating

3. Make Changes

Follow markdown style guidelines:

  • •Use ATX-style headers (#, ##, ###)
  • •One blank line between sections
  • •Code blocks with language specifier
  • •Tables for structured data
  • •Relative links within docs

4. Verify Cross-References

After changes:

  • • Links work correctly
  • • SSOT references are accurate
  • • No information duplication
  • • Consistent formatting

Markdown Style

Headers

markdown
# Top Level (document title)

## Section

### Subsection

Code Blocks

Always specify language:

markdown
```go
func example() {}
```
bash
make go-lint
code

### Tables

Use tables for structured data:

```markdown
| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Links

  • •Use relative links: [link](../path/to/file.md)
  • •Verify links work after moving files
  • •Update cross-references when renaming

Self-Review Checklist

  • • SSOT location identified (if applicable)
  • • No duplicated information
  • • References point to correct SSOT
  • • Markdown renders correctly
  • • Links work
  • • Consistent formatting
  • • Tables align properly

Commit & PR

Use git-workflow skill for commits:

  • •Commit type: docs
  • •Scope: Optional (or target area: btc, eth, standards, etc.)

Example: docs(standards): update coding conventions for error handling

Related