Skills and playbooks

ralphy skill install across agents, the sentinel-bounded merge contract, and how playbooks differ from skills.

ralphy skill install lays down the agent-side glue — slash-command shims, routing pointers, per-playbook stubs — for whichever AI agent you use. The actual instructions live in docs/playbooks/<name>.md in the repo; skills are thin shims that point the agent at them. This page documents the install surface and the contract.

ralphy skill install

ralphy skill install --agent claude
ralphy skill install --agent cursor --scope project
ralphy skill install --agent codex                  # always project scope
ralphy skill install --agent copilot                # always project scope
ralphy skill install                                # interactive wizard
ralphy skill install --reconfigure                  # re-prompt
ralphy skill install --symlink --agent claude       # symlink instead of copy

The verb is idempotent — re-running replaces the sentinel-bounded block in-place. Three agents ship in v1 (claude, cursor, codex); copilot is supported via the same installer.

--agent <id> · string

claude, cursor, codex, or copilot. Auto-detects from $HOME/.claude, $HOME/.cursor, AGENTS.md when omitted.

--scope <s> · string

user or project. Defaults differ per agent: claude/cursor → user, codex → project (forced), copilot → project (forced).

--symlink · boolean

Symlink the skills bundle instead of copying. Useful when iterating on .agents/skills/ locally.

--reconfigure · boolean

Re-launch the wizard, overwriting the persisted choice in ~/.ralphy/config.json.

Full surface: /reference/cli/skill.

What gets written

The install path depends on the agent. Each adapter is sentinel-bounded — <!-- ralphy:start v=1 --> / <!-- ralphy:end --> — so re-running swaps the block without duplicating it.

Agent	Skills bundle	Routing pointer
claude (user)	~/.claude/skills/ralphy/	~/.claude/CLAUDE.md (merged)
claude (project)	./.claude/skills/ralphy/	./CLAUDE.md (merged)
cursor	~/.cursor/rules/ or ./.cursor/rules/	ralphy-router.mdc (always-apply) + per-playbook .mdc files
codex (project)	n/a	./AGENTS.md (merged)
copilot (project)	n/a	./.github/copilot-instructions.md + per-playbook files under ./.github/instructions/

For Cursor and Copilot, the installer writes one file per playbook (intake, researcher, scenarist, art-director, editor, producer, core), each with a description Cursor / Copilot use to surface it on relevant intents.

ralphy skill uninstall

Reverses the install — removes the skills dir, strips the sentinel block from any routing file. If the routing file is empty after the strip, the verb deletes the file outright.

ralphy skill uninstall --agent claude
ralphy skill uninstall              # remove from every detected agent

ralphy skill new

Scaffolds a new skill: writes .agents/skills/<name>/SKILL.md plus docs/playbooks/<name>.md, optionally adds a row to AGENTS.md’s routing table.

# Interactive — clack-prompts wizard
ralphy skill new my-flow

# Scripted
ralphy skill new my-flow \
  --non-interactive \
  --intent "Does the X thing" \
  --trigger "do X" --trigger "/x"

# Maintainer namespace
ralphy skill new dev-only \
  --namespace maintainer \
  --non-interactive --intent "Maintainer-only" --trigger "/dev-only"

# Also append a row to AGENTS.md
ralphy skill new fancy --add-to-routing --row "When user wants fancy"

Names must be kebab-case (^[a-z][a-z0-9-]*$); collisions raise E_ALREADY_EXISTS. Full surface: /reference/cli/skill.

Skills vs. playbooks

The two are deliberately distinct.

• Skills are slash-command-invocable shims under .agents/skills/<name>/SKILL.md. The user can type /researcher and the agent loads the skill body. They’re thin pointers — most of the body is “Read docs/playbooks/<name>.md before acting.”

• Playbooks are the canonical instructions under docs/playbooks/<name>.md. The agent reads them on demand based on intent matching in AGENTS.md, not on a user typing a slash command.

Examples of skills shipped today: researcher, evaluator, install, dev-issues, dev-loop, dev-publish-template, dev-release, postmortem, hyperframes, dev-tasks, normalize-skills. Playbooks: intake, researcher, scenarist, art-director, editor, producer, core, install, hyperframes, plus the per-domain references.

Playbooks are not slash-invocable on purpose — the user shouldn’t have to know which playbook to summon. AGENTS.md routes by intent.

Namespaces

Two namespaces ship in v1:

• user — user-facing skills (the default for skill new).
• maintainer — maintainer-only flows. Pass --namespace maintainer on skill new; pass --dev to skill install to also install the maintainer namespace.

Both end up under .agents/skills/<name>/; the namespace is a convention in SKILL.md frontmatter and the routing row text.

Wizard mode

ralphy skill install with no --agent flag launches an interactive wizard on TTY: it auto-detects installed agents, asks for a scope, persists the choice to ~/.ralphy/config.json. Subsequent runs re-install non-interactively from the persisted choice; --reconfigure re-prompts.

Off-TTY (piped, --json) with no flags → E_WIZARD_NEEDS_TTY rather than hanging. Pass --agent explicitly to skip the wizard.

Related

• AGENTS.md — the routing contract every install points to
• Skill format — the SKILL.md schema
• docs/playbooks/ — the canonical instruction set
• cli/lib/skill/installer.ts