Documentation And Adrs

This one keeps you from re-litigating the same architectural decisions every six months. It pushes you to write ADRs when choosing databases, frameworks, or API patterns, with a solid template that captures context, alternatives considered, and consequences. The inline documentation guidance is spot on: comment the why, not the what, and document gotchas that will bite future engineers or agents. Includes practical templates for API docs, READMEs, and changelogs. The "common rationalizations" section cuts through the usual excuses about self-documenting code. Most valuable for teams that keep rebuilding context from scratch because nobody wrote down why they picked PostgreSQL over MongoDB.

skills.sh installs: 73.5K
GitHub stars: 114.6K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add addyosmani/agent-skills --skill documentation-and-adrs --agent claude-code

Installs into .claude/skills of the current project.

Files

Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why — the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.

When to Use

Making a significant architectural decision
Choosing between competing approaches
Adding or changing a public API
Shipping a feature that changes user-facing behavior
Onboarding new team members (or agents) to the project
When you find yourself explaining the same thing repeatedly

When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.