Documentation Management Skill

Purpose

Every .md file has a clear home based on its lifecycle stage. This skill defines where docs go, when to archive them, and how to keep the project navigable.

When to Activate

Activate this skill when the agent:

• Creates a new .md file anywhere in the project
• Moves, renames, or reorganizes documentation
• Completes a task that produced progress reports or test results
• Runs a documentation audit or health check
• Notices stale or duplicate documents
• Reviews a PR that adds or moves .md files
• Before git commit that includes .md changes

Quick Reference

Component README?        → <component>/README.md
Project-essential file?  → Root (allowlist only — see Rule 5)
One-time snapshot?       → docs/archive/YYYY-MM-DD_<name>.md
Actively iterated?       → docs/drafts/<name>.md
Periodically updated?    → appropriate dir + purpose header (mandatory)
Stable reference?        → docs/<name>.md

Directory Map

project-root/
├── docs/
│   ├── archive/              # Historical snapshots (read-only)
│   │   └── README.md         # Index: date, origin path, description
│   ├── drafts/               # Active design docs under iteration
│   └── *.md                  # Stable reference docs
├── *.md                      # Root: allowlist only (see Rule 5)
├── backend/README.md         # Component README (allowed)
├── proxy/README.md           # Component README (allowed)
├── examples/*/README.md      # Example project README (allowed)
├── go-sdk/*/README.md        # SDK README (allowed)
├── scripts/README.md         # Scripts README (allowed)
├── .agents/skills/*/SKILL.md # Project-local skill definitions (allowed)
├── openclaw-plugin/skills/*/SKILL.md  # Plugin skill (allowed)
└── memory/*.md               # Agent memory (.gitignored)

Rules

Rule 1: Classify Before Creating

Before creating ANY .md file, classify it:

Rule 2: Live Documents Must Have a Purpose Header

Every document that gets periodically updated MUST include this header immediately after the title:

# Title

> **Purpose**: What this document tracks.
> **Updated by**: Who/what updates it (cron ID, manual process, etc.).
> **Update rule**: How it changes (overwrite with latest / append entries).

This header is mandatory. No exceptions.

Rule 3: Archive, Don't Delete

When a document's content becomes a historical record:

1. Identify the last-relevant date for the content
2. Copy to docs/archive/YYYY-MM-DD_<descriptive-name>.md
   • YYYY-MM-DD = last-relevant date (not today's date)
   • <descriptive-name> = lowercase, hyphens, clear description
3. Add a row to docs/archive/README.md:

   | `YYYY-MM-DD_<name>.md` | `<original-path>` | YYYY-MM-DD | <brief description> |

4. Remove the original file
5. Check if any remaining docs reference the archived file's path — update those references

Archive size: If docs/archive/ exceeds 30 files, review whether any very old entries can be removed (they remain in git history regardless).

When to archive a draft: When the feature it describes is fully implemented AND the design is no longer referenced for active work. If the draft still contains design rationale useful for future reference, promote it to docs/ instead of archiving.

Rule 4: No Duplicate Purpose

Before creating a new file, ask: "Does a file already exist for this purpose?"

• Yes → Update it in place (live docs) or create a new archive entry (historical)
• No → Create the file in the correct location per Rule 1

Never have two files tracking the same thing.

Rule 5: Root Directory Is Sacred

Only these files may live in the project root:

Everything else → docs/, docs/drafts/, or docs/archive/.

Rule 6: Language Consistency

• Reference docs: Maintain paired versions — <name>.md (English) + <name>-zh-CN.md (Chinese)
• Updating a doc with only one language version: update it as-is; note in commit that counterpart is missing
• Drafts: Any language; clarity matters most
• Archive: Keep original language; do not translate
• Code comments: English preferred

Rule 7: Draft Naming Convention

Draft filenames should describe their content, not their tracking function. Use one of these patterns:

Where <type> is: design, analysis, research, plan, walkthrough, guide, review.

Rule 8: No Ephemeral Files in the Repo

Do not commit scratch notes, temporary debugging logs, or throwaway files. If it's worth writing down, it's worth placing correctly per Rule 1. If it's truly temporary, use commit messages or terminal output instead.

Agent memory files (HEARTBEAT.md, MEMORY.md, memory/*.md) are .gitignored by design. Never .gitignore anything under docs/ — those are project artifacts.

Principle: Findability

When placing a document, ask: "If someone needs this in 3 months, where would they look first?"

• API docs → docs/API.md (obvious)
• Deployment → docs/DEPLOYMENT.md (obvious)
• Performance results → docs/performance-test-results.md (with purpose header)
• Design for an in-progress feature → docs/drafts/<feature>-design.md

The correct location is the one that maximizes findability for future readers.

Draft Lifecycle

Created → Iterated → Implemented → Decision point
                                           ├─ Still useful as reference? → Promote to docs/
                                           └─ No longer needed?          → Archive to docs/archive/

Signs a draft should be archived or promoted:

• Feature fully implemented and tested
• Design stable for 2+ weeks without changes
• New contributors would find the final docs/ version more useful

Real-World Example

Before (the problem this skill prevents):

./TASK_TRACKER.md                          # Completed 2026-02-13, forgotten
./performance-test-results.md              # Duplicate of docs/ version
./backend/TASK_PROGRESS.md                 # Completed 2026-02-12, forgotten
./backend/TEST_REPORT.md                   # Historical snapshot, not updated
./reviews/code-review-2026-02-12.md        # Old review, never cleaned up
./docs/drafts/TASK_PROGRESS.md             # Completed task in drafts
./docs/drafts/implementation-progress.md   # Completed, never archived
./RELEASE_DRAFT.md                         # Already released as v0.1.0

After (applying this skill):

./docs/archive/2026-02-12_code-review-v1.md
./docs/archive/2026-02-12_code-review-fix-progress.md
./docs/archive/2026-02-13_task-tracker-webui-complete.md
./docs/archive/2026-02-13_comprehensive-test-report.md
./docs/archive/2026-03-13_v0.1.0-beta-release-draft.md
./docs/archive/2026-03-17_evo-memory-implementation-progress.md
./docs/archive/2026-03-18_spring-ai-integration-progress.md
./docs/archive/2026-03-20_go-java-sdk-implementation-progress.md
./docs/archive/README.md                   # Index of all archived docs
./docs/performance-test-results.md         # Single live copy with purpose header

11 scattered files → 1 organized archive with index.

Audit Checklist

Run before major commits, or when documentation feels disorganized.

Step 1 — Scan:

find . -name "*.md" \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" \
  -not -path "*/target/*" \
  -not -path "*/.mvn/*" \
  -not -path "*/memory/*" \
  | sort

Step 2 — Verify each file:

• Correct location per Rule 1?
• If live: has purpose header per Rule 2?
• No duplicate purpose file?
• If completed tracker in docs/drafts/: archived?
• docs/archive/README.md table current?
• If stale: has archive entry?
• If in root: on the Rule 5 allowlist?
• Draft filenames descriptive per Rule 7?

Step 3 — Report:

• All pass → "Documentation health OK"
• Issues found → List each violation with its file path, then fix per Common Violations table

Common Violations