agentleFS
merllinsbeardmerllinsbeard/merlin-skills/skills/merlin-skills-routing/SKILL.md

merlin-skills-routing

Skill1 starsChanged 6 months agoMITView on GitHub

Mandatory meta-routing skill for Merlin Skills. Use before any non-trivial /goal or implementation task to choose the smallest skill-first chain, bind work to Spec Kit artifacts, and prevent loading unrelated skills.

The file

Show its rules and text

We split this skill into the rules it gives an agent

32 rules. About 0 are common, 14 are distinctive, and 18 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 18

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill before non-trivial implementation work, and always before creating or executing a Codex /goal.

    line 8
  2. Very specific:

    If the idea is ambiguous or product-shaped, route to brainstorming, but keep Spec Kit as the destination: the design output should be …

    line 26
  3. Distinctive:

    If there is a conflict, the user's newest request and current checkout win over old docs.

    line 36
  4. Very specific:

    No unresolved [NEEDS CLARIFICATION] markers in spec.md.

    line 119
  5. Very specific:

    If these are not true, route to the missing step instead of launching /goal.

    line 124
  6. Very specific:

    Use before non-trivial implementation work and always before /goal.

    line 130
  7. Distinctive:

    Use when installing, updating, or vendoring this pack into Codex, Claude, or a project-local skill root.

    line 134
  8. Very specific:

    Use when installing or running the official specify CLI, initializing .specify/, or managing Spec Kit integrations/extensions/presets.

    line 138
  9. Distinctive:

    Use when the product direction, UX, or feature shape is still ambiguous.

    line 142
  10. Very specific:

    Use when existing conversation context should become product requirements or an issue.

    line 146
  11. Distinctive:

    Use when the code area is unfamiliar and the agent needs a map before edits.

    line 150
  12. Very specific:

    Use to create or refresh .specify/memory/constitution.md.

    line 154
  13. Very specific:

    Use to create or update specs/<feature>/spec.md from natural-language requirements.

    line 158
  14. Very specific:

    Use before planning when requirements are underspecified.

    line 162
  15. Very specific:

    Use to create the technical plan and optional design artifacts.

    line 166
  16. Distinctive:

    Use to pressure-test a plan against project docs, domain language, and ADRs.

    line 170
  17. Very specific:

    Use to convert spec and plan into executable work.

    line 174
  18. Distinctive:

    Use to generate requirement-quality checklists.

    line 178
  19. Very specific:

    Use after tasks to check consistency across spec, plan, and tasks.

    line 182
  20. Very specific:

    Use only when the user explicitly wants GitHub issues from tasks.md.

    line 186
  21. Very specific:

    Use to generate GOAL.md from Spec Kit artifacts.

    line 190
  22. Very specific:

    Use only when the user explicitly wants upstream Spec Kit native implementation.

    line 194
  23. Distinctive:

    Use for hard bugs, unknown failures, flaky tests, or performance regressions.

    line 202
  24. Distinctive:

    Use after implementation or before ship.

    line 206
  25. Distinctive:

    Use for token-efficient browser interaction, screenshots, and Playwright test workflow.

    line 210
  26. Distinctive:

    Use when browser proof needs custom scripting or repeatable automation.

    line 214
  27. Distinctive:

    Use when implementation and QA evidence are ready and the user asks to package, commit, push, PR, tag, release, merge, or deploy.

    line 218
  28. Distinctive:

    Prefer Spec Kit artifacts over chat memory for feature truth.

    line 223
  29. Distinctive:

    Prefer tests, browser proof, and QA reports over confidence.

    line 224
  30. Distinctive:

    Keep generated proof next to the feature or in the repo's existing evidence location.

    line 225
  31. Very specific:

    Keep gstack limited to gstack-qa and gstack-ship unless the source-selection policy is intentionally changed.

    line 226
  32. Very specific:

    Keep upstream-generated speckit-* skills close to GitHub Spec Kit.

    line 227

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Merlin Skills Routing

Use this skill before non-trivial implementation work, and always before creating or executing a Codex /goal.

Your job is to identify the current development phase and load only the next useful skill. Keep routing short. Do not load every skill and do not turn routing into a separate planning ceremony when the next step is obvious.

Spec Kit Consultation Pass

For every non-trivial request, do a short Spec Kit consultation before choosing the next skill.

Inspect whether the current work already has:

  • .specify/ project infrastructure;
  • an active specs/<feature>/ directory;
  • current spec.md, plan.md, and tasks.md;
  • an existing GOAL.md;
  • completed task checkboxes, QA reports, browser proof, PRs, or release artifacts.

Then decide whether the next step should create, refresh, or reuse Spec Kit artifacts. This pass is mandatory even when the next visible skill is brainstorming, to-prd, tdd, diagnose, gstack-qa, or gstack-ship.

If the idea is ambiguous or product-shaped, route to brainstorming, but keep Spec Kit as the destination: the design output should be concrete enough to become spec.md, plan.md, and tasks.md.

Inputs To Inspect

  1. The user's newest request.
  2. The current repository state and instruction files.
  3. Existing Spec Kit infrastructure in .specify/.
  4. Existing Spec Kit artifacts in specs/<feature>/.
  5. Existing GOAL.md, test output, QA reports, browser screenshots, PRs, or release artifacts.

If there is a conflict, the user's newest request and current checkout win over old docs.

Required Decision

Return a short routing decision before doing major work:

Phase: <current phase>
Spec Kit consultation: create | refresh | reuse | not applicable, with one short reason
Next skill: <one skill or /goal>
Feature dir: <path or none>
Why: <one sentence>
Required proof: <what proves this phase is done>

Then continue with the next skill or task. Do not stop after routing unless a required artifact is missing or the user asked only for a plan.

Default Route

For autonomous web coding:

spec-kit consultation
  -> brainstorming or to-prd when useful
  -> speckit-cli/setup
  -> speckit-constitution
  -> speckit-specify
  -> speckit-clarify
  -> speckit-plan
  -> speckit-tasks
  -> speckit-analyze/checklist
  -> create-goal
  -> /goal
  -> tdd/diagnose
  -> gstack-qa
  -> playwright-cli/playwright-skill
  -> gstack-ship

In this default route, tdd is an execution mode after speckit-tasks has produced tasks.md, create-goal has produced GOAL.md, and /goal is working an implementation slice. Do not use tdd to replace speckit-tasks or to bulk-write every test before implementation.

Compact form:

spec-kit consultation -> brainstorming or to-prd -> speckit-cli/setup -> speckit-constitution -> speckit-specify -> speckit-clarify -> speckit-plan -> speckit-tasks -> speckit-analyze/checklist -> create-goal -> /goal -> tdd/diagnose -> gstack-qa -> playwright-cli/playwright-skill -> gstack-ship

Most work skips some phases. If .specify/, spec.md, plan.md, tasks.md, or GOAL.md already exists and is current, route to the first missing or stale phase. The durable progress layer remains Spec Kit-native: tasks.md checkboxes track task completion, GOAL.md defines the resume protocol, and QA/browser proof lives next to the feature or in the repo's existing evidence location.

Phase Router

PhaseUser situationUse this skillRequiresProducesStop or skip condition
Pack installInstall, update, refresh, or project-local setup for Merlin Skillsinstall-merlin-skillsTarget root or reasonable defaultInstalled pack and optional instruction blockSkip for normal feature work
Spec Kit setupNeed .specify/, specify CLI, Codex $speckit-* skills, integrations, extensions, or presetsspeckit-cliRepo target and permission to initialize.specify/, .agents/skills/speckit-*, managed contextSkip when .specify/ and needed skills already exist
Product shapingAmbiguous product idea, early UX concept, or "is this worth building?"brainstormingUser intent and repo contextApproved design directionSkip when the requested behavior is already concrete
PRD synthesisExisting conversation needs to become a PRD or issueto-prdEnough conversation/repo contextPRD-style requirementsSkip when Spec Kit spec.md already covers the requirement
Context mapUnfamiliar code area needs a broader mapzoom-outCode area or topicModule/context mapSkip when the implementer already knows the area
ConstitutionProject principles are missing or stalespeckit-constitution.specify/ initialized.specify/memory/constitution.mdSkip when current principles are good enough
Feature specNeed to create or update requirements from natural languagespeckit-specify.specify/ initialized and feature descriptionspecs/<feature>/spec.mdSkip when spec.md is current
Spec clarificationSpec has ambiguity, [NEEDS CLARIFICATION], or high-risk assumptionsspeckit-clarifyActive spec.mdClarifications written into the specSkip only for explicit spikes or trivial changes
Technical planNeed implementation approach, research, data model, contracts, or quickstartspeckit-planActive clarified spec.mdplan.md plus optional design artifactsSkip when plan.md is current
Plan pressureNeed to challenge terminology, ADRs, docs, or domain assumptionsgrill-with-docsDraft plan and project docsSharpened decisions/docsSkip when the plan is routine and grounded
TasksNeed executable implementation checklistspeckit-tasksspec.md and plan.mdtasks.mdSkip when tasks.md is current and agent-runnable
Requirements checksNeed requirement-quality checklistspeckit-checklistActive feature artifactsChecklist under feature artifactsOptional; skip for small low-risk changes
Artifact auditNeed cross-artifact consistency before goal or implementationspeckit-analyzespec.md, plan.md, tasks.mdNon-destructive consistency reportSkip when artifacts are tiny and obviously aligned
GitHub issuesUser explicitly wants tasks converted to GitHub issuesspeckit-taskstoissuesGitHub auth/MCP and tasks.mdGitHub issuesNever default; it has external side effects
Goal contractNeed durable Codex /goal contractcreate-goalClear spec.md, plan.md, tasks.mdspecs/<feature>/GOAL.mdRequired before long /goal work
Native upstream implementationUser explicitly wants Spec Kit native implementation instead of Merlin /goalspeckit-implementComplete Spec Kit artifacts and approval to executeImplementation driven by upstream tasksNon-default; prefer create-goal -> /goal
Autonomous executionGoal exists and user wants Codex to work until done/goalCurrent GOAL.mdImplemented tasks and verificationDo not launch from loose chat summary
Test-first buildBuilding a feature or normal bug fix with teststddSpec Kit work: GOAL.md plus tasks.md; small non-Spec-Kit fix: clear behavior targetTested implementationSkip for read-only review/analysis
Hard diagnosisBroken behavior, flaky test, unknown failure, performance regressiondiagnoseRepro target or failing signalRoot cause, fix, regression testRoute back to tdd for implementation if needed
QA gateImplementation exists and needs proof or fixes before shipgstack-qaActive spec/goal and runnable app/checksQA report, tests, browser evidence, in-scope fixesRequired before ship for web work
Browser proofNeed live browser interaction, screenshots, or Playwright testsplaywright-cliURL/dev server or browser targetBrowser proof and optional generated testsUse before ship when UI/user flow changed
Custom browser automationBrowser workflow needs loops, login setup, screenshots, or reusable logicplaywright-skillURL/dev server and scenarioCustom Playwright script/evidenceUse only when CLI steps are not enough
ShipReady to commit, push, PR, tag, release, merge, or deploygstack-shipQA evidence and explicit ship intentShipped artifact/PR/release/deployDo not use before implementation and QA evidence

/goal Gate

Before /goal, require:

  1. A Spec Kit feature directory or explicit user approval to create one.
  2. No unresolved [NEEDS CLARIFICATION] markers in spec.md.
  3. plan.md names the technical approach and checks.
  4. tasks.md is executable by an agent.
  5. create-goal has produced or refreshed GOAL.md.

If these are not true, route to the missing step instead of launching /goal.

Skill Cards

merlin-skills-routing

Use before non-trivial implementation work and always before /goal. Requires the newest user request and current repo state. Produces the next phase decision. Do not use as a long planning ceremony.

install-merlin-skills

Use when installing, updating, or vendoring this pack into Codex, Claude, or a project-local skill root. Requires a target root or clear default. Produces installed skills and optional AGENTS.md/CLAUDE.md block. Do not use for feature work.

speckit-cli

Use when installing or running the official specify CLI, initializing .specify/, or managing Spec Kit integrations/extensions/presets. Requires permission to mutate project setup. Produces the Spec Kit project infrastructure. Do not use for writing an already-initialized feature spec.

brainstorming

Use when the product direction, UX, or feature shape is still ambiguous. Requires user intent and repo context. Produces an approved design direction. Do not use when the requested behavior is already concrete.

to-prd

Use when existing conversation context should become product requirements or an issue. Requires enough context to synthesize without interviewing. Produces a PRD-style requirement. Do not use when speckit-specify is the better source-of-truth path.

zoom-out

Use when the code area is unfamiliar and the agent needs a map before edits. Requires a topic or area. Produces module/context orientation. Do not use as a substitute for implementation.

speckit-constitution

Use to create or refresh .specify/memory/constitution.md. Requires initialized Spec Kit infrastructure. Produces project principles for later specs and plans.

speckit-specify

Use to create or update specs/<feature>/spec.md from natural-language requirements. Requires .specify/ and a feature description. Produces the feature spec.

speckit-clarify

Use before planning when requirements are underspecified. Requires a feature spec. Produces recorded clarifications. Do not skip if [NEEDS CLARIFICATION] remains.

speckit-plan

Use to create the technical plan and optional design artifacts. Requires a clarified spec. Produces plan.md, plus optional research.md, data-model.md, contracts/, and quickstart.md.

grill-with-docs

Use to pressure-test a plan against project docs, domain language, and ADRs. Requires a draft plan and docs. Produces sharper decisions. Do not use when no meaningful decision is open.

speckit-tasks

Use to convert spec and plan into executable work. Requires current spec.md and plan.md. Produces tasks.md.

speckit-checklist

Use to generate requirement-quality checklists. Requires active feature artifacts. Produces checklist files. Optional for small changes.

speckit-analyze

Use after tasks to check consistency across spec, plan, and tasks. Requires all three artifacts. Produces a non-destructive analysis. Prefer it before create-goal on non-trivial work.

speckit-taskstoissues

Use only when the user explicitly wants GitHub issues from tasks.md. Requires GitHub capability and approval for external side effects. Produces issues.

create-goal

Use to generate GOAL.md from Spec Kit artifacts. Requires clear spec.md, plan.md, and tasks.md. Produces a durable /goal contract. Do not start implementation from this skill.

speckit-implement

Use only when the user explicitly wants upstream Spec Kit native implementation. Requires complete artifacts and approval to execute. Produces implementation directly from tasks.md. Merlin's default is create-goal -> /goal instead.

tdd

Use for feature work and normal bug fixes where tests can drive the change. For Spec Kit work, use it after tasks.md and GOAL.md exist and /goal is executing a concrete implementation slice. For small non-Spec-Kit fixes, a clear behavior target is enough. Produces tested code.

diagnose

Use for hard bugs, unknown failures, flaky tests, or performance regressions. Requires a repro or failing signal. Produces root cause, fix direction, and regression coverage.

gstack-qa

Use after implementation or before ship. Requires active spec/goal and runnable checks. Produces QA evidence and in-scope fixes.

playwright-cli

Use for token-efficient browser interaction, screenshots, and Playwright test workflow. Requires a URL or browser target. Produces browser proof.

playwright-skill

Use when browser proof needs custom scripting or repeatable automation. Requires a scenario. Produces a Playwright script and evidence.

gstack-ship

Use when implementation and QA evidence are ready and the user asks to package, commit, push, PR, tag, release, merge, or deploy. Requires explicit ship intent.

Skill-First Rules

  • Load only the next required skill file.
  • Prefer Spec Kit artifacts over chat memory for feature truth.
  • Prefer tests, browser proof, and QA reports over confidence.
  • Keep generated proof next to the feature or in the repo's existing evidence location.
  • Keep gstack limited to gstack-qa and gstack-ship unless the source-selection policy is intentionally changed.
  • Keep upstream-generated speckit-* skills close to GitHub Spec Kit. Merlin-owned adaptations are speckit-cli, create-goal, gstack-qa, and gstack-ship.

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.