documentation-and-adrs

An agent skill by addyosmani, from addyosmani/agent-skills. Tags: api, developer-tools, documents.

What it does

Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add addyosmani/agent-skills --skill documentation-and-adrs

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/addyosmani/agent-skills
cp -r agent-skills/skills/documentation-and-adrs ~/.claude/skills/documentation-and-adrs

Safety box score

Grade A, minimal risk: 4 of 100 risk points, rated 2026-10-19. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This skill is a documentation-only guide: it tells an agent how to write ADRs, README content, changelogs, and inline comments in the repository. It does not ship code or automation, so the main exposure is in-repo file edits and the possibility of documenting the wrong convention if existing project structure is not checked first.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	0 (none)	No scripts, shell commands, or code evaluators are shipped; the file is prose guidance only.
Network access	0 (none)	It does not fetch remote content or send data to external services.
Filesystem reach	1 (low)	The skill is meant to write documentation in the repo, e.g. "Store ADRs in `docs/decisions/`" and update README/changelog/comments.
Secrets & credentials	0 (none)	It does not ask for tokens, passwords, key files, or browser sessions; the `.env.example` mention is only a README template example.
Privilege & persistence	0 (none)	No sudo, global installs, services, shell startup edits, or OS-level changes are requested.
Instruction hijack surface	0 (none)	There is no instruction to ignore safeguards, follow remote instructions, hide behavior, or override system prompts.
Irreversible actions	0 (none)	It documents decisions and code, but does not itself push, publish, delete, pay, book, or send messages.
Transparency	0 (none)	All shipped content is readable markdown; there are no binaries, generated blobs, or decoded-at-runtime scripts.

Before installing

Check whether the repo already has ADR tooling or an existing decisions directory before applying the default `docs/decisions/` layout.
Verify the README/changelog conventions in the target project so the skill does not introduce a second format.
If you plan to use the `.env` example text, confirm it is only documentation and not a real environment-file workflow in this repo.

Rated 2026-10-19 by an automated review of 1 file from the skill's repository.

Source

Repository: addyosmani/agent-skills (all skills from this repository)
Path: skills/documentation-and-adrs/SKILL.md
Branch: main
Updated: 2026-09-19

deprecation-and-migration — Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another.
source-driven-development — Grounds every implementation decision in official documentation.
code-documenter — Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides.
intended-vs-implemented — The method for finding the gap between what a system is supposed to do and what the code actually does — the class of bug generic scanners miss because they.
shipping-artifacts — The durable documentation set that makes an AI-built (vibe-coded) app reviewable before shipping.
writing-skills — Use when creating new skills, editing existing skills, or verifying skills work before deployment