New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Make Decision Doc

by remix-run in remix-run/remix

Add a numbered decision document under decisions/ to capture a non-obvious architectural choice.

MITAuto-check passedDevelopment

Install Make Decision Doc

skills CLI
$ npx skills add remix-run/remix --skill make-decision-doc -a claude-code

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

GitHub CLI
$ gh skill install remix-run/remix make-decision-doc --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/remix-run/remix.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/make-decision-doc .claude/skills/make-decision-doc && 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/

Facts

Skill name
make-decision-doc
GitHub stars
33k
Token cost
~934 tokens
SKILL.md length
509 words
Files
1
Skills in repo
19
Repo updated
First seen
Licence
MIT

At a glance

Add a numbered decision document under decisions/ to capture a non-obvious architectural choice.

  • Works in 5 steps: Read the existing files under decisions/… → Pick the next number by counting… → Pick a slug that names the thing being… → …
  • The user asks for a decision doc
  • SKILL.md covers Overview, When to write one, Workflow and Structure, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Make Decision Doc is an agent skill from remix-run/remix. Add a numbered decision document under decisions/ to capture a non-obvious architectural choice. Use when the user asks for a decision doc, ADR, design rationale, or wants to record why we picked one approach over alternatives.

Its SKILL.md is about 930 tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Architecture decision records. The repository describes itself as: The fully-stacked web framework. The licence is MIT.

When your agent uses it

  • The user asks for a decision doc
  • Design rationale
  • Wants to record why we picked one approach over alternatives

Example prompts

  • “/make-decision-doc”

Workflow steps

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

  1. Read the existing files under decisions/ (e.g. decisions/001-*.md) to match tone and structure.
  2. Pick the next number by counting existing files (ls decisions/ | wc -l) and add 1. Filename is NNN-kebab-slug.md with a 3-digit…
  3. Pick a slug that names the thing being decided, not the verb (single-matcher, not pick-single-matcher).
  4. Draft the doc following the structure below. Keep it grounded — no hypothetical alternatives, no aspirational language.
  5. If the decision relates to other decisions, link them as footnotes ([NNN]: ./NNN-other.md).

What it can do on your machine

Read from SKILL.md and the folder at commit ef2c594. 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

    No scripts in the folder and no shell commands in SKILL.md.

    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

Make Decision Doc loads about 934 tokens when it runs. Until then it costs about 62 tokens; SKILL.md has 509 words of instructions outside code blocks.

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

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); files beside SKILL.md are not scanned.

SKILL.md

The full file from remix-run/remix at commit ef2c594, republished under its MIT licence (© remix-run). 509 words, ~934 tokens.

Download SKILL.mdSave it as .claude/skills/make-decision-doc/SKILL.md (or your agent's skills folder).
name
make-decision-doc
description
Add a numbered decision document under `decisions/` to capture a non-obvious architectural choice. Use when the user asks for a decision doc, ADR, design rationale, or wants to record why we picked one approach over alternatives.

Make Decision Doc

Overview

Decision docs live at the repo root in decisions/NNN-kebab-name.md. They explain why a choice was made — the tradeoff, the alternatives that were actually considered, and (when useful) the conditions under which we'd revisit. They are not feature specs, not how-to guides, and not changelog entries.

When to write one

  • A non-obvious architectural choice was made and a future contributor would reasonably ask "why didn't we do X instead?".
  • A choice has tradeoffs that are easy to second-guess without context (perf vs. simplicity, lock-in vs. flexibility, ergonomics vs. correctness).
  • We diverged from a common default or industry-standard alternative and the reasoning matters.

Skip a decision doc when the choice is obvious, the alternatives weren't seriously considered, or the rationale already lives in code comments / change file / PR description.

Workflow

  1. Read the existing files under decisions/ (e.g. decisions/001-*.md) to match tone and structure.
  2. Pick the next number by counting existing files (ls decisions/ | wc -l) and add 1. Filename is NNN-kebab-slug.md with a 3-digit zero-padded prefix.
  3. Pick a slug that names the thing being decided, not the verb (single-matcher, not pick-single-matcher).
  4. Draft the doc following the structure below. Keep it grounded — no hypothetical alternatives, no aspirational language.
  5. If the decision relates to other decisions, link them as footnotes ([NNN]: ./NNN-other.md).

Structure

No rigid template — match the style of existing docs. The shape that tends to work:

  • H1 title: a short statement or question that a reader scanning the folder can grok at a glance.
  • Opening framing (1–3 short paragraphs): what the choice was, why it came up, and what the realistic alternatives were. Lead with concrete context, not abstractions.
  • Tradeoff sections: typically "What gets simpler / harder", "Why we chose X", or named sections per dimension (perf, complexity, ergonomics). Use H2s.
  • When to revisit (optional but encouraged): a numbered list of conditions that would flip the decision. Keeps the doc honest and gives future contributors a clear off-ramp.
  • Footnote links to related decisions or external sources cited in the body.
Show full SKILL.md (173 more words)Show less

Content rules

  • Ground every claim. Cite benchmarks, blog posts, code references, or measured behavior. If the decision is "feels nicer", say so explicitly rather than dressing it up.
  • Only list alternatives that were actually deliberated. Inventing options to knock down weakens the doc.
  • Past tense for the decision ("we chose X"), present tense for ongoing implications ("X means we don't need Y").
  • Keep prose tight. These docs reward density — readers come looking for a specific answer.
  • Code references use the repo's standard path/to/file.ts style; line ranges with backtick fences when illustrating a specific snippet.
  • No marketing tone, no hedging filler ("it's worth noting that…", "in many cases…"). State the call.

Checklist

  • Did you read at least one existing decision doc to match style?
  • Is the filename NNN-kebab-slug.md with the next available number?
  • Does the H1 communicate the decision in one line?
  • Are the alternatives ones that were actually considered?
  • Did you cite concrete evidence (benchmarks, sources, code) instead of assertions?
  • Is there a "when to revisit" section if the decision could plausibly flip?

© remix-run, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/make-decision-doc of remix-run/remix.

Open the folder on GitHubat commit ef2c594

Compare with similar skills

Make Decision Doc 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.

Make Decision Doc compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Make Decision Doc this skillremix-run/remix33k—~934Automated safety check: PassMIT
PR Design DocOpenHands/OpenHands90k—~2.4kAutomated safety check: PassMIT
Cto AdvisorIbrahim-3d/orchestrator-supaconductor3804 repos~2.4kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0
Domain Modelingbrim-borium/spotify_sdk1665 repos~806Automated safety check: PassApache-2.0
Design Doc MermaidSpillwaveSolutions/design-doc-mermaid1751 repos~5.6kAutomated safety check: PassNone

Similar skills

  • PR Design Doc

    OpenHands/OpenHands

    For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link a visibility-appropriate preview in the PR description, so maintainers grasp the…

    90k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed

  • Cto Advisor

    Ibrahim-3d/orchestrator-supaconductor

    Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.

    380 GitHub starsUsed in 4 repos~2.4k tokens
    DevelopmentAuto-check passed

  • Improve Codebase Architecture

    ywwynm/EverythingDone

    Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed

  • Domain Modeling

    brim-borium/spotify_sdk

    Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.

    166 GitHub starsUsed in 5 repos~806 tokens
    DevelopmentAuto-check passed

  • Design Doc Mermaid

    SpillwaveSolutions/design-doc-mermaid

    Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.

    175 GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed

  • Learning Opportunities

    DrCatHicks/learning-opportunities

    Facilitates deliberate skill development during AI-assisted coding.

    2.5k GitHub stars~2.5k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

More from remix-run/remix

All 19 skills in this repo

  • Supersede PR

    remix-run/remix

    Safely replace one GitHub pull request with another. An agent skill from remix-run/remix.

    33k GitHub stars~456 tokensUpdated today
    Auto-check passed

  • Add Package

    remix-run/remix

    Create or align a package in the Remix monorepo to match existing package conventions.

    33k GitHub stars~2k tokensUpdated today
    Auto-check passed

  • Author UI Primitives

    remix-run/remix

    Build idiomatic headless primitives in packages/ui for Remix.

    33k GitHub stars~2.5k tokensUpdated today
    Auto-check passed

  • Fix Issue

    remix-run/remix

    Fix a reported issue in Remix from a GitHub issue. An agent skill from remix-run/remix.

    33k GitHub stars~1.8k tokensUpdated today
    Auto-check passed

  • Make Demo

    remix-run/remix

    Create or revise demos in the Remix repository. An agent skill from remix-run/remix.

    33k GitHub stars~2.4k tokensUpdated today
    Auto-check passed

  • Make PR

    remix-run/remix

    Create GitHub pull requests with clear, reviewer-friendly descriptions.

    33k GitHub stars~847 tokensUpdated today
    Auto-check passed

Categories

Questions about Make Decision Doc

What does Make Decision Doc do?

Add a numbered decision document under decisions/ to capture a non-obvious architectural choice. Make Decision Doc is an agent skill from remix-run/remix. Add a numbered decision document under decisions/ to capture a non-obvious architectural choice.

When should I use Make Decision Doc?

Make Decision Doc fits situations like: the user asks for a decision doc; design rationale; wants to record why we picked one approach over alternatives.

How do I install Make Decision Doc in Claude Code?

Run `npx skills add remix-run/remix --skill make-decision-doc -a claude-code`. Or copy the skill folder (.agents/skills/make-decision-doc in remix-run/remix) into .claude/skills/make-decision-doc in your project. Claude Code loads it when a task matches its description.

How do I install Make Decision Doc in Codex?

Run `npx skills add remix-run/remix --skill make-decision-doc -a codex`. Or copy the skill folder (.agents/skills/make-decision-doc in remix-run/remix) into .agents/skills/make-decision-doc in your project. Codex loads it when a task matches its description.

Can I use Make Decision Doc 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 remix-run/remix --skill make-decision-doc -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/make-decision-doc, .gemini/skills/make-decision-doc, .github/skills/make-decision-doc and .opencode/skills/make-decision-doc in your project.

What does Make Decision Doc need to run?

SKILL.md names no scripts, command-line tools or credentials: Make Decision Doc is instructions for the agent only.

Does Make Decision Doc 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 Make Decision Doc 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. Review the folder before installing.

What licence does Make Decision Doc use?

Make Decision Doc 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 Make Decision Doc use?

About 934 tokens (SKILL.md is roughly 3.7k 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 Make Decision Doc?

Skills that share tags, products or a category with Make Decision Doc: PR Design Doc (OpenHands/OpenHands, 90k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 380 stars), Improve Codebase Architecture (ywwynm/EverythingDone, 144 stars) and Domain Modeling (brim-borium/spotify_sdk, 166 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Make Decision Doc?

remix-run (a GitHub organization) maintains it in remix-run/remix, which has 33,397 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 8, 2026.

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