agentsclimarketplace

Adr creation

Skill ceilidhboy/skills/skills/adr-creation

Agent skills for Laravel and PHP development. Installable via npx skills@latest add ceilidhboy/skills

Install
npx -y skills add ceilidhboy/skills --skill adr-creation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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

SKILL.md

4.5 KB, as published. Nobody here has run it

ADR Creation (Dual Format)

Core Principles

  1. Markdown (docs/adr/YYYY-MM-DD_kebab-title.md) is the source of truth. Concise, technical — for AI agents.

  2. HTML (docs/adr/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.

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

Write to docs/adr/YYYY-MM-DD_kebab-title.md. Use the template in template-markdown.md.

3. Create the HTML ADR

Write to docs/adr/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?"
  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.

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

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.