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/.
In this repository27 other files it gives its agents.
- action-patternSkill
- boost-documentation-searchSkill
- bug-fixSkill
- component-composition-patternsSkill
- creating-pull-requestsSkill
- github-cli-workaroundsSkill
- html-outputSkill
- inertia-react-conventionsSkill
- javascript-typescript-conventionsSkill
- monthly-report-generatorSkill
- pest-testing-conventionsSkill
- pr-reviewSkill
- refactor-comments-that-are-code-smellsSkill
- routing-and-controllersSkill
- serena-conventionsSkill
- serena-mcp-selectionSkill
- settings-systemSkill
- single-task-responsibilitySkill
- spatie-data-transfer-objectsSkill
- tdd-laravelSkill
- troubleshooting-backendSkill
- troubleshooting-frontendSkill
- troubleshootingSkill
- unexpected-situationsSkill
- wayfinder-conventionsSkill
- write-a-skillSkill
- writing-skills-readme-firstSkill
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
- Distinctive: line 35
No ADR numbering — numbers clash across branches.
- Distinctive: line 42
Ask: What decision was made?
- Very specific: line 56
Write to <adr-dir>/html/YYYY-MM-DD_kebab-title.html.
- Distinctive: line 58
Follow the section order below.
- Very specific: line 63
YOU MUST check whether the
html-outputskill is installed: If it is, read its references/DESIGN_SYSTEM.md for the canonical CSS tokens, … - Very specific: line 70
If html-output is NOT installed, fall back to the bundled html-design-system.md — an abridged subset of the design system sufficient for …
- Distinctive: line 74
Follow the narrative guide in html-narrative-guide.md — audience, story examples, readability principles, before/after diagrams.
- Very specific: line 111
Use HEAD (not a branch name).
- Distinctive: line 118
Only explain non-obvious system behaviour.
≈ “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.
Files
ADR Creation (Dual Format)
Core Principles
- Markdown (
<adr-dir>/YYYY-MM-DD_kebab-title.md) is the source of truth. Concise, technical — for AI agents. The ADR directory isdocs/adr/by default, but mirror the project's existing ADR location if it differs (e.g.wip/docs/adr/). - 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 consulthtmlOutputDirsettings for ADRs. - 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.
- 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
- 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.
- Why it happened — Root cause in lay terms. Before/after flow diagrams.
- What we changed — The fix or improvement. Include any safety guards added.
- Consequences — Positive outcomes and trade-offs, in plain language.
4. Add cross-links
- Markdown frontmatter: add
html(relative) andhtml_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
- Edit the markdown first (source of truth).
- Regenerate the HTML — same narrative depth, consistent facts.
- Cross-link consistency — both files link to each other correctly.
- 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.htmlUse 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.mdwhen thehtml-outputskill is installed)
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
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.

