skills.rest
DagimAlemayehuu
DagimAlemayehuuCOMMUNITY
Explore all skills by this author →
GitHub

documentation-and-adrs

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

Updated Jul 19, 2026
Search Tags:#changelog#documentation#technical writing#adr#readme#architecture decisions#api documentation
One-click install
npx skills add https://github.com/DagimAlemayehuu/AgenticEngineering --skill documentation-and-adrs-dagimalemayehuu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/DagimAlemayehuu/AgenticEngineering/tree/main/agentic-engineering/core/dependencies/planning/documentation-and-adrs
Command: npx skills add https://github.com/DagimAlemayehuu/AgenticEngineering --skill documentation-and-adrs-dagimalemayehuu

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 decisions, lose context, and onboard engineers or agents without the rationale behind architectural choices. ## Core Features & Use Cases - Architecture Decision Records (ADRs): Capture context, decision, alternatives considered, and consequences for significant technical choices, with lifecycle tracking from Proposed to Accepted to Superseded. - Convention Matching: Detects existing ADR conventions in the repository (location, numbering, headings, format) and follows them instead of imposing a new scheme. - Inline and API Documentation: Guidance for why-focused comments, TypeScript docstrings, OpenAPI specs, README structure, and changelogs. - Use Case: After choosing PostgreSQL over MongoDB for a new service, record an ADR documenting the requirements, rejected alternatives, and consequences so future engineers and agents never re-litigate the decision. ## Quick Start Use the documentation-and-adrs skill to write an ADR for the database decision we just made and update the project README.

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?▼

An ADR documents the context, the decision, alternatives considered with rejection reasons, and consequences. Store it in docs/decisions/ with sequential numbering, or match your repository's existing ADR convention for location, format, and naming.

When should I write an ADR?▼

Write an ADR for decisions that are expensive to reverse: choosing frameworks or databases, designing data models, selecting authentication strategies, or picking API architectures. Skip ADRs for trivial or easily reversible choices.

Should I update or delete an old ADR when a decision changes?▼

Never delete old ADRs since they preserve historical context. Write a new ADR that references and supersedes the old one, and update the old ADR's status to Superseded by the new record.

What code comments are worth writing?▼

Comment the why, not the what: explain non-obvious intent, constraints, and known gotchas. Avoid comments that restate the code, stale TODOs, and commented-out code, which should be deleted since version control keeps history.

What should a project README include?▼

A README should contain a one-paragraph project description, quick start steps, a commands table, an architecture overview linking to ADRs, and contributing guidelines covering standards and the PR process.

Related Skills

Explore More Software Engineering Skills→
jtvarisjtvaris

architecture-decision

Generate Architecture Decision Records with context, constraints, and alternatives.

Community
Intermediate
zorgentechzorgentech

adr-approve

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

Official
Advanced
klhklh
9

documentation-and-adrs

Record architectural decisions and documentation with context, rationale, alternatives, and consequences.

Community
Intermediate
Integra-BeautyIntegra-Beauty

integra-git-conventions

Enforce kebab-case branch names, conventional commits, and repository naming conventions.

Official
Intermediate