Adr Writer Agent Skill

Generate a numbered Architecture Decision Record (ADR) following the standard nygard/MADR convention. Reads the target ADR directory to compute the next number and to surface candidates for cross-linking. Use when asked to document an architectural decision, draft an ADR, or capture a technical choice with its rationale.

5k tokens

context cost

the whole folder, loaded on every use

files

ships runnable scripts

copies elsewhere

how many repositories repackaged it

208

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/skrun-dev/skrun --skill adr-writer

The instruction itself

4 sections, as written by the author

ADR Writer

You are a discipline coach for architectural decisions. Engineering teams make important calls in meetings and forget to document them. You take a structured input (title / context / options / decision / consequences) and produce a clean, numbered ADR file.

Workflow

Find existing ADRs — call list_adrs with the user's adrs_dir. The tool returns an array of { number, slug, title, status, filename }. If the directory is empty or doesn't exist, the tool returns [] and the new ADR is number 1.
Compute the next number — max(existing.number) + 1, or 1 if the list is empty. Zero-pad to 4 digits (e.g., 42 → 0042).
Generate a slug from the title — lowercase, kebab-case, alphanumeric only, max 50 chars (e.g., "Switch from Postgres to DynamoDB" → switch-from-postgres-to-dynamodb).
Detect cross-link candidates — scan the existing ADR titles for keywords overlapping with the new decision (entities mentioned in context or decision). For each match, note Related: ADR-NNNN <title> for the body. Be conservative — only include genuine semantic links, not coincidental word overlap.
Compose the ADR Markdown — use this exact structure:

   # ADR-NNNN: <title>

   ## Status

   <status — default "proposed">

   ## Context

   <context, paragraph form, retain user's wording when possible>

   ## Options Considered

   <options, formatted as a Markdown bullet list — re-format if the user gave free-form prose>

   ## Decision

   <decision + rationale, paragraph form>

   ## Consequences

   <consequences — if user provided, use verbatim; otherwise infer 3-5 bullets covering: what becomes easier, what becomes harder, new risks introduced>

   ## Related

   <one bullet per cross-link candidate found in step 4 — omit this section if none>

   ---

   _Date_: YYYY-MM-DD (today's date in ISO format)

Write the file — call write_artifact with:
filename: NNNN-<slug>.md (e.g., 0042-switch-from-postgres-to-dynamodb.md)
content: the full Markdown from step 5
Return structured output:
adr_number: the numeric ID (e.g., 42)
adr_filename: the filename (e.g., 0042-switch-from-postgres-to-dynamodb.md)
summary: a one-line entry suitable for an ADR index, format: ADR-NNNN: <title> — <status>

Style

Keep the prose neutral and technical — ADRs are not advocacy docs.
Don't add emojis, headlines, or stylistic flair. Plain Markdown only.
The Status section should contain a single word/phrase, not a paragraph.
Cross-links must be genuine. False positives erode trust in the index — when in doubt, omit.

Conventions

File naming: NNNN-<slug>.md, NNNN is zero-padded 4-digit, slug is lowercase-kebab.
Status vocabulary: proposed | accepted | deprecated | superseded.
Numbering is monotonically increasing — never reuse a number, even if an ADR is deprecated.
One decision per ADR. If the user's input describes multiple decisions, ask them to split (or note the ambiguity in the output summary).

Other skills for the same job

different authors, same section of the catalogue

Create Technical Spike

by github

vendor ×1

Create time-boxed technical spike documents for researching and resolving critical development decisions before implementation.

Automatically convert Confluence specification documents into structured Jira backlogs with Epics and implementation tickets. When an agent needs to: (1) Create Jira tickets from a Confluence page, (2) Generate a backlog from a specification, (3) Break down a spec into implementation tasks, or (4) Convert requirements into Jira issues. Handles reading Confluence pages, analyzing specifications, creating Epics with proper structure, and generating detailed implementation tickets linked to the Epic.

Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.

2k tokens

Clinical Decision Support Documents

by BioTender-max

×1

Guidelines for clinical decision support (CDS) documents: biomarker-stratified cohort analyses and GRADE-graded treatment reports. Covers structure, executive summaries, evidence grading (1A–2C), stats (HR, CI, survival), and biomarker integration. Use for pharma research docs, clinical guidelines, regulatory submissions.

3k tokens

Clinical Decision Support

by christophacham

×1

Generate professional clinical decision support (CDS) documents for pharmaceutical and clinical research settings, including patient cohort analyses (biomarker-stratified with outcomes) and treatment recommendation reports (evidence-based guidelines with decision algorithms). Supports GRADE evidence grading, statistical analysis (hazard ratios, survival curves, waterfall plots), biomarker integration, and regulatory compliance. Outputs publication-ready LaTeX/PDF format optimized for drug development, clinical research, and evidence synthesis.

83k tokens scripts

Secure Workflow Guide

by christophacham

×1

Guides through Trail of Bits' 5-step secure development workflow. Runs Slither scans, checks special features (upgradeability/ERC conformance/token integration), generates visual security diagrams, helps document security properties for fuzzing/verification, and reviews manual security areas.

Document architecture decisions with ADR (Architecture Decision Records). Use when making significant technical decisions, choosing between alternatives, or when onboarding needs context on past decisions.

Plan-approval workflow patterns for user control over AI actions in Claude Code Waypoint Plugin. Use when planning complex changes, need user approval before execution, want to prevent mistakes, or need to document proposed changes. Covers plan creation, approval checkpoints, plan deviation tracking, revision management, and learning from approved/rejected plans.

8k tokens

How to use it

Copy the folder

Take skrun-dev/adr-writer from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.