Install Merlin Skills

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 intent | Mode | SKILL_ROOT | | --- | --- | --- | | "global", no runtime specified | both global | run Codex and Claude installs | | Codex global | global Codex | $HOME/.codex/skills | | Claude global | global Claude | $HOME/.claude/skills | | current project for Codex | project Codex | /.codex/skills | | current project for Claude | project Claude | /.claude/skills | | custom path | custom | user-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=""

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=""

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="" 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: merllinsbeard
• Source: merllinsbeard/merlin-skills
• License: MIT

Install and usage instructions live in the source repository linked above.