documentation-and-adrs SKILL.md skillA

documentation-and-adrs from jpeetz/agent-skills is an agent skill: a SKILL.md folder an AI agent loads when a task calls for it.

mdr add jpeetz/agent-skills/documentation-and-adrs@v1.0.0

Pins v1.0.0 in mdr.lock. Pin the fingerprint instead.

Audit grade

A, 17 of 17 checks passed

Kind

SKILL.md skill

Repository

jpeetz/agent-skills

Path

skills/documentation-content/documentation-and-adrs/SKILL.md

Versions recorded

1

Latest version

v1.0.0, committed Sep 21, 2026

Size

12,310 bytes

Repository stars

16

License

none declared

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…

Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file 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.

---
…

Read the whole file at its exact version.

How to install

mdr add jpeetz/agent-skills/documentation-and-adrs@sha256:dfea4a4c21ff1292

[![mdr](https://markdownregistry.com/badge/art_nkdjcwm24i3ifflz.svg)](https://markdownregistry.com/a/art_nkdjcwm24i3ifflz)

Versions

The registry has recorded 1 version of this file, committed on Sep 21, 2026.

Audit of the latest version

Source

API

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 AI assistant 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.

Guides: the SKILL.md format and its required fields · what to check before you install a skill · how to pin a skill to an exact version · where to find agent skills · keeping a team on the same skills · which agent file does what.

More from jpeetz/agent-skills

Every file in jpeetz/agent-skills

Other files named documentation-and-adrs

Browse by kind, by grade A, or by owner.