agentleFS
ceilidhboyceilidhboy/skills/skills/adr-creation/SKILL.md

adr-creation

Skill1 starsChanged 52 days agoMITView on GitHub

Creates and maintains dual-format ADRs — Markdown (source of truth for agents) and HTML (rich explainer for humans with diagrams). Keeps both formats in sync on updates. Use when user says "create an ADR", "document this decision", "write an ADR", "ADR for X", or when creating or updating a file in docs/adr/.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No ADR numbering — numbers clash across branches.

    line 35
  2. Distinctive:

    Ask: What decision was made?

    line 42
  3. Very specific:

    Write to <adr-dir>/html/YYYY-MM-DD_kebab-title.html.

    line 56
  4. Distinctive:

    Follow the section order below.

    line 58
  5. Very specific:

    YOU MUST check whether the html-output skill is installed: If it is, read its references/DESIGN_SYSTEM.md for the canonical CSS tokens, …

    line 63
  6. Very specific:

    If html-output is NOT installed, fall back to the bundled html-design-system.md — an abridged subset of the design system sufficient for …

    line 70
  7. Distinctive:

    Follow the narrative guide in html-narrative-guide.md — audience, story examples, readability principles, before/after diagrams.

    line 74
  8. Very specific:

    Use HEAD (not a branch name).

    line 111
  9. Distinctive:

    Only explain non-obvious system behaviour.

    line 118

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ADR Creation (Dual Format)

Core Principles

  1. Markdown (<adr-dir>/YYYY-MM-DD_kebab-title.md) is the source of truth. Concise, technical — for AI agents. The ADR directory is docs/adr/ by default, but mirror the project's existing ADR location if it differs (e.g. wip/docs/adr/).
  2. HTML (<adr-dir>/html/YYYY-MM-DD_kebab-title.html) is the human explainer. Rich, narrative, with diagrams. Lead with the problem — open with a concrete before-state so the reader feels the pain before learning the fix. The HTML destination is task-derived — do not consult htmlOutputDir settings for ADRs.
  3. HTML targets non-technical readers. The markdown is for developers and AI agents — concise, technical, assumes domain knowledge. The HTML is for sending to clients, stakeholders, project managers, and non-programming colleagues. Include explainers for concepts the markdown takes for granted. If you must use a technical term, define it inline. Use analogies. Assume the reader knows the business problem but not the code.
  4. Keep both in sync. Stale HTML is worse than no HTML.

File Naming

Both files share the same YYYY-MM-DD_kebab-case-title, differing only by extension. No ADR numbering — numbers clash across branches. Refer by date + title (e.g. "see Capture Referrer As Intended Login URL (2026-07-19)").

Process: Creating a New ADR

1. Gather context

Ask: What decision was made? What was the problem? What alternatives were considered? Why was this approach chosen?

Auto-detect project name and repo URL from README.md or git remote get-url origin.

2. Create the Markdown ADR

Determine the ADR directory first: use where the project's existing ADRs live (look for docs/adr/, wip/docs/adr/, etc.), defaulting to docs/adr/ when none exist yet. Write to <adr-dir>/YYYY-MM-DD_kebab-title.md. Use the template in template-markdown.md.

3. Create the HTML ADR

Write to <adr-dir>/html/YYYY-MM-DD_kebab-title.html. The HTML should:

  • Expand freely — diagrams, narrative, safety checks. Never contradict the markdown.
  • Follow the section order below.
  • Be self-contained (single HTML file, no external dependencies).

Design system and SVG conventions

YOU MUST check whether the html-output skill is installed. If it is, read its references/DESIGN_SYSTEM.md for the canonical CSS tokens, colour palette, typography, spacing, and CSS patterns — and its references/SVG_GUIDELINES.md for SVG diagram conventions (figure structure, common diagram types, flowcharts, timelines). These are the authoritative sources and take precedence over the bundled fallback.

If html-output is NOT installed, fall back to the bundled html-design-system.md — an abridged subset of the design system sufficient for standalone ADR creation.

Follow the narrative guide in html-narrative-guide.md — audience, story examples, readability principles, before/after diagrams.

HTML section order

  1. Problem in plain English — Concrete before-state example. A story that answers "why should I care?" Assume your reader is a project manager or client — they know the business problem but not the code or terminology. Define technical terms inline.
  2. Why it happened — Root cause in lay terms. Before/after flow diagrams.
  3. What we changed — The fix or improvement. Include any safety guards added.
  4. Consequences — Positive outcomes and trade-offs, in plain language.

4. Add cross-links

  • Markdown frontmatter: add html (relative) and html_github (absolute) fields.
  • HTML header: link back to the markdown on GitHub.

5. Present to the user

Show both files for review before committing. On WSL, link HTML files as file://wsl.localhost/Ubuntu-24.04/....

Process: Updating an Existing ADR

  1. Edit the markdown first (source of truth).
  2. Regenerate the HTML — same narrative depth, consistent facts.
  3. Cross-link consistency — both files link to each other correctly.
  4. Present for review.

Cross-Reference URLs

Markdown: https://github.com/{owner}/{repo}/blob/HEAD/docs/adr/YYYY-MM-DD_kebab-title.md
HTML:     https://github.com/{owner}/{repo}/blob/HEAD/docs/adr/html/YYYY-MM-DD_kebab-title.html

Use HEAD (not a branch name). Derive {owner} and {repo} from git remote get-url origin. Adjust the docs/adr/ path in the URLs if the project's ADR directory differs.

Markdown Notes

  • The markdown is for AI agents. Keep it concise and technical.
  • Context → Decision → Consequences is sufficient. No narrative treatment.
  • Only explain non-obvious system behaviour; skip what's self-evident.

Reference Files

  • template-markdown.md — Markdown template
  • template-html.html — HTML boilerplate
  • html-narrative-guide.md — Audience, story examples, readability principles, before/after diagrams
  • html-design-system.md — CSS tokens, visual style rules (fallback; superseded by html-output/references/DESIGN_SYSTEM.md when the html-output skill is installed)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.