skills.rest
PHenrique07
PHenrique07COMMUNITY
Explore all skills by this author →
GitHub

documentation-and-adrs

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

5|Updated Feb 12, 2026
Search Tags:#changelog#documentation#technical writing#adr#readme#API documentation#architecture decisions
One-click install
npx skills add https://github.com/PHenrique07/Sementis-IFSP-Pirituba --skill documentation-and-adrs-phenrique07
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/PHenrique07/Sementis-IFSP-Pirituba/tree/main/.github/skills/documentation-and-adrs
Command: npx skills add https://github.com/PHenrique07/Sementis-IFSP-Pirituba --skill documentation-and-adrs-phenrique07

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineering teams lose critical context about why technical decisions were made, leading to repeated debates, undocumented APIs, and onboarding friction. This Skill captures the reasoning behind architectural choices and keeps project documentation accurate and useful. ## 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, naming, and format. - Inline and API Documentation: Guides writing comments that explain intent rather than restating code, plus typed docstrings and OpenAPI specs for public interfaces. - README and Changelog Maintenance: Provides templates for quick-start READMEs and versioned changelogs for shipped features. - Use Case: After choosing Flask with SQLite over PostgreSQL for a backend, use this Skill to write an ADR recording the requirements, rejected alternatives, and consequences so future contributors understand the trade-offs. ## Quick Start Ask the AI to write an ADR documenting why the project uses Flask and SQLite for its backend architecture.

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 status, date, context, decision, alternatives considered, and consequences of a significant technical choice. 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 that would be expensive to reverse.

What should code comments explain in a codebase?▼

Comments should explain why code behaves a certain way, not restate what it does. Document non-obvious intent, constraints, and known gotchas, and avoid TODO comments, commented-out code, and comments on self-explanatory functions.

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.

What sections should a project README include?▼

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

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
d0whc3rd0whc3r
2

documentation-and-adrs

Record architectural decision rationale using a structured ADR template.

Community
Basic
douglancedouglance
4

documentation

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

Community
Basic
Jimmy-JungJimmy-Jung

comment-checker

Detect redundant, outdated, or misleading code comments and propose rewrites.

Community
Advanced