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

install-merlin-skills

Skill1 starsChanged 6 months agoMITView on GitHub

Install or refresh Merlin Skills globally for Codex/Claude or project-locally under .codex/skills or .claude/skills. Use when the user asks to set up, install, update, or vendor this skill pack into a machine or repo.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use when the user asks to:

    line 14
  2. Very specific:

    Do not use this for normal feature routing.

    line 22
  3. Distinctive:

    Default to both global only when the user says "global" without naming a runtime.

    line 37
  4. Very specific:

    Do not delete an existing ~/.claude/skills/gstack directory automatically.

    line 47
  5. Very specific:

    All other gstack skills are intentionally excluded.

    line 58
  6. Distinctive:

    If none exists, clone it:

    line 68
  7. Distinctive:

    If the directory exists but is not this repo, stop and report the path conflict.

    line 75
  8. Distinctive:

    Before installing, verify the source checkout:

    line 83
  9. Very specific:

    If npm test fails, stop unless the user explicitly asked to install an unverified checkout.

    line 90
  10. Distinctive:

    Run commands from the source checkout.

    line 94
  11. Distinctive:

    If installing for both project runtimes, update both files.

    line 141
  12. Very specific:

    If the file has an existing ## Merlin Skills block, replace only that block.

    line 143
  13. Distinctive:

    Do not copy the global adapter into a project.

    line 157

≈ “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

Install Merlin Skills

Install or refresh this skill pack into a global skill root or a project-local skill root.

This is a repo-owned meta skill. It routes installation; it does not duplicate scripts/install-local.sh.

When To Use

Use when the user asks to:

  • install Merlin Skills globally;
  • install Merlin Skills into Codex or Claude;
  • install this pack into the current project;
  • refresh or update an existing Merlin Skills installation;
  • make a repo use merlin-skills-routing and the skill-first /goal workflow.

Do not use this for normal feature routing. Use merlin-skills-routing for implementation work.

Required Decision

Pick exactly one target mode from the user's request:

User intentModeSKILL_ROOT
"global", no runtime specifiedboth globalrun Codex and Claude installs
Codex globalglobal Codex$HOME/.codex/skills
Claude globalglobal Claude$HOME/.claude/skills
current project for Codexproject Codex<project>/.codex/skills
current project for Claudeproject Claude<project>/.claude/skills
custom pathcustomuser-provided SKILL_ROOT

Default to both global only when the user says "global" without naming a runtime.

This release no longer installs a gstack runtime sidecar. GSTACK_ROOT may be passed for backward-compatible scripts, but scripts/install-local.sh does not sync or build ~/.claude/skills/gstack.

For all normal modes, use only:

SKILL_ROOT="<target-skill-root>"

Do not delete an existing ~/.claude/skills/gstack directory automatically. It may belong to a standalone gstack install.

Gstack Prefix Contract

Install every retained gstack-derived user-facing skill with the gstack- prefix. This avoids collisions with skills from Matt Pocock, Merlin-owned meta skills, project-local skills, or future packs.

Examples:

  • source skills/qa installs as $SKILL_ROOT/gstack-qa;
  • source skills/ship installs as $SKILL_ROOT/gstack-ship.

All other gstack skills are intentionally excluded. The installer removes stale Merlin-managed copies such as gstack-review, gstack-office-hours, and gstack-browse from the selected SKILL_ROOT when it can identify them as gstack-managed.

Locate The Merlin Skills Repo

Find the source checkout in this order:

  1. Current working directory or an ancestor containing both skills/merlin-skills-routing/SKILL.md and scripts/install-local.sh.
  2. Environment variable MERLIN_SKILLS_REPO.
  3. A local checkout at $HOME/.local/share/merlin-skills.

If none exists, clone it:

mkdir -p "$HOME/.local/share"
git clone https://github.com/merllinsbeard/merlin-skills.git "$HOME/.local/share/merlin-skills"

If the directory exists but is not this repo, stop and report the path conflict.

Set MERLIN_SKILLS_REPO to the resolved absolute checkout path before running commands:

MERLIN_SKILLS_REPO="<resolved-merlin-skills-checkout>"

Before installing, verify the source checkout:

cd "$MERLIN_SKILLS_REPO"
npm test

If npm test fails, stop unless the user explicitly asked to install an unverified checkout.

Install Commands

Run commands from the source checkout.

Global Codex:

SKILL_ROOT="$HOME/.codex/skills" bash scripts/install-local.sh

Global Claude:

SKILL_ROOT="$HOME/.claude/skills" bash scripts/install-local.sh

Both global:

SKILL_ROOT="$HOME/.codex/skills" bash scripts/install-local.sh
SKILL_ROOT="$HOME/.claude/skills" bash scripts/install-local.sh

Project Codex:

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SKILL_ROOT="$PROJECT_ROOT/.codex/skills" bash "$MERLIN_SKILLS_REPO/scripts/install-local.sh"

Project Claude:

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SKILL_ROOT="$PROJECT_ROOT/.claude/skills" bash "$MERLIN_SKILLS_REPO/scripts/install-local.sh"

Custom:

SKILL_ROOT="<absolute-skill-root>" bash "$MERLIN_SKILLS_REPO/scripts/install-local.sh"

Project Instruction Block

For project-local installs, update the target project's instruction file after the install:

  • Codex project install: update AGENTS.md.
  • Claude project install: update CLAUDE.md.
  • If installing for both project runtimes, update both files.

If the file has an existing ## Merlin Skills block, replace only that block. Otherwise append this block:

## Merlin Skills

Use `merlin-skills-routing` before non-trivial implementation work and always before long-running `/goal` work.

Default route: `brainstorming` or `to-prd` -> `speckit-cli` when setup is missing -> `speckit-*` artifact skills -> `create-goal` -> `/goal` -> `tdd` or `diagnose` -> `gstack-qa` -> browser proof -> `gstack-ship`.

For Spec Kit work, `tdd` starts after `tasks.md` and `GOAL.md` exist and `/goal` is executing an implementation slice. Do not use `tdd` to replace `speckit-tasks`.

Create or refresh `GOAL.md` from Spec Kit artifacts before autonomous implementation. Use `install-merlin-skills` to refresh this project's local skill installation.

Do not copy the global adapter into a project. Add only this project-specific block.

Verification

After install, verify:

find "$SKILL_ROOT" -maxdepth 2 -name SKILL.md | wc -l
test -f "$SKILL_ROOT/install-merlin-skills/SKILL.md"
test -f "$SKILL_ROOT/speckit-cli/SKILL.md"
test -f "$SKILL_ROOT/speckit-specify/SKILL.md"
test -f "$SKILL_ROOT/speckit-plan/SKILL.md"
test -f "$SKILL_ROOT/speckit-tasks/SKILL.md"
test -f "$SKILL_ROOT/gstack-qa/SKILL.md"
test -f "$SKILL_ROOT/gstack-ship/SKILL.md"
test ! -e "$SKILL_ROOT/gstack-review/SKILL.md"
grep -q '^name: gstack-qa$' "$SKILL_ROOT/gstack-qa/SKILL.md"

Expected installable skill count for this release: 23.

For project-local installs, also verify the instruction file contains exactly one ## Merlin Skills block.

Report

Report:

  • source checkout path;
  • target mode;
  • final SKILL_ROOT;
  • whether npm test passed before install;
  • installable skill count;
  • instruction file updated, if project-local.

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.