skills.rest
addyosmani
addyosmaniCOMMUNITY
Explore all skills by this author →
Website𝕏@addyosmaniGitHub

documentation-and-adrs

Create and maintain project documentation including ADRs, API specs, and changelogs.

84.9k|9.1k|Updated Feb 15, 2026
Search Tags:#changelog#architecture#documentation#adr#readme#code comments#api documentation
One-click install
npx skills add https://github.com/addyosmani/agent-skills --skill documentation-and-adrs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: documentation-and-adrs
Source: https://github.com/addyosmani/agent-skills/tree/main/skills/documentation-and-adrs
Command: npx skills add https://github.com/addyosmani/agent-skills --skill documentation-and-adrs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the critical need to capture the rationale behind technical decisions, ensuring long-term project maintainability and clarity for both human and AI collaborators.

Core Features & Use Cases

  • Architectural Decision Records (ADRs): Formalizes the process of documenting significant technical choices, including context, alternatives considered, and consequences.
  • Inline Documentation Best Practices: Guides on writing effective comments that explain the "why" rather than the "what," and when not to comment.
  • API Documentation Standards: Provides examples for documenting public APIs using JSDoc-style comments and OpenAPI/Swagger specifications.
  • README Structure: Outlines essential sections for a project's README file to ensure discoverability and ease of onboarding.
  • Changelog Maintenance: Offers a template and guidelines for maintaining a clear and informative changelog.
  • Agent-Specific Documentation: Highlights the importance of documentation for AI agents, including ADRs and inline comments.
  • Use Case: When making a significant architectural choice, like selecting a new database technology, use this Skill to generate an ADR that clearly outlines the reasons for the choice, alternatives considered, and potential impacts.

Quick Start

Use the documentation-and-adrs skill to generate an Architecture Decision Record for a new database choice.

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 for a new database choice?▼

To write an Architecture Decision Record (ADR), document the context, alternatives considered, and consequences of the technical choice. This ensures long-term project maintainability and captures the rationale behind significant architectural decisions for future reference.

What is the best way to document API specifications and inline code comments?▼

The best way to document API specifications is using OpenAPI or Swagger, while inline comments should explain the 'why' rather than the 'what'. Standardizing API documentation and code comments ensures clarity and effective knowledge transfer for collaborators.

How do I structure a README file to make project onboarding easier?▼

To structure a README file, outline essential sections that ensure project discoverability and ease of onboarding. A well-structured README provides clear guidance for new collaborators and establishes standard documentation practices.

Why does maintaining a changelog help with project documentation?▼

Maintaining a changelog helps project documentation by offering a clear, informative record of changes over time. Using a standard changelog template ensures maintainability and effective knowledge transfer, allowing teams to track project evolution accurately.

When do I need Architecture Decision Records in my software engineering workflow?▼

You need Architecture Decision Records (ADRs) when making significant architectural choices, such as selecting a new database technology. ADRs formalize the process of documenting technical implementations, ensuring the rationale behind decisions is captured for collaborators.

Related Skills

Explore More Software Engineering Skills→
Prompt-or-Die-LabsPrompt-or-Die-Labs
7

ADR Assistant

Analyze existing ADRs and draft new ones with consistent structure and tradeoffs.

Official
Intermediate
JongsixJongsix

moai-docs-generation

Generate technical documentation from source code and API definitions.

Community
Advanced
hiro0218hiro0218
8

code-comment-guidelines

Enforce code-comment guidelines and JSDoc for public APIs.

Community
Advanced
ev3rlitev3rlit

architecture-decision-records

Manage architecture decision records with standardized templates and lifecycle statuses.

Community
Advanced