skills.rest
SanHsien
SanHsienCOMMUNITY
Explore all skills by this author →
𝕏@Hsien_3GitHub

documentation-and-adrs

Writes architecture decision records, API documentation, READMEs, and changelogs for software projects.

1|Updated Sep 4, 2026
Search Tags:#changelog#documentation#technical writing#adr#readme#architecture decisions#api documentation
One-click install
npx skills add https://github.com/SanHsien/agent-skills --skill documentation-and-adrs-sanhsien
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/SanHsien/agent-skills/tree/main/skills/documentation-and-adrs
Command: npx skills add https://github.com/SanHsien/agent-skills --skill documentation-and-adrs-sanhsien

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code shows what was built but not why it was built that way, so teams repeatedly re-debate old decisions and new engineers or agents lack the context to work safely in a codebase. ## Core Features & Use Cases - Architecture Decision Records (ADRs): Capture context, decision, alternatives considered, and consequences for significant technical choices, while matching any existing ADR convention in the repository. - Inline and API Documentation: Comment the why behind non-obvious code, document public APIs with typed docstrings or OpenAPI, and record known gotchas. - Project Documentation: Structure READMEs with quick start and commands, and maintain changelogs for shipped features. - Use Case: After choosing PostgreSQL over MongoDB for a new service, record an ADR with the requirements, rejected alternatives, and consequences so future engineers and agents do not re-litigate the decision. ## Quick Start Ask the agent to write an ADR documenting the database or framework decision you just made, including the alternatives you rejected and why.

Frequently Asked Questions about documentation-and-adrs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an architecture decision record?▼

Create a Markdown file with sections for status, date, context, decision, alternatives considered, and consequences. Store ADRs in docs/decisions with sequential numbering, or match the existing ADR convention already used in your repository.

When should I write an ADR?▼

Write an ADR when choosing frameworks or major dependencies, designing data models, selecting authentication strategies, deciding API architecture, or making any decision that would be expensive to reverse.

What should code comments explain?▼

Comments should explain why the code does something, not what it does. Document non-obvious intent, constraints, and known gotchas, and avoid comments that restate self-explanatory code or leave stale TODOs.

Should old ADRs be deleted when a decision changes?▼

No. Old ADRs capture historical context and should be kept. When a decision changes, write a new ADR that references and supersedes the previous one, following the proposed, accepted, superseded lifecycle.

When should I not write documentation?▼

Skip documentation for obvious self-explanatory code, throwaway prototypes, and comments that merely restate what the code already says. Focus documentation effort on decisions, public APIs, and non-obvious behavior.

Related Skills

Explore More Software Engineering Skills→
NSObjectsNSObjects
4

designing

Define architecture decisions and map requirements to technical approaches before planning.

Community
Advanced
japurcelljapurcell

addy-documentation-and-adrs

Record architectural decisions and documentation for software projects.

Community
Advanced
AZANIRAZANIR
2

qa-spec-auditor

Audit specifications against live UI behavior, API contracts, and test results.

Community
Advanced
jamestorrevillasjamestorrevillas
3

code-explanation

Generate inline comments and documentation notes explaining code decisions.

Community
Intermediate