documentation-and-adrs is agent-read markdown (skill) from jpeetz/agent-skills: Use 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.
Indexed from public GitHub and served as immutable, content-addressed versions. Install it pinned to an exact SHA-256 with the mdr CLI, and every file is verified against the hash recorded here before it reaches your agent. The deterministic audit below grades the latest version, and the same file always earns the same grade.
What the file says
# Documentation and ADRs
Records decisions and documents the *why* — context, constraints, trade-offs, and rejected alternatives that code alone cannot express.
---
## Overview
Code tells you *what* was built. Documentation tells you *why* it was built that way, *what alternatives were rejected*, and *what constraints governed the decision*. The most valuable documentation captures the reasoning, not the mechanics.
This skill covers four documentation layers, from most to least strategic:
| Layer | What | When | Effort |
|-------|------|------|--------|
| **🏛️ ADRs** | Architecture Decision Records — capture *why* a decision was made | Every significant architectural choice | 10-30 min |
| **📘 README** | Project entry point — what, why, how | New projects, major releases | 15-60 min |
| **🔌 API Docs** | Endpoint/schema documentation | Every public API change | Per-endpoint |
| **📝 Inline Docs** | Comments explaining *why*, not *what* | Continuously | Seconds |
**Core principle: document decisions, not mechanics.** A comment explaining *why* a rate limit uses a sliding window is valuable. A comment that says `// Increment counter by 1` above `counter += 1` is noise.
---
…
Pin to a label to follow the author's releases, or to a sha256 to freeze the exact bytes forever. Either way the resolved hash is written to mdr.lock, and mdr install reproduces it on any machine.
GET https://markdownregistry.com/api/v1/artifacts/art_nkdjcwm24i3ifflz
GET https://markdownregistry.com/api/v1/resolve?ref=jpeetz/agent-skills/documentation-and-adrs
GET https://markdownregistry.com/api/v1/blob/dfea4a4c21ff1292483e68b1131c6095edcdfdc0297c22d7264f16b1c9f5aab8
Your agent does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
jpeetz/agent-skills · skills/api-backend/har-api-reverse-engineering/SKILL.md · Use this skill when an agent needs to call a website's hidden or undocumented API: capture real browser requests into a…
jpeetz/agent-skills · skills/api-backend/image-to-image-character-generation/SKILL.md · Use this skill when an agent needs to generate consistent character images via kie.ai grok-imagine image-to-image from…
jpeetz/agent-skills · skills/api-backend/social-har-api-connectivity/SKILL.md · Use this skill when an agent needs to connect to a social platform's API by prompting the user to pick a platform…
jpeetz/agent-skills · skills/business-strategy/app-discovery-scrutiny/SKILL.md · Use this skill when the user wants to evaluate a mobile app idea for commercial viability — whether it's a clone…
jpeetz/agent-skills · skills/business-strategy/enterprise-consulting-methods/SKILL.md · Use when you need McKinsey/BCG-grade strategy work — problem decomposition, hypothesis testing, storyline building…
jpeetz/agent-skills · skills/code-quality/code-simplification/SKILL.md · Use this skill when refactoring code for clarity without changing behavior. Use when code works but is harder to read…
jpeetz/agent-skills · skills/code-quality/debugging-and-error-recovery/SKILL.md · Use this skill when tests fail, builds break, runtime behavior doesn't match expectations, a bug report arrives, or…
addyosmani/agent-skills · skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning…
shashankswe2020-ux/whoop-mcp · .github/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-cursor/.cursor/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-claude/.claude/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when you need to document
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-forgecat/platforms/codex/.agents/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-forgecat/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-codex/.agents/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning…
nota-america/forgecat-agent-profiles · profiles/addyosmani/agent-skills/for-forgecat/platforms/cursor/.cursor/skills/documentation-and-adrs/SKILL.md · Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning…
