SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsupdate-claude-documentation

update-claude-documentation

Agents & models

View repository

Updated 10-16 03:40

About this skill

Update Claude Documentation

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

  • Use this skill when repository documentation such as README.md, CLAUDE.md, or repo docs must be updated after skill changes.
  • Load it when repository behavior has changed and the Claude-facing docs are now incomplete or stale.

Do Not Use When

  • The task does not change repository behavior or documentation-relevant structure.
  • The work is unrelated to repository documentation.

Inputs

Artefact Source/provider Required? Missing-input behaviour
Implemented change and complete diff Repository Yes Stop and inspect the change before describing it.
Affected documentation Repository routers and docs Yes Mark inaccessible documents not assessed; do not claim consistency.

Workflow

  1. Review the implemented change and map facts to affected documents.
  2. Update specific technical or contract documentation before general summaries.
  3. Stop if machine output and a documented count or command disagree.
  4. Recover by rerunning the source check, correcting stale claims, and reconciling terminology.
  5. Verify links, paths, commands, counts, and release instructions across the affected documents.

Quality Standards

  • Keep documentation factual, current, and aligned to actual file paths and workflows.
  • Prefer minimal updates that eliminate drift without adding unnecessary ceremony.
  • Preserve compatibility with existing repository workflows and file paths.

Anti-Patterns

  • Updating README while leaving AGENTS routing stale. Fix: map the change to every governing document.
  • Describing a validator that was not run. Fix: quote only commands and results supported by execution evidence.
  • Copying the same long procedure into three routers. Fix: keep the procedure in one focused document and link to it.
  • Preserving a stale skill count after filesystem changes. Fix: derive counts from the live catalogue.
  • Claiming a breaking change is harmless. Fix: state the migration or compatibility consequence explicitly.

Outputs

Artefact Consumer Acceptance condition
Updated repository documentation Maintainers and agents Counts, paths, terminology, commands, and release rules match the implemented state.

Evidence Produced

Evidence Consumer Acceptance condition
Documentation consistency check Release owner Affected files and verified facts are listed with no unresolved contradiction.

Capability Contract

Read and search are required. Editing is permitted only when documentation updates are authorised by the parent task. Publishing, external messaging, deletion, and release claims require explicit authority and validation evidence.

Degraded Mode

Fallback: when a source document, diff, command, or machine result is unavailable, update only verified facts, mark the remainder not assessed, and do not claim repository-wide consistency.

Decision Rules

Change Action Failure or risk avoided
Routing or active-count change Update agent routers and catalogue documentation Agents loading stale paths
Validator or release-gate change Update authoring, contribution, and CI instructions Unreproducible releases
Copy-only correction with no behavioural effect Edit the owning document only Unnecessary documentation churn

References

Update project documentation systematically after significant changes. Keep all files consistent and accurate.

Core Principle: Documentation tells one cohesive story. Each file serves a specific audience but must reflect the same reality.

Modularize Instructions (Token Economy): Avoid packing everything into a single CLAUDE.md. Prefer multiple focused docs (e.g., docs/setup.md, docs/api.md, docs/workflows.md) and reference them only when needed to reduce context bloat.

When to Use

✅ Adding/removing features ✅ Architecture or design pattern changes ✅ Dependency or tech stack updates ✅ API endpoints or database schema changes ✅ Project directory restructuring ✅ Development workflow changes

❌ Typo fixes (do directly) ❌ Code comments ❌ WIP features not yet merged

Documentation Files

File Audience Purpose
PROJECT_BRIEF.md Stakeholders, new devs 30-sec overview
README.md Developers Setup, usage guide
TECH_STACK.md Developers, DevOps Tech inventory
ARCHITECTURE.md Senior devs, architects System design
docs/API.md API consumers API reference
docs/DATABASE.md Backend devs, DBAs Schema docs
CLAUDE.md Claude Code Dev patterns
docs/setup.md Developers Setup details
docs/api.md API consumers API usage guide
docs/workflows.md Developers Workflow rules

Change → File Mapping

New Feature:

  • README.md (usage)
  • docs/API.md (if adds endpoints)
  • docs/DATABASE.md (if adds tables)
  • ARCHITECTURE.md (if adds components)
  • CLAUDE.md (if changes patterns)
  • PROJECT_BRIEF.md (if significant)

Tech Stack Change:

  • TECH_STACK.md (always)
  • README.md (setup instructions)
  • ARCHITECTURE.md (if affects design)
  • CLAUDE.md (if affects workflows)

Architecture Change:

  • ARCHITECTURE.md (always)
  • README.md (overview section)
  • CLAUDE.md (patterns)
  • PROJECT_BRIEF.md (if major)

API/Database Change:

  • docs/API.md or docs/DATABASE.md (always)
  • ARCHITECTURE.md (if changes contracts)
  • CLAUDE.md (if affects patterns)
  • README.md (if affects usage)

Update Workflow

1. Understand Change (2-5 min)

Document:

  • Type: Feature/Architecture/Tech Stack/API/Database
  • What: One sentence description
  • Impact: Who/what affected
  • Breaking: Yes/No (what breaks)

2. Map to Files (1-2 min)

Order: Specific → General

  1. Technical Specs (API.md, DATABASE.md)
  2. Architecture (ARCHITECTURE.md, TECH_STACK.md)
  3. AI Instructions (CLAUDE.md)
  4. User Guides (README.md)
  5. Overview (PROJECT_BRIEF.md)

3. Read Current State (2-3 min)

Read all affected files in parallel.

4. Update Systematically (10-20 min)

Per-file checklist:

  • Update primary section
  • Update related sections
  • Update examples/code snippets
  • Add migration notes if breaking

5. Verify Consistency (2-3 min)

Check across all files:

  • Terminology consistent
  • Version numbers match
  • File paths consistent
  • Component names consistent
  • Features described consistently

6. Final Review (1 min)

  • New dev can understand from README
  • CLAUDE.md has context
  • Breaking changes marked
  • Examples work
  • No contradictions

Total: 15-30 minutes

Common Mistakes

❌ Updating only one file

# Updated README but forgot CLAUDE.md

# Result: AI doesn't know new pattern

❌ Inconsistent terminology

# README.md: "Authentication Service"

# ARCHITECTURE.md: "Auth Module"

# CLAUDE.md: "Login System"

# Pick ONE term everywhere

❌ Forgetting breaking changes

# Renamed API endpoint but README examples still use old path

# Add migration notes EVERYWHERE affected

❌ General → Specific order

# BAD: Update BRIEF first, then API.md

# GOOD: Update API.md first (precise), then BRIEF (summary)

Quick Reference

Update Order:

API/DB Specs → Architecture → CLAUDE → README → BRIEF

Consistency Checks:

Terminology, Versions, Paths, Names, Features

Time Budget:

Small change: 5-10 min
Medium change: 15-30 min
Major refactor: 45-60 min

Summary

Process: Understand → Map → Read → Update → Verify → Review

Key Rules:

  1. Update specific docs first, general last
  2. Read all affected files before editing
  3. Keep terminology consistent
  4. Mark breaking changes everywhere
  5. Test examples before committing
  6. One reality, multiple perspectives

Remember: Documentation debt compounds fast. Update immediately when making changes.