Skip to main content
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.
AgentSkills bundleRouting 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-release, postmortem, hyperframes, dev-tasks. 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.