More screenshots

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    Documentation & ADRs: Write Down the Why

    1

    Capture the why behind technical decisions — architecture decision records for expensive-to-reverse choices, plus living docs (READMEs, API docs, onboarding guides) that keep a codebase legible.

    $5

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Documentation & ADRs: Write Down the Why

    Documentation & ADRs: Write Down the Why

    Example session with this skill installed

    We are choosing between JWTs and session tokens for our multi-service API, and nobody will remember why in six months. Write the ADR and tell me what living docs need to exist alongside it.

    • Read your context and instructions
    • Compiled the documentation & adrs

    ADR — JWTs vs session tokens (multi-service API)

    Context: three services, one web client, one mobile client. Services must validate requests without calling a central auth service every time, and token revocation must work within minutes when an account is compromised.

    Alternatives with why each lost: (1) Stateful session tokens — revocation is simple, but every service calls the auth service per request, which is the bottleneck this architecture exists to avoid. (2) JWTs with long expiry — simplest, but revocation is effectively impossible, which fails the compromise requirement outright.

    Decision: JWTs, 15-minute access tokens, rotating refresh tokens, denylist checked at refresh time.

    Consequences — positive: services validate locally, no auth-service bottleneck. Negative, stated honestly: refresh rotation adds complexity, and the denylist is a new component to operate. Reversal trigger written in the record: if the denylist becomes a bottleneck, revisit stateful sessions.

    Living docs alongside it: the README's API section records the token lifetimes and refresh flow; the API docs state the retry semantics for an expired access token; the onboarding guide includes the three gotchas (refresh rotation, denylist checks, clock skew). Status: Accepted, dated, filed as ADR-004 in the repo's existing sequence. In six months, "why not long-lived JWTs?" is answered by the alternatives section — not re-litigated.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    Code shows what was built. Documentation explains why it was built that way and what else was considered — and six months from now, the why is the part that is missing. This skill covers the two highest-value forms: ADRs for decisions that would be expensive to reverse (frameworks, data models, auth strategies, APIs, infrastructure), and living documentation for the codebase (README, API and behavior docs, onboarding guides).

    An ADR is short and permanent: context, decision, alternatives with why each lost, honest consequences including the costs, current status, and a reversal trigger. The existing repo convention is matched first — sequence continued, not restarted — and superseded records link forward, never rewritten. A worked example records a JWT-vs-sessions auth decision with the revocation requirement that decided it, so the question never gets re-litigated. Living docs are held to a test: an onboarding guide must get a competent new person to first productive commit. A rubric gates legibility: below 6 out of 8, the why is missing somewhere.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Product Management.

    • It records decisions; it does not make them. The alternatives and consequences must come from the people deciding — the skill structures them, it does not invent them.
    • ADRs are reserved for expensive-to-reverse decisions. A decision that took ten minutes and costs nothing to reverse gets a code comment, and the skill will say so.
    • Living docs decay: every doc needs an owner and a change-based review trigger, or it rots like any other doc.
    • A stale page is deleted rather than left standing — the skill treats a confident lie as worse than an honest gap.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 3 days ago

    Permissions

    No special permissions declared or detected

    Listed3 days ago

    What's inside

    Frequently Asked Questions

    An ADR is a short, permanent record of one decision: context, choice, alternatives with why each lost, and honest consequences. A design doc proposes and explores. The ADR is what remains after the decision is made — the record future readers consult instead of re-litigating.

    No. Reserve ADRs for decisions that would be expensive to reverse — frameworks, data models, auth strategies, APIs, infrastructure. A ten-minute decision that costs nothing to reverse gets a code comment. An ADR for everything is a filing cabinet nobody opens.

    The old record is marked Superseded and linked forward to the new one — never rewritten. A superseded ADR is still true about the past, and rewriting it destroys the history of why the old choice was reasonable at the time.

    New in Product Management