skills.rest
visdomtech
visdomtechOFFICIAL
Explore all skills by this author →
WebsiteGitHub

documentation-and-adrs

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

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

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 reasoning behind architectural decisions, APIs, and features in durable written records. ## Core Features & Use Cases - Architecture Decision Records (ADRs): Creates sequentially numbered ADRs with context, decision, alternatives considered, and consequences, while matching any existing project convention for location, numbering, and format. - Inline and API Documentation: Guides writing why-focused code comments, JSDoc/TSDoc annotations, and OpenAPI specs for public interfaces. - READMEs and Changelogs: Provides templates for project READMEs (quick start, commands, architecture) and Keep-a-Changelog-style release notes. - Use Case: After choosing PostgreSQL over MongoDB for a new service, ask the agent to write an ADR documenting the context, rejected alternatives, and consequences so future contributors understand the decision. ## Quick Start Ask the agent to write an ADR documenting why you chose your current database or framework, following any existing ADR convention in the repository.

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 the context, decision, alternatives considered, and consequences of a significant technical choice. Store it as a sequentially numbered Markdown file (e.g., docs/decisions/ADR-001-title.md) and mark its status as Proposed, Accepted, Superseded, or Deprecated.

When should I write an ADR versus a code comment?▼

Write an ADR for decisions that are expensive to reverse, such as choosing frameworks, databases, or API architectures. Use inline comments only to explain non-obvious intent or known gotchas, never to restate what the code already says.

Should ADRs follow my project's existing format?▼

Yes. Inspect the repository for existing ADRs, an .adr-dir file, or ADR tooling, and match the established directory, file extension, numbering sequence, and section headings. Only apply a default template when no convention exists.

What should a project README include?▼

A README should contain a one-paragraph project description, quick start steps, a commands table (dev, test, build, lint), a brief architecture overview linking to ADRs, and contributing guidelines.

When should I not write documentation?▼

Skip documentation for self-explanatory code, throwaway prototypes, and comments that restate what the code does. Avoid TODO comments for work you should do now and delete commented-out code instead of preserving it.

Related Skills

Explore More Software Engineering Skills→
michael-watsonmichael-watson
8

rpi-research

Analyze codebase architecture, dependencies, and constraints into a research document.

Community
Intermediate
zorgentechzorgentech

adr-approve

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

Official
Advanced
douglancedouglance
4

documentation

Write and verify README, API, and ADR documentation against shipped code behavior.

Community
Basic
VitaDynamicsVitaDynamics

adr

Create sequentially numbered Architecture Decision Records in docs/adr/.

Official
Intermediate