Code Documentation Skill

intent

this skill governs code documentation at every level: from individual file headers to global architecture docs. use it whenever documentation is requested, after any significant code change, when onboarding a new subsystem, auditing existing docs for accuracy, or when asked to "document", "update docs", "write docs", or "clean up comments". the skill covers three tightly coupled concerns: (1) inline file and function headers in source code, (2) subsystem-level .md docs, and (3) global architecture plus API reference docs. always apply this skill instead of improvising documentation standards. document the why, not the what , the code already says what it does.

inputs

• source repository: read access to all project files (frontend, backend, docs/)
• git history: ability to check git log to understand code evolution and reason against stale docs
• reference templates: access to three reference files in the project (references/subsystem-doc.md, references/architecture-doc.md, references/api-reference.md)
• language-specific comment syntax: knowledge of comment block syntax for all languages in the codebase (js/ts, python, go, ruby, etc.)
• current code state: confirm you're documenting against the active branch, not stale code
• project structure awareness: understand directory layout, subsystem boundaries, and which files import which

procedure

phase 0: scan and assess

1. read the repo structure top-to-bottom. understand what exists before editing anything.
2. identify subsystems by grouping files by domain (auth, billing, api layer, data layer, etc.). check for directories with 3+ related files, shared services used by 3+ files, distinct API surfaces, background jobs, or third-party integrations.
3. scan /docs/, /backend/docs/, and /frontend/docs/ for existing documentation. note what's present, missing, or stale.
4. confirm the active branch in git. never document against stale or wrong code.

phase 1: source file documentation

5. for every source file that is 20+ lines long or is imported by other modules, add a full path comment on line 1 using the language's comment syntax (e.g., // src/services/auth/tokenService.js in js, # src/services/auth/token_service.py in python).
6. immediately after the path comment, add a file header block using the language's block comment syntax. the header must include: file path, overview (2-3 sentences explaining what the file does and why it exists), exports list (function/class names exported), imported by list (files that import this one), imports list (external deps and internal imports), and notes (gotchas, expiry info, backwards compatibility concerns).
7. keep the file header current. whenever you add an export, update the exports section. whenever a new file imports this one and you know about it, update imported by. never pad with boilerplate; every line must be accurate.
8. for every non-trivial function (anything with logic beyond a single expression), add a function header comment. max 2 sentences. explain why the function exists or what makes it non-obvious, not just what it does. include parameter/return type info only if the types are genuinely surprising.
9. delete all inline comments that restate code logic (e.g., // enable proxy above proxy: true), reference removed code (e.g., // removed legacy handler), serve as changelogs (e.g., // changed to use v2 API), use section dividers (e.g., // ---- helpers ----), or describe obvious steps (e.g., // loop through users). these are clutter that erode trust in real comments.
10. allow inline comments only for surprising constants or non-obvious intent (e.g., const TIMEOUT = 5000 // 5 seconds, or return null // caller handles retries).

phase 2: subsystem documentation

11. create one .md file per subsystem in /backend/docs/<subsystem>.md or /frontend/docs/<subsystem>.md. use the template in references/subsystem-doc.md as your blueprint.
12. if a subsystem doc already exists, compare it against current code. remove any description of code that no longer exists. add any missing files, services, or flows. update all file maps and function names to reflect the current state.
13. for each subsystem, document: high-level purpose, directory structure and file map, exported functions/classes with signatures, internal data structures, common workflows with step-by-step examples, external dependencies and how they're used, error handling patterns, and any testing approach.

phase 3: global architecture document

14. create or update /docs/architecture.md (or /backend/docs/architecture.md depending on repo layout). use the template in references/architecture-doc.md.
15. include required sections: system overview (2-3 sentences on what the product does), subsystems list (bulleted, one-liner per subsystem, linked to its .md), high-level diagram (ascii or mermaid showing subsystem relationships), tech stack (language, framework, database, cache, queue, infrastructure), and cross-cutting concerns (how auth, error handling, validation, config, logging, and testing work across the system, not per-subsystem).

phase 4: API reference documentation

16. if a backend exists, create /backend/docs/api.md or, for large backends, create per-subsystem files like /backend/docs/api-auth.md, /backend/docs/api-billing.md, then link them in an index at /backend/docs/api.md.
17. for every API endpoint, document using the template in references/api-reference.md: http method and path, description (1 sentence, what the caller gets), request section (path params, query params, request body schema with types and constraints), response section (success schema, status codes, error codes with descriptions), and source mapping (which controller file and service methods handle it).
18. keep api.md in sync with the actual codebase. if an endpoint is removed, remove its documentation.

phase 5: validation audit

19. after writing or updating any docs, run a documentation audit. create a checklist with four sections: missing (list any subsystem without a doc, any major service without a function header), outdated (list any doc referencing removed files, functions, endpoints, or incorrect flow descriptions), incorrect (list any wrong dependency chain, wrong export name, wrong error code), and recommendations (specific fixes with file locations).
20. do not skip this audit. stale documentation is worse than none because it actively misleads. publish the audit results or fix the issues before marking the work done.

decision points

if the repo already has docs: then compare them against current code (step 12, step 18). remove references to removed code. update file maps and function signatures to match reality. else create new docs from the reference templates (steps 11-15).

if a function's logic changes: then update its header comment immediately (enforcement rule 1). else skip function header updates.

if you add or remove an export: then update the file header's exports section (enforcement rule 2). else do not modify the exports section.

if a new file is created that other files import: then create a file header for it and update the "imported by" sections in any importing files if you have visibility (enforcement rule 3). else skip importer updates.

if an API endpoint is added, changed, or removed: then update /backend/docs/api.md (enforcement rule 4). else do not modify api.md.

if a subsystem's internal structure or flow changes significantly: then update that subsystem's .md doc (enforcement rule 5). else do not modify subsystem docs.

if a brand new subsystem is created: then create a new .md from the template in references/subsystem-doc.md (enforcement rule 6). else do not create new subsystem docs.

if a file or feature is removed: then find every doc that mentions it and remove those references (enforcement rule 7). else do not prune docs.

if the repo has no reference templates: then consult the skill text for minimal inline templates (file header structure in phase 1, subsystem structure in phase 2, architecture structure in phase 3, api structure in phase 4). else use the reference files as your authoritative blueprint.

if documentation audit finds stale references: then fix or remove them before considering the skill complete. else proceed to publish docs.

output contract

successful documentation deliverables appear in these locations:

• file headers: every source file ≥20 lines or imported by other modules has a full path comment on line 1 and a block comment header with overview, exports, imported by, imports, and notes sections within the first 30 lines.
• function headers: every non-trivial function has a 1-2 sentence block comment explaining its purpose above its definition.
• subsystem docs: one .md file per subsystem exists at /backend/docs/<name>.md or /frontend/docs/<name>.md with directory structure, file map, exported functions, workflows, dependencies, and error handling documented.
• architecture doc: /docs/architecture.md or /backend/docs/architecture.md exists with system overview, subsystems list (linked), high-level diagram, tech stack, and cross-cutting concerns.
• api reference: /backend/docs/api.md exists (or per-subsystem api-*.md files with an index). every endpoint lists method, path, description, request schema, response schema, status codes, and source mapping.
• audit report: a documentation audit log (missing, outdated, incorrect, recommendations) is produced or issues are fixed.
• no stale references: all docs describe code that currently exists in the active branch. removed code, endpoints, and files have been purged from docs.

data format: markdown (.md) files with standard block comment syntax in source code (js, python, go, ruby, etc.). diagrams may be ascii art or mermaid syntax.

outcome signal

you know this skill worked when:

• a new developer can read the architecture.md and understand what the system does, which subsystems exist, and how they fit together.
• a developer can open any source file and immediately see its purpose, what it exports, and which files depend on it (from the file header).
• a developer can look up any API endpoint in api.md and find the exact schema, status codes, and which controller handles it.
• a developer can read a subsystem.md and understand its workflows, error patterns, and which files live inside it.
• every function in the codebase has a clear comment explaining why it exists, not just what it does.
• when code changes (a file is removed, an endpoint is added, a function signature changes), the corresponding docs are updated in the same pr or commit.
• a code review checklist or automated linter can verify: every file ≥20 lines has a header comment, every function has a purpose comment, no inline comments restate code logic, and no docs reference removed code.
• a developer runs a grep search for any removed filename and finds zero references in any .md file.

credits: original skill by encryptshawn (clawhub). enriched to implexa quality standards.