skills.rest
insightriot
insightriotOFFICIAL
Explore all skills by this author →
GitHub

documentation-and-adrs

Write ADRs, API docs, READMEs, and changelogs that capture architectural decision rationale.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code shows what was built but not why it was built that way. This Skill captures the context, constraints, and trade-offs behind technical decisions so future engineers and AI agents stop re-litigating settled choices or falling into known traps. ## Core Features & Use Cases - Architecture Decision Records (ADRs): A numbered template with status lifecycle (Proposed → Accepted → Superseded/Deprecated), alternatives analysis, and consequences, stored in docs/decisions/. - Inline and API Documentation: Guidance on commenting the why rather than the what, JSDoc/TSDoc patterns for public APIs, and OpenAPI/Swagger examples for REST endpoints. - Project Documentation Standards: README structure (quick start, commands, architecture), changelog format, and agent-facing docs like CLAUDE.md rules files. - Use Case: After choosing PostgreSQL over MongoDB and SQLite for a task app, write ADR-001 recording the requirements, rejected alternatives, and consequences so the decision is never re-debated six months later. ## Quick Start Ask the agent to write an ADR documenting the architectural decision you just made, including the alternatives considered and why they were rejected.

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 (ADR)?▼

Create a numbered Markdown file in docs/decisions/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Record why each alternative was rejected, not just which option won.

When should I write an ADR for a technical decision?▼

Write an ADR when choosing frameworks, databases, authentication strategies, API architectures, or any decision expensive to reverse. Skip ADRs for throwaway prototypes and easily reversible choices.

What should code comments explain versus restate?▼

Comments should explain why code exists, non-obvious constraints, and known gotchas. Never restate what the code already says, leave stale TODOs, or keep commented-out code that git history already preserves.

Should old ADRs be deleted when a decision changes?▼

No. Old ADRs capture historical context and should be kept. Write a new ADR that references and supersedes the old one, updating its status to Superseded by ADR-XXX.

How does documentation help AI coding agents?▼

Agents read CLAUDE.md rules files, specs, and ADRs to follow project conventions and avoid re-deciding settled questions. Inline gotcha comments prevent agents from repeating known traps.

Related Skills

Explore More Software Engineering Skills→
lllooollpplllooollpp

architecture-decision-records

Record architectural decisions as ADR documents with rationale and trade-offs.

Community
Advanced
PostalocityPostalocity
1

tech-writer

Generate developer-facing documentation from code and design artifacts.

Official
Intermediate
YazanKittanehYazanKittaneh

review

Enforces a standardized PR review checklist covering tests, linting, documentation, and descriptions before merging or opening pull requests.

Community
Intermediate
lunaticwithaducklunaticwithaduck
2

documentation

Guides creation of API references, READMEs, changelogs, ADRs, and documentation sites.

Community
Intermediate