Skillshub Documentation Standards

Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.

install

source · Clone the upstream repo

git clone https://github.com/ComeOnOliver/skillshub

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ComeOnOliver/skillshub "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/HoangNguyen0403/agent-skills-standard/documentation" ~/.claude/skills/comeonoliver-skillshub-documentation-standards && rm -rf "$T"

manifest: skills/HoangNguyen0403/agent-skills-standard/documentation/SKILL.md

source content

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): description
```
or
```
FIXME
```
to 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.