skills.rest
TylerSimons1127
TylerSimons1127COMMUNITY
Explore all skills by this author →
GitHub

addy-documentation-and-adrs

Writes Architecture Decision Records, API documentation, READMEs, and changelogs for codebases.

Updated Aug 21, 2026
Search Tags:#changelog#documentation#adr#readme#API documentation#architecture decisions#engineering workflow
One-click install
npx skills add https://github.com/TylerSimons1127/vibe --skill addy-documentation-and-adrs-tylersimons1127
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: addy-documentation-and-adrs
Source: https://github.com/TylerSimons1127/vibe/tree/main/skills/addy-documentation-and-adrs
Command: npx skills add https://github.com/TylerSimons1127/vibe --skill addy-documentation-and-adrs-tylersimons1127

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineering decisions and their rationale are often lost, forcing future developers and agents to re-debate settled choices or guess why code was written a certain way. This Skill captures the context, constraints, and trade-offs behind decisions in durable written form. ## Core Features & Use Cases - Architecture Decision Records (ADRs): Creates sequentially numbered ADRs with status, context, decision, alternatives considered, and consequences, while matching any existing project convention for location, numbering, and headings. - Inline and API Documentation: Guides writing why-focused comments, JSDoc/TSDoc annotations, and OpenAPI specs for public interfaces. - READMEs and Changelogs: Provides templates for project READMEs (quick start, commands, architecture) and structured changelogs for shipped features. - Use Case: After choosing PostgreSQL over MongoDB for a new service, use this Skill to write ADR-001 documenting the requirements, rejected alternatives, and consequences so future engineers understand the reasoning. ## Quick Start Write an ADR documenting the decision to use tRPC instead of REST for the new API, including the alternatives considered.

Frequently Asked Questions about addy-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?▼

An ADR documents a significant technical decision with sections for status, date, context, decision, alternatives considered, and consequences. Store it in docs/decisions/ with sequential numbering, or match your project's existing ADR convention if one exists.

When should I write an ADR for a project?▼

Write an ADR when choosing frameworks or major dependencies, designing data models, selecting authentication strategies, deciding API architecture, or making any decision expensive to reverse. Skip ADRs for trivial or easily reversible choices.

What is the difference between good and bad code comments?▼

Good comments explain why code exists, such as non-obvious intent, constraints, or known gotchas. Bad comments restate what the code already says, leave stale TODOs, or preserve commented-out code that version control already tracks.

Should old ADRs be deleted when a decision changes?▼

No, old ADRs should never be deleted because they capture historical context. When a decision changes, write a new ADR that references and supersedes the previous one, following the PROPOSED to ACCEPTED to SUPERSEDED lifecycle.

How does documentation help AI coding agents?▼

Agents read ADRs to understand why past decisions were made, preventing them from re-deciding settled questions. Rules files, updated specs, and inline gotcha documentation also keep agents from repeating known traps.

Related Skills

Explore More Software Engineering Skills→
compozycompozy
2.5k

cy-create-techspec

Generates a complete draft of TechSpec and companion documents from your uploaded files.

Official
Advanced
zorgentechzorgentech

adr-approve

Move approved ADR files to docs/adr and update status via GitHub CLI.

Official
Advanced
agentpatternsagentpatterns
5

adr

Create and manage Architecture Decision Records with structured YAML frontmatter.

Official
Intermediate
baotoqbaotoq
98

architecture-decision-records

Capture and manage architectural decisions with standardized ADR templates.

Community
Intermediate