Agent skill

Adr Writer

Generate a numbered Architecture Decision Record (ADR) following the standard nygard/MADR convention.

MITAuto-check passedDevelopment

Install Adr Writer

skills CLI

$ npx skills add skrun-dev/skrun --skill adr-writer -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install skrun-dev/skrun adr-writer --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/skrun-dev/skrun.git skills-src && mkdir -p .claude/skills && cp -r skills-src/agents/adr-writer .claude/skills/adr-writer && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "adr-writer" agent skill from https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer into .claude/skills/adr-writer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "adr-writer", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add skrun-dev/skrun --skill adr-writer -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install skrun-dev/skrun adr-writer --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/skrun-dev/skrun.git skills-src && mkdir -p .agents/skills && cp -r skills-src/agents/adr-writer .agents/skills/adr-writer && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "adr-writer" agent skill from https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer into .agents/skills/adr-writer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "adr-writer", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add skrun-dev/skrun --skill adr-writer -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install skrun-dev/skrun adr-writer --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/skrun-dev/skrun.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/agents/adr-writer .cursor/skills/adr-writer && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "adr-writer" agent skill from https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer into .cursor/skills/adr-writer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "adr-writer", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/skrun-dev/skrun.git --path agents/adr-writer

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add skrun-dev/skrun --skill adr-writer -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install skrun-dev/skrun adr-writer --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/skrun-dev/skrun.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/agents/adr-writer .gemini/skills/adr-writer && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "adr-writer" agent skill from https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer into .gemini/skills/adr-writer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "adr-writer", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install skrun-dev/skrun adr-writer

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add skrun-dev/skrun --skill adr-writer -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/skrun-dev/skrun.git skills-src && mkdir -p .github/skills && cp -r skills-src/agents/adr-writer .github/skills/adr-writer && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "adr-writer" agent skill from https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer into .github/skills/adr-writer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "adr-writer", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add skrun-dev/skrun --skill adr-writer -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install skrun-dev/skrun adr-writer --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/skrun-dev/skrun.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/agents/adr-writer .opencode/skills/adr-writer && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "adr-writer" agent skill from https://github.com/skrun-dev/skrun/tree/main/agents/adr-writer into .opencode/skills/adr-writer/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "adr-writer", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: adr-writer
GitHub stars: 210
Token cost: ~861 tokens
SKILL.md length: 321 words
Files: 8 (incl. scripts)
Skills in repo: 14
Repo updated: Sep 22, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Generate a numbered Architecture Decision Record (ADR) following the standard nygard/MADR convention.

Works in 7 steps: Find existing ADRs — call list_adrs with… → Compute the next number —… → Generate a slug from the title —… → …
Asked to document an architectural decision
SKILL.md covers Workflow, Style and Conventions
Runs TypeScript scripts from its folder

What it does

Adr Writer is an agent skill from skrun-dev/skrun. 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.

Its SKILL.md is about 860 tokens, which your agent loads only when the skill is triggered. The skill folder holds 11 other files, including scripts (for example `README.md`, `agent.yaml` and `fixtures/existing-adrs/0001-stack-choice.md`).

It sits in Development, covering Architecture decision records. It works with Amazon DynamoDB and PostgreSQL. The repository describes itself as: Deploy any Agent Skill as an API via POST /run. The open-source multi-model alternative to Claude Managed Agents, Microsoft Foundry & Mistral/Koyeb — works with any LLM. The licence is MIT.

When your agent uses it

Asked to document an architectural decision
Capture a technical choice with its rationale

Example prompts

“/adr-writer”

Requirements

Node.js

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

Find existing ADRs — call list_adrs with the user's adrs_dir. The tool returns an array of { number, slug, title, status, filename }. If…
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" →…
Detect cross-link candidates — scan the existing ADR titles for keywords overlapping with the new decision (entities mentioned in context…
Compose the ADR Markdown — use this exact structure
Write the file — call write_artifact with
Return structured output

What it can do on your machine

Read from SKILL.md and the folder at commit b1d963b. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 2 files in scripts/ (TypeScript), which the agent can run.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Adr Writer loads about 861 tokens when it runs. Until then it costs about 83 tokens; SKILL.md has 321 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~83
When it runs · the whole SKILL.md, loaded when a task matches: ~861

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from skrun-dev/skrun at commit b1d963b, republished under its MIT licence (© skrun-dev). 321 words, ~861 tokens.

Download SKILL.mdSave it as .claude/skills/adr-writer/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.

name: adr-writer
description: 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.

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>

Show full SKILL.md (102 more words)Show less

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).

Files

SKILL.md and 7 other files (scripts) in agents/adr-writer of skrun-dev/skrun.

SKILL.md
README.md
agent.yaml
fixtures/empty-adrs/.gitkeep
fixtures/existing-adrs/0001-stack-choice.md
fixtures/existing-adrs/0002-monorepo.md
scripts/list_adrs.ts
scripts/write_artifact.ts

Open the folder on GitHubat commit b1d963b

Compare with similar skills

Adr Writer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Adr Writer compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Adr Writer this skillskrun-dev/skrun	210	—	~861	Automated safety check: Pass	MIT	15 days ago
Ogham Researchogham-mcp/ogham-mcp	115	—	~1.4k	Automated safety check: Pass	MIT	8 days ago
Event Store Designwshobson/agents	40k	9 repos	~828	Automated safety check: Pass	MIT	3 days ago
DB SculptorEliasOulkadi/shokunin	114	—	~3.1k	Automated safety check: Notes	MIT	3 days ago
Redshift Guideaws/agent-toolkit-for-aws	2.8k	—	~2.6k	Automated safety check: Pass	Apache-2.0	today
Stash Dynamodbcipherstash/stack	157	—	~5.7k	Automated safety check: Pass	MIT	today

Similar skills

Ogham Research
ogham-mcp/ogham-mcp
Structured memory capture for Ogham shared memory. An agent skill from ogham-mcp/ogham-mcp.
115 GitHub stars~1.4k tokensUpdated 8 days ago
Agent WorkflowsAuto-check passed
Event Store Design
wshobson/agents
Designs event stores for event-sourced systems: requirements, a comparison of EventStoreDB, PostgreSQL, Kafka, DynamoDB and Marten, and stream and versioning practices.
40k GitHub starsUsed in 9 repos~828 tokens
Backend & APIsAuto-check passed
DB Sculptor
EliasOulkadi/shokunin
Design database schemas with Prisma/Drizzle, PostgreSQL index strategy (B-tree, GIN, GiST, BRIN, Hash), query optimization (EXPLAIN ANALYZE), migration safety (expand/contract, zero-downtime), and…
114 GitHub stars~3.1k tokensUpdated 3 days ago
DatabasesAuto-check: notes
Redshift Guide
aws/agent-toolkit-for-aws
Official
Amazon Redshift is NOT PostgreSQL — corrects PostgreSQL-derived LLM mistakes; covers Redshift-specific SQL, DDL, COPY/UNLOAD, system views, metadata discovery, and operational patterns.
2.8k GitHub stars~2.6k tokensUpdated today
DatabasesAuto-check passed
Stash Dynamodb
cipherstash/stack
Integrate CipherStash encryption with Amazon DynamoDB using @cipherstash/stack/dynamodb and EQL v3 schemas.
157 GitHub stars~5.7k tokensUpdated today
DatabasesAuto-check passed
Database Designer
borghei/Claude-Skills
Database design with schema analysis, index optimization, and migration generation for PostgreSQL, MySQL, MongoDB, and DynamoDB.
881 GitHub stars~1.6k tokensUpdated today
DatabasesAuto-check passed

More from skrun-dev/skrun

All 14 skills in this repo

Changelog Generator
skrun-dev/skrun
Generate a polished CHANGELOG.md and release-notes.md from a local git repository (or a captured .git-log.txt dump).
210 GitHub stars~770 tokensUpdated 15 days ago
Auto-check passed
CSV To Executive Report
skrun-dev/skrun
Turn a CSV of operational data (sales, usage, signups, support tickets) into a multi-page styled PDF executive report with narrative + matplotlib charts.
210 GitHub stars~1.1k tokensUpdated 15 days ago
Auto-check passed
Knowledge Base From Vault
skrun-dev/skrun
Turn a folder of Markdown notes (Obsidian vault, Notion export, plain repo docs) into a navigable static HTML knowledge base bundled as a single .zip file.
210 GitHub stars~1.4k tokensUpdated 15 days ago
Auto-check passed
Meeting Transcript To Action Items
skrun-dev/skrun
Listen to a meeting recording and extract structured action items, decisions, and open questions.
210 GitHub stars~1.3k tokensUpdated 15 days ago
Auto-check passed
Semgrep Rule Creator
skrun-dev/skrun
Generate a complete Semgrep rule bundle (rule.yml + tests.md + README.md) from a CVE description and a bad-code example.
210 GitHub stars~1.3k tokensUpdated 15 days ago
Auto-check passed
Receipts To Expenses
skrun-dev/skrun
Read a batch of receipt images directly via vision, classify each into expense categories, optionally reconcile against a bank statement CSV, and produce a multi-sheet Excel workbook + a PDF summary.
210 GitHub stars~1.1k tokensUpdated 15 days ago
Auto-check passed

Works with

Questions about Adr Writer

What does Adr Writer do?

Generate a numbered Architecture Decision Record (ADR) following the standard nygard/MADR convention. Adr Writer is an agent skill from skrun-dev/skrun. Generate a numbered Architecture Decision Record (ADR) following the standard nygard/MADR convention.

When should I use Adr Writer?

Adr Writer fits situations like: asked to document an architectural decision; capture a technical choice with its rationale.

How do I install Adr Writer in Claude Code?

Run `npx skills add skrun-dev/skrun --skill adr-writer -a claude-code`. Or copy the skill folder (agents/adr-writer in skrun-dev/skrun) into .claude/skills/adr-writer in your project. Claude Code loads it when a task matches its description.

How do I install Adr Writer in Codex?

Run `npx skills add skrun-dev/skrun --skill adr-writer -a codex`. Or copy the skill folder (agents/adr-writer in skrun-dev/skrun) into .agents/skills/adr-writer in your project. Codex loads it when a task matches its description.

Can I use Adr Writer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add skrun-dev/skrun --skill adr-writer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/adr-writer, .gemini/skills/adr-writer, .github/skills/adr-writer and .opencode/skills/adr-writer in your project.

What does Adr Writer need to run?

Going by SKILL.md and its folder, Adr Writer needs TypeScript for the scripts in its folder. Our summary lists: Node.js.

Does Adr Writer access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Adr Writer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Adr Writer use?

Adr Writer is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Adr Writer use?

About 861 tokens (SKILL.md is roughly 3.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Adr Writer?

Skills that share tags, products or a category with Adr Writer: Ogham Research (ogham-mcp/ogham-mcp, 115 stars), Event Store Design (wshobson/agents, 40k stars), DB Sculptor (EliasOulkadi/shokunin, 114 stars) and Redshift Guide (aws/agent-toolkit-for-aws, 2.8k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Adr Writer?

skrun-dev (a GitHub organization) maintains it in skrun-dev/skrun, which has 210 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on September 22, 2026.

Source: skrun-dev/skrun on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Adr Writer

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

ADR Writer

Workflow

Style

Conventions

Files

Compare with similar skills

Similar skills

More from skrun-dev/skrun

Related

Questions about Adr Writer