JPeetz/agent-skills / skills/documentation-content/documentation-and-adrs
documentation-and-adrs
VerifiedUse this skill when you need to record an architecture decision (ADR) or document the reasoning behind a design choice — when changing public APIs, shipping features that change behavior, or recording context that future engineers (human or agent) will need to understand the codebase. Does NOT replace code comments or inline docstrings; targets strategic documentation and decision capture. Primary keywords: ADR architecture decision record, technical documentation, design rationale, decision log, API documentation, README writing, changelog, documentation-driven development, inline documentation best practices, specification writing. For all major agentic platforms.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 941 B |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 12.0 KB |
| evals/evals.json | config | 5.9 KB |
| references/adr-template.md | markdown | 2.3 KB |
| references/api-docs-checklist.md | markdown | 2.0 KB |
| references/readme-template.md | markdown | 2.1 KB |
references/adr-template.md
View on GitHub# ADR-NNNN: [Short Title of Decision]
- **Status**: [proposed | accepted | rejected | deprecated | superseded by ADR-NNNN]
- **Date**: YYYY-MM-DD
- **Deciders**: [list of people involved in the decision]
- **Technical Story**: [ticket/issue URL or description of the problem]
---
## Context and Problem Statement
[Describe the context and problem statement in 2-3 paragraphs. What forces
are at play? What constraints exist? What triggered this decision now and
not earlier or later? What is the concrete problem we're solving?]
## Decision Drivers
- [driver 1, e.g., scalability requirement]
- [driver 2, e.g., team expertise with technology]
- [driver 3, e.g., cost constraint]
- [driver 4, e.g., time-to-market pressure]
- [driver 5, e.g., compliance/regulatory requirement]
## Considered Options
### Option 1: [Name]
[Detailed description. Enough detail that someone who joins the team in 2
years can understand what this option entailed.]
**Pros:**
- [pro 1]
- [pro 2]
- [pro 3]
**Cons:**
- [con 1]
- [con 2]
- [con 3]
### Option 2: [Name]
[Detailed description.]
**Pros:**
- [pro 1]
- [pro 2]
**Cons:**
- [con 1]
- [con 2]
### Option 3: [Name]
[Include "do nothing" or "status quo" as an option when applicable.]
**Pros:**
- [pro 1]
**Cons:**
- [con 1]
## Decision Outcome
**Chosen option**: "[Option X — Name]", because [summary of the key reason
in one sentence].
### Positive Consequences
- [e.g., improvement in X metric, reduced complexity, team alignment]
- [e.g., enables future Y capability]
### Negative Consequences
- [e.g., increased operational overhead for Z]
- [e.g., learning curve for team members]
- [e.g., migration cost from existing system]
### Mitigations
- For [negative consequence 1]: [how we'll mitigate it]
- For [negative consequence 2]: [how we'll mitigate it]
## Implementation Plan
1. [Step 1 — who, what, by when]
2. [Step 2 — who, what, by when]
3. [Step 3 — who, what, by when]
4. [Validation: how will we know the decision was correct?]
## Links
- [Link to relevant documentation, RFC, or external resource]
- [Link to related ADRs]
- [Link to the PR or issue where this was discussed]
---
*Template based on [Michael Nygard's ADR format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
with extensions for implementation planning and mitigation tracking.*Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |