skills.rest
alissonpef
alissonpefCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

documentation-and-adrs

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases lose critical context over time: engineers forget why decisions were made, APIs ship undocumented, and new team members or AI agents repeatedly re-litigate settled questions. This Skill provides structured templates and rules for capturing the reasoning behind technical decisions. ## Core Features & Use Cases - Architecture Decision Records (ADRs): A numbered template with Status, Context, Decision, Alternatives Considered, and Consequences sections, stored in docs/decisions/ with a PROPOSED → ACCEPTED → SUPERSEDED lifecycle. - Inline and API Documentation: Rules for commenting the why instead of the what, plus TypeScript JSDoc and OpenAPI/Swagger examples for public interfaces. - README and Changelog Standards: Templates covering quick start, command tables, architecture overviews, and versioned changelogs. - Use Case: After choosing PostgreSQL over MongoDB for a new service, invoke this Skill to produce ADR-001 documenting the requirements, rejected alternatives, and consequences so future engineers and agents understand the rationale. ## Quick Start Ask the agent to write an ADR documenting the architectural decision you just made, including the alternatives considered and their trade-offs.

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 numbered markdown file in docs/decisions/ with sections for Status, Date, Context, Decision, Alternatives Considered, and Consequences. Document why each alternative was rejected, and never delete old ADRs—supersede them with new ones.

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 why code exists, not what it does. Document non-obvious intent, constraints, and known gotchas. Avoid restating self-explanatory code, leaving stale TODOs, or keeping commented-out code that git history already preserves.

How do I document a TypeScript public API?▼

Use JSDoc comments with @param, @returns, @throws, and @example tags directly on exported functions. For REST APIs, maintain an OpenAPI/Swagger specification describing endpoints, request schemas, and response codes.

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. Documentation effort belongs on decisions, constraints, and context that code cannot express.

Related Skills

Explore More Software Engineering Skills→
mpazarynampazaryna
1

technical-decision

Analyze technical options and draft an Architecture Decision Record.

Community
Advanced
zorgentechzorgentech

adr-approve

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

Official
Advanced
ludicroushqludicroushq

code-style

Enforce code style conventions for components, functions, and destructuring patterns.

Official
Intermediate
kriscardkriscard
13

doc-coauthoring

Automate stage-based collaborative authoring of RFCs, ADRs, and proposals.

Community
Intermediate