skills.rest
authrain-cloud-abdullahformuli
authrain-cloud-abdullahformuliCOMMUNITY
Explore all skills by this author →
𝕏@abdullahformuliGitHub

documentation-and-adrs

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineering decisions and design rationale are often lost, forcing future engineers and AI 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 documentation. ## 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 comments that explain the why rather than restating code, plus typed API docs with parameters, return values, errors, and examples. - Project Documentation: Provides templates for READMEs (quick start, commands, architecture) and changelogs for shipped features. - Use Case: After choosing PostgreSQL over MongoDB for a new service, use this Skill to write an ADR documenting the requirements, rejected alternatives, and consequences so future contributors understand the rationale. ## Quick Start Ask the agent to write an ADR documenting the decision to use your chosen framework or database, including the alternatives you considered.

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

An ADR documents a significant technical decision with sections for status, date, context, the decision itself, alternatives considered with rejection reasons, and consequences. Store ADRs in docs/decisions/ with sequential numbering, or match your project's existing convention.

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 expensive to reverse. Skip ADRs for trivial or easily reversible choices.

What should code comments explain?▼

Comments should explain the why: non-obvious intent, constraints, and known gotchas. Avoid comments that restate what the code does, leftover TODOs for work you should do now, and commented-out code that version control already preserves.

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 old one, following the lifecycle of proposed, accepted, then superseded or deprecated.

What belongs in a project README?▼

A README should include a one-paragraph project description, quick start steps, a commands table, an architecture overview linking to ADRs, and contributing guidelines. It must explain how to install, configure, and run the project.

Related Skills

Explore More Software Engineering Skills→
kalamdbkalamdb
48

speckit-clarify

Resolve ambiguities in feature specifications through structured interactive questioning.

Official
Advanced
JacobThreeJacobThree

documentation-and-adrs

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

Community
Intermediate
vardhineediganesh877-uivardhineediganesh877-ui

ez-context

Extract coding conventions and generate CLAUDE.md, AGENTS.md, and Cursor rules with drift detection.

Community
Intermediate
plastikawebplastikaweb
1

code-documentation

Generate Markdown documentation, API references, and architecture guides from codebases.

Community
Basic