documentation-and-adrs

75 / 100 · Review before installing

Check before installing.

By addyosmani/agent-skills (GitHub) · writing · 117,315 stars · scanned at commit 39b723c

Records decisions and documentation, and detects when documentation has drifted from the code it describes. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, when docs may be stale or out of sync with the code they describe, when working out which module docs are still accurate, or when setting up a check so docs cannot silently go out of date again.

Works with any agent that supports SKILL.md skills.

What this skill can do

Runs commands on your computer

The author does not mention this.

Found in 1 place.

skills/documentation-and-adrs/SKILL.md, line 273code=$(git log -1 --format=%H -- src/rate-limiter.js)

Connects to the internet

The author does not mention this. It runs automatically when the plugin is installed.

Found in 16 places.

hooks/SDD-CACHE.md, line 3Cross-session citation cache for [`source-driven-development`](../skills/source-driven-development/SKILL.md). Skips redundant `WebFetch` calls without weakening
hooks/SDD-CACHE.md, line 20"matcher": "WebFetch",
hooks/SDD-CACHE.md, line 32"matcher": "WebFetch",

Show 13 more

hooks/SDD-CACHE.md, line 57The stored body is not raw HTML — `WebFetch` post-processes each response through a model using the caller's prompt, so what we cache is one agent's reading of
hooks/SDD-CACHE.md, line 65| `PreToolUse WebFetch` | If an entry exists, sends a `HEAD` request with `If-None-Match` / `If-Modified-Since`. On `304`, blocks the fetch and returns the cach
hooks/SDD-CACHE.md, line 66| `PostToolUse WebFetch` | Captures the response, issues a `HEAD` request to record the current `ETag` / `Last-Modified`, and stores `{url, prompt, etag, last_m
hooks/SDD-CACHE.md, line 76- Cache hit: `WebFetch` is blocked via exit code 2. Claude Code delivers the hook's stderr payload back to the agent as a tool error — this is the intended sign
hooks/SDD-CACHE.md, line 77- Cache miss or stale: `WebFetch` runs normally; the result is stored for next time.
hooks/SDD-CACHE.md, line 1216. Verify the second `WebFetch` is blocked and the cached content is returned (visible in the session transcript as a tool error with `[sdd-cache]` prefix).
hooks/SDD-CACHE.md, line 157- **Every cache write costs an extra HEAD.** Claude Code doesn't expose the response headers that `WebFetch` already received, so the post hook re-queries the o
hooks/sdd-cache-post.sh, line 82HEAD_OUT=$(curl -sI -L --max-time 5 "$URL" 2>/dev/null | tr -d '\r' || true)
hooks/sdd-cache-pre.sh, line 71STATUS=$(curl -sI -o /dev/null -w "%{http_code}" \
hooks/sdd-cache-pre.sh, line 78dbg "not 304, letting WebFetch proceed"
hooks/sdd-cache-pre.sh, line 85dbg "cache HIT, blocking WebFetch with ${#CONTENT} bytes of cached content"
hooks/sdd-cache-pre.sh, line 97printf 'content below as if WebFetch had just returned it.\n\n'
hooks/sdd-cache-pre.sh, line 99printf 'Original WebFetch prompt: "%s". If your angle differs, judge\n' "$ORIGINAL_PROMPT"

Downloads and installs other software

The author does not mention this. It runs automatically when the plugin is installed.

Found in 1 place.

hooks/session-start.sh, line 19echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "agent-skills: jq is required for the session-start hook but was not found o

Safer alternatives

Low-risk skills in the same category (writing) that look related. Check that one does what you need.

Install

Paste this into your terminal. It downloads exactly the version we scanned, not whatever is newest.

if [ -e ~/.agents/skills/'documentation-and-adrs' ] || [ -L ~/.agents/skills/'documentation-and-adrs' ]; then echo 'A skill folder named documentation-and-adrs already exists — not replacing it' >&2; false; else d=$(mktemp -d) && git clone --quiet --filter=blob:none --no-checkout 'https://github.com/addyosmani/agent-skills' "$d" && git -C "$d" checkout --quiet '39b723ceebf81474d0557c1fecd01eddab585563' -- 'skills/documentation-and-adrs' && mkdir -p ~/.agents/skills && cp -R "$d"/'skills/documentation-and-adrs' ~/.agents/skills/'documentation-and-adrs' && rm -rf "$d"; fi

Codex reads ~/.agents/skills directly. For Claude Code, Cursor, Copilot, Gemini CLI, Antigravity or OpenCode, also link it. For Claude Code: ln -s ~/.agents/skills/'documentation-and-adrs' ~/.claude/skills/'documentation-and-adrs' (other agents: ~/.cursor/skills, ~/.copilot/skills, ~/.gemini/skills, ~/.gemini/config/skills, ~/.config/opencode/skills). Or install through the finder skill, which does both.

Badge for your README

The badge for addyosmani/agent-skills shows the score of its lowest-scoring skill.

SkillTrust badge for addyosmani/agent-skills

[![SkillTrust](https://zalavijaysinh.github.io/skilltrust/badges/addyosmani/agent-skills.svg)](https://zalavijaysinh.github.io/skilltrust/repos/addyosmani/agent-skills/)

Score history

Date	Version	Score
2026-11-14	`39b723c`	75
2026-11-08	`301b02b`	80
2026-11-06	`301b02b`	80