name: code-documentation description: > Comprehensive code documentation skill — use this any time 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". Covers three tightly coupled concerns: (1) inline file/function headers in source code, (2) subsystem-level .md docs, and (3) global architecture + API reference docs. Always apply this skill — do not improvise documentation standards. Also triggers for requests like "add comments", "document this file", "our docs are out of date", "generate API reference", or after a PR or feature branch is completed.

Code Documentation Skill

Purpose

This skill governs how code is documented at every level — from individual file headers to global architecture docs. Apply it consistently across all projects. When in doubt: document the why, not the what. The code already says what it does.

Phase 0 — Before You Write Anything

1. Scan the repo structure. Understand what exists before touching anything.
2. Identify subsystems. Group files by domain (Auth, Billing, API Layer, etc.).
3. Read existing docs first. Check /docs/ in both frontend and backend. Note what's present, missing, or stale.
4. Confirm the active branch. Never document against stale or wrong code.

Phase 1 — Source File Standards

Apply to every file that is ≥ 20 lines OR is imported by other modules.

1.1 — Line 1: Full Path Comment

The very first line of every source file must be a comment containing the file's full path from the project root. Use the comment syntax appropriate to the language.

// src/services/auth/tokenService.js

# src/services/auth/token_service.py

1.2 — File Header Block (lines 2–N)

Immediately after the path comment, add a header block. Use the language's block comment syntax. This block is mandatory and must be kept accurate.

/**
 * File: src/services/auth/tokenService.js
 *
 * Overview:
 *   Issues, validates, and refreshes JWT tokens for authenticated sessions.
 *   Exists to centralise all token logic so Auth routes stay thin.
 *
 * Exports:
 *   - issueToken(userId, role) → signed JWT string
 *   - verifyToken(token) → decoded payload or throws
 *   - refreshToken(oldToken) → new signed JWT string
 *
 * Imported By:
 *   - src/routes/auth.js
 *   - src/middleware/requireAuth.js
 *
 * Imports:
 *   - jsonwebtoken  — signing/verification
 *   - config/env    — JWT_SECRET, TOKEN_TTL
 *
 * Notes:
 *   - Tokens expire in 15 min; refresh window is 7 days.
 *   - verifyToken throws on expiry — callers must handle.
 */

Rules: - Keep it current. If you add an export, update Exports. If a new file imports this, update Imported By. - Do not pad with boilerplate. Every line must be accurate and useful.

1.3 — Function Headers

Top of every non-trivial function (any function with logic beyond a single expression):

/**
 * Signs a new JWT for the given user. Embeds userId and role in payload.
 * Throws if JWT_SECRET is not set in env.
 */
function issueToken(userId, role) { ... }

Rules: - Max 2 sentences. - Explain why the function exists or what makes it non-obvious, not just what it does. - No parameter/return type breakdown unless the types are genuinely surprising.

1.4 — Inline Comment Rules

Allowed (rare exceptions only):

const TIMEOUT = 5000 // 5 seconds

Prohibited — remove on sight:

If you encounter these, delete them. They are clutter that erodes trust in real comments.

Phase 2 — Subsystem Documentation

See references/subsystem-doc.md for the full template and field-by-field instructions.

One .md file per subsystem, located at: - /backend/docs/<subsystem>.md - /frontend/docs/<subsystem>.md

Subsystem identification heuristics: - A cohesive domain handled by a directory or cluster of files - Examples: auth, billing, search, notifications, api-layer, data-layer, file-upload, websockets, admin, onboarding

Discovery checklist — identify a subsystem when you find: - [ ] A directory with 3+ related files - [ ] A shared service/utility used by 3+ other files - [ ] A distinct API surface (routes/controllers grouped by concern) - [ ] A background job or scheduled process - [ ] A third-party integration (Stripe, S3, Twilio, etc.)

If a subsystem doc already exists: - Compare it against current code - Remove anything describing code that no longer exists - Add anything the doc misses - Update all file maps, function names, and flow diagrams

Phase 3 — Global Architecture Document

Location: /docs/architecture.md (or /backend/docs/architecture.md depending on repo layout)

See references/architecture-doc.md for the full template.

Required sections: 1. System Overview — what this product does in 2–3 sentences 2. Subsystems — bulleted list, one-liner per subsystem, link to its .md 3. High-Level Diagram — ASCII or Mermaid, showing subsystem relationships 4. Tech Stack — language, framework, DB, cache, queue, infra 5. Cross-Cutting Concerns — how auth, error handling, validation, config, logging, and testing work across the system (not per-subsystem)

Phase 4 — API Reference

Required if a backend exists. Location: /backend/docs/api.md

For large backends: one file per subsystem, e.g. /backend/docs/api-auth.md, /backend/docs/api-billing.md, then an index in /backend/docs/api.md.

See references/api-reference.md for the full endpoint template.

Every endpoint must document: - Method + path - Description (1 sentence — what this does for the caller) - Request: path params, query params, body schema - Response: success schema + status codes + error codes - Source mapping: which controller file and service methods handle it

Phase 5 — Validation Pass

After writing or updating docs, audit them:

## Documentation Audit

### Missing
- List any subsystem without a doc

### Outdated
- List any doc that references removed files, functions, or endpoints

### Incorrect
- List any wrong dependency, wrong export name, wrong flow description

### Recommendations
- Specific fixes with file locations

Do not skip this pass. Stale documentation is worse than none — it actively misleads.

Enforcement Rules

These apply any time you touch code:

1. Changed a function's logic? → Update its header.
2. Added or removed an export? → Update the file header's Exports section.
3. Added a new file that others import? → Add the file header; update importers' "Imported By" lists if practical.
4. Added or changed an API endpoint? → Update api.md.
5. Structural change to a subsystem? → Update that subsystem's .md.
6. Added a new subsystem? → Create its .md from the template in references/subsystem-doc.md.
7. Removed a file or feature? → Find every doc that mentions it and remove those references.

Never leave documentation in a state that describes code that doesn't exist.

Quick Reference: What Goes Where

Reference Files

• references/subsystem-doc.md — Full subsystem doc template + instructions
• references/architecture-doc.md — Full architecture.md template

  這個技能的最新版本可以在7w4.net小蔥技能站找到。

• references/api-reference.md — Full API endpoint documentation template

這個 Skill 質量很好，提供了系統化的程式碼文件編寫規範，覆蓋原始碼註釋、子系統文件、全域性架構和 API 參考等各個層面，模板詳細可直接使用。優點是規則清晰、觸發條件明確、執行流程完整；不足是主要面向 JavaScript 專案，缺少自動化檢查工具，且沒有提供實際示例來演示標準效果。對於需要建立統一程式碼文件規範的團隊來說，這是一個可靠的選擇，但需要根據具體技術棧做適當調整。