The rig skill

Rig writes two skills for Claude Code: a user-level one for everywhere, and a project-level one specific to each rig workspace. The project-level skill takes precedence inside a rig.

User-level skill

Path: ~/.claude/skills/rig/SKILL.md

Installed by the postinstall hook of @rigxyz/cli. If ~/.claude/ doesn't exist (you're not a Claude Code user), nothing is written.

To opt out:

RIG_SKIP_SKILL_INSTALL=1 npm install -g @rigxyz/cli

What it teaches Claude:

• What rig is, in one paragraph.
• Intent → action lookup table: when the user says "start a rig here", the agent runs rig init; "make this collaborative" → rig share --enable; "publish this" → rig hub publish; etc.
• Context detection: how to recognise a bound rig (.rig/tap-binding.local.json present), an author workspace (rig.toml but no binding), an empty folder.
• Safe read-only commands the agent can run without asking.
• Commands that require explicit user approval: rig init in non-empty dirs, rig install --run-hooks, rig join, rig hub publish, rig disconnect --purge.
• Boundary rules: never read .rig/tap-binding.local.json, never kill the daemon directly, never commit .rig/*.local.json.

It's the bootstrap. Without it, an agent in an empty folder has no context for "the user just said 'start a rig'".

The skill is versioned via a SKILL_VERSION marker so the postinstall is idempotent — upgrading @rigxyz/cli updates the skill in place; downgrading leaves the newer version alone.

Project-level skill

Path: .claude/skills/rig/SKILL.md (per workspace)

Written by rig init and refreshed by rig pack. Specific to this rig.

What it adds beyond the user-level skill:

• The workspace's current rig doctor --json snapshot embedded for reference.
• The workspace's rig.toml embedded for reference.
• A read-first guidance list: read rig.toml, then .rig/instance.toml, then README.md, then CLAUDE.md, then check rig doctor.
• A 7–9 step repair workflow: run doctor, fix env, fix dirs, fix MCP, fix tools, fix plugins, re-run doctor, start the rig. See Repair workflow.
• The full list of declared requirements: env vars (with template path), tools, MCP servers, plugins, local dirs, permissions, install commands.
• For sync rigs: a collab repair table covering tapd version, binding state, daemon health, sync status.

The project-level skill is what makes the agent useful for this specific rig rather than for rigs in general.

How they compose

Claude Code reads skills in increasing specificity: user-level first, then project-level. Project-level entries override user-level ones when both apply. This is by design — a rig author can tell Claude things that override the global defaults (e.g. "in this rig, prefer running ./scripts/refresh.sh over inferred behavior").

Updating

• User-level: bump via npm install -g @rigxyz/cli@latest. The postinstall hook re-writes the file if the version is newer.
• Project-level: re-run rig init (with --force if rig.toml already exists, though init usually preserves the skill on regen), or rig pack (which refreshes the skill files before packing).

Disabling

If you don't want either skill:

• Skip user-level on install: RIG_SKIP_SKILL_INSTALL=1.
• Skip project-level: delete .claude/skills/rig/ after rig init. Future rig pack will not recreate it unless rig init is re-run.

Why you'd disable: if you're using a different agent runtime or you don't want Claude to act autonomously in your workspaces.

Inspecting

cat ~/.claude/skills/rig/SKILL.md          # user-level
cat .claude/skills/rig/SKILL.md            # project-level (in a rig)

Skills are plain markdown with YAML frontmatter. The frontmatter declares the skill name and allowed-tools — a precise list of Bash commands the skill grants the agent without further prompting.

See also

• Repair workflow — what the project-level skill teaches.
• Doctor as live state — the data the skill reads.
• Install the CLI — when each skill gets written.