> Documentation Standards
Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.
curl "https://skillshub.wtf/HoangNguyen0403/agent-skills-standard/documentation?format=md"Documentation Standards - High-Density Standards
Essential rules for code comments, READMEs, and technical documentation.
Priority: P2 (MAINTENANCE)
Essential rules for maintaining proper code comments, READMEs, and technical documentation.
📝 Code Comments (Inline Docs)
- "Why" over "What": Comments should explain non-obvious intent. Code should describe the logic.
- Docstrings: Use triple-slash (Dart/Swift) or standard JSDoc (TS/JS) for all public functions and classes.
- Maintenance: Delete "commented-out" code immediately; use Git history for retrieval.
- TODOs: Use
TODO(username): descriptionorFIXMEto track technical debt with ownership. - Workarounds: Document hacks and removal conditions (e.g., backend bug, version target).
- Performance Notes: Explain trade-offs only when performance-driven changes are made.
📖 README Essentials
- Mission: Clear one-sentence summary of the project purpose.
- Onboarding: Provide exact Prerequisites (runtimes), Installation steps, and Usage examples.
- Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
- Up-to-Date: Documentation is part of the feature; keep it synchronized with code changes.
🏛 Architectural & API Docs
- ADRs: Document significant architectural changes and the "Why" in
docs/adr/. - Docstrings: Document Classes and Functions with clear descriptions of Args, Returns, and usage Examples (
>>>). - Diagrams: Use Mermaid.js inside Markdown to provide high-level system overviews.
🚀 API Documentation
- Self-Documenting: Use Swagger/OpenAPI for REST or specialized doc generators for your language.
- Examples: Provide copy-pasteable examples for every major endpoint or utility.
- Contract First: Define the interface before the implementation.
> related_skills --same-repo
> typescript-tooling
Development tools, linting, and build config for TypeScript. Use when configuring ESLint, Prettier, Jest, Vitest, tsconfig, or any TS build tooling. (triggers: tsconfig.json, .eslintrc.*, jest.config.*, package.json, eslint, prettier, jest, vitest, build, compile, lint)
> typescript-security
Secure coding practices for TypeScript. Use when validating input, handling auth tokens, sanitizing data, or managing secrets and sensitive configuration. (triggers: **/*.ts, **/*.tsx, validate, sanitize, xss, injection, auth, password, secret, token)
> typescript-language
Modern TypeScript standards for type safety and maintainability. Use when working with types, interfaces, generics, enums, unions, or tsconfig settings. (triggers: **/*.ts, **/*.tsx, tsconfig.json, type, interface, generic, enum, union, intersection, readonly, const, namespace)
> typescript-best-practices
Idiomatic TypeScript patterns for clean, maintainable code. Use when writing or refactoring TypeScript classes, functions, modules, or async logic. (triggers: **/*.ts, **/*.tsx, class, function, module, import, export, async, promise)