Publish Sign in

Documentation and ADRs

Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to…

You say
Install this skill Read the source first Free Written by addyosmani · unverified publisher
Context cost
2.5k tokensestimated from the bundle, loaded when it triggers
Bundle
1 file · 9.8 kBtext throughout, nothing executable
Licence
MITfree to use
Last change
—no release on file
Servers it uses
Noneruns standalone

What it does

Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Expertise

Domain judgement the base model does not have.

documentation
Filed under

Learning & Documentation

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md9.8 kB · 289 lines
--- name: documentation-and-adrs description: Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase. ---
6# Documentation and ADRs
7
8## Overview
9
10Document 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.
11
12## When to Use
13
14- Making a significant architectural decision
15- Choosing between competing approaches
16- Adding or changing a public API
17- Shipping a feature that changes user-facing behavior
18- Onboarding new team members (or agents) to the project
19- When you find yourself explaining the same thing repeatedly
20
21**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.
22
23## Architecture Decision Records (ADRs)
24
25ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.
26
27### When to Write an ADR
28
29- Choosing a framework, library, or major dependency
30- Designing a data model or database schema
31- Selecting an authentication strategy
32- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
33- Choosing between build tools, hosting platforms, or infrastructure
34- Any decision that would be expensive to reverse
35
36### Match the existing convention first
37
38Before creating an ADR, inspect the available repository context for an established convention — existing ADRs, project instructions, and ADR-related configuration or tooling (e.g. an .adr-dir file). An established convention overrides the defaults below. Match:
39
40- **Location and format** — e.g. docs/adr/*.md, Documentation/Decisions/*.rst, a MADR layout, or an adr-tools setup. Match the existing directory, file extension, and markup (Markdown vs reStructuredText).
41- **Numbering and naming** — continue the existing sequence and filename pattern (ADR-004-Title.rst, 0004-title.md, …); don't restart at 001 or introduce a second scheme.
42- **Section headings** — reuse the project's heading set rather than imposing this template's.
43
44If the available evidence conflicts, surface the conflict rather than silently introducing another scheme. Only when no convention can be established do you apply the default below.
45
46### ADR Template
47
48Store ADRs in docs/decisions/ with sequential numbering (unless the project already uses another location — see above):
49
50```markdown
51# ADR-001: Use PostgreSQL for primary database
52
53## Status
54Accepted | Superseded by ADR-XXX | Deprecated
55
56## Date
572025-01-15
58
59## Context
60We need a primary database for the task management application. Key requirements:
61- Relational data model (users, tasks, teams with relationships)
62- ACID transactions for task state changes
63- Support for full-text search on task content
64- Managed hosting available (for small team, limited ops capacity)
65
66## Decision
67Use PostgreSQL with Prisma ORM.
68
69## Alternatives Considered
70
71### MongoDB
72- Pros: Flexible schema, easy to start with
73- Cons: Our data is inherently relational; would need to manage relationships manually
74- Rejected: Relational data in a document store leads to complex joins or data duplication
75
76### SQLite
77- Pros: Zero configuration, embedded, fast for reads
78- Cons: Limited concurrent write support, no managed hosting for production
79- Rejected: Not suitable for multi-user web application in production
80
81### MySQL
82- Pros: Mature, widely supported
83- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
84- Rejected: PostgreSQL is the better fit for our feature requirements
85
86## Consequences
87- Prisma provides type-safe database access and migration management
88- We can use PostgreSQL's full-text search instead of adding Elasticsearch
89- Team needs PostgreSQL knowledge (standard skill, low risk)
90- Hosting on managed service (Supabase, Neon, or RDS)
91```
92
93### ADR Lifecycle
94
95```
96PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)
97```
98
99- **Don't delete old ADRs.** They capture historical context.
100- When a decision changes, write a new ADR that references and supersedes the old one.
101
102## Inline Documentation
103
104### When to Comment
105
106Comment the *why*, not the *what*:
107
108```typescript
109// BAD: Restates the code
110// Increment counter by 1
111counter += 1;
112
113// GOOD: Explains non-obvious intent
114// Rate limit uses a sliding window — reset counter at window boundary,
115// not on a fixed schedule, to prevent burst attacks at window edges
116if (now - windowStart > WINDOW_SIZE_MS) {
117 counter = 0;
118 windowStart = now;
119}
120```
121
122### When NOT to Comment
123
124```typescript
125// Don't comment self-explanatory code
126function calculateTotal(items: CartItem[]): number {
127 return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
128}
129
130// Don't leave TODO comments for things you should just do now
131// TODO: add error handling ← Just add it
132
133// Don't leave commented-out code
134// const oldImplementation = () => { ... } ← Delete it, git has history
135```
136
137### Document Known Gotchas
138
139```typescript
140/**
141 * IMPORTANT: This function must be called before the first render.
142 * If called after hydration, it causes a flash of unstyled content
143 * because the theme context isn't available during SSR.
144 *
145 * See ADR-003 for the full design rationale.
146 */
147export function initializeTheme(theme: Theme): void {
148 // ...
149}
150```
151
152## API Documentation
153
154For public APIs (REST, GraphQL, library interfaces):
155
156### Inline with Types (Preferred for TypeScript)
157
158```typescript
159/**
160 * Creates a new task.
161 *
162 * @param input - Task creation data (title required, description optional)
163 * @returns The created task with server-generated ID and timestamps
164 * @throws {ValidationError} If title is empty or exceeds 200 characters
165 * @throws {AuthenticationError} If the user is not authenticated
166 *
167 * @example
168 * const task = await createTask({ title: 'Buy groceries' });
169 * console.log(task.id); // "task_abc123"
170 */
171export async function createTask(input: CreateTaskInput): Promise<Task> {
172 // ...
173}
174```
175
176### OpenAPI / Swagger for REST APIs
177
178```yaml
179paths:
180 /api/tasks:
181 post:
182 summary: Create a task
183 requestBody:
184 required: true
185 content:
186 application/json:
187 schema:
188 $ref: '#/components/schemas/CreateTaskInput'
189 responses:
190 '201':
191 description: Task created
192 content:
193 application/json:
194 schema:
195 $ref: '#/components/schemas/Task'
196 '422':
197 description: Validation error
198```
199
200## README Structure
201
202Every project should have a README that covers:
203
204```markdown
205# Project Name
206
207One-paragraph description of what this project does.
208
209## Quick Start
2101. Clone the repo
2112. Install dependencies: npm install
2123. Set up environment: cp .env.example .env
2134. Run the dev server: npm run dev
214
215## Commands
216| Command | Description |
217|---------|-------------|
218| npm run dev | Start development server |
219| npm test | Run tests |
220| npm run build | Production build |
221| npm run lint | Run linter |
222
223## Architecture
224Brief overview of the project structure and key design decisions.
225Link to ADRs for details.
226
227## Contributing
228How to contribute, coding standards, PR process.
229```
230
231## Changelog Maintenance
232
233For shipped features:
234
235```markdown
236# Changelog
237
238## [1.2.0] - 2025-01-20
239### Added
240- Task sharing: users can share tasks with team members (#123)
241- Email notifications for task assignments (#124)
242
243### Fixed
244- Duplicate tasks appearing when rapidly clicking create button (#125)
245
246### Changed
247- Task list now loads 50 items per page (was 20) for better UX (#126)
248```
249
250## Documentation for Agents
251
252Special consideration for AI agent context:
253
254- **CLAUDE.md / rules files** — Document project conventions so agents follow them
255- **Spec files** — Keep specs updated so agents build the right thing
256- **ADRs** — Help agents understand why past decisions were made (prevents re-deciding)
257- **Inline gotchas** — Prevent agents from falling into known traps
258
259## Common Rationalizations
260
261| Rationalization | Reality |
262|---|---|
263| "The code is self-documenting" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. |
264| "We'll write docs when the API stabilizes" | APIs stabilize faster when you document them. The doc is the first test of the design. |
265| "Nobody reads docs" | Agents do. Future engineers do. Your 3-months-later self does. |
266| "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. |
267| "Comments get outdated" | Comments on *why* are stable. Comments on *what* get outdated — that's why you only write the former. |
268
269## Red Flags
270
271- Architectural decisions with no written rationale
272- Public APIs with no documentation or types
273- README that doesn't explain how to run the project
274- Commented-out code instead of deletion
275- TODO comments that have been there for weeks
276- No ADRs in a project with significant architectural choices
277- Documentation that restates the code instead of explaining intent
278
279## Verification
280
281After documenting:
282
283- [ ] ADRs exist for all significant architectural decisions
284- [ ] README covers quick start, commands, and architecture overview
285- [ ] API functions have parameter and return type documentation
286- [ ] Known gotchas are documented inline where they matter
287- [ ] No commented-out code remains
288- [ ] Rules files (CLAUDE.md etc.) are current and accurate
289
In the file
SKILL.md1,470 words
Files1
LicenceMIT
Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈70
always loaded
The name and description, so the model knows the skill exists and when to reach for it.
2,380
on trigger
The instruction body, read only when the skill fires.
1.2%
of a 200k window
Ten skills this size would take about 12% of the window before you open a file.
050k100k150k200k context window

2.5k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Middling. Fine to keep on in a project where you use it weekly, worth unloading in one where you never do.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption
Installsnone yet
Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It writes no files and reaches no network. All it changes is how the model reasons and writes.

What it asks for
Writes filesno
Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

What is in the bundle

1 file, 9.8 kB on disk. A bundle is text throughout: the instructions the model reads, plus the templates it fills in.

  • SKILL.md9.8 kB
What is not in it

No dependencies and nothing executable: a skill is text the agent reads, so the bundle is 1 file you can review in full before installing. The MIT licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

# Documentation and ADRs · 2.5k tokens when loaded npx mcprush@latest skill add addyosmani/documentation-and-adrs

Writes to .claude/skills/documentation-and-adrs/ in the current project. Add --global to put it in your home directory instead, for every project.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/
Claude Desktop
ChatGPT
Cursor.cursor/skills/
VS Code.github/skills/
Codex CLI.agents/skills/
Gemini CLI.gemini/skills/
Grok.grok/skills/
Zed.agents/skills/
Windsurf.windsurf/skills/
Agent SDK.claude/skills/
HTTP / API
This release
Versionnot versioned
Publishedno release date on file
PriceFree
Referenceaddyosmani/documentation-and-adrs

Versions

Its author publishes no version number, so there is nothing here to pin to: what you install is the folder as it stands today. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

v
  • No earlier releases have been published to the marketplace.
Pinning

Nothing to pin to: this skill carries no version number of its own. What you install is what the folder holds on the day you install it.

Reviews

—no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Who wrote it

AD
addyosmani

Publishes on mcprush.

0 servers listed13 skills listednot claimed
Profile
Publisher
Servers0