RSK Guide

Draft (v0.3.0). The rsk CLI is in progress. Verify against rsk --help once shipped. For creating new skills (vs managing existing ones), use skill-builder. For designing CLIs in general, see cli-tool-architect.

Always ask the user before taking action

Installing, pinning, updating, or uninstalling skills changes what tools and standards future agents will load in this and other projects. These are architectural decisions, not housekeeping. Never run `rsk install`, `rsk uninstall`, `rsk update`, `rsk new`, `rsk destroy`, `rsk pin`, or `rsk unpin` without explicit user confirmation.

For every proposed action:

1. State the action plainly — which skills/bundles, target scope (--global / --for / project manifest), and what changes on disk (including .rsk/CLAUDE.md and ./CLAUDE.md edits when pinning)
2. Quote the exact command you'd run
3. Wait for the user to confirm, redirect, or decline
4. Use `--dry-run` when available if the user wants to see the effect first

Read-only commands (rsk list, rsk catalog, rsk status without --stack) are safe to run without asking — they only display state. Anything that touches symlinks, the manifest, the project CLAUDE.md, the official cache, or makes network calls (rsk status --stack) needs an explicit go.

If the user gives a blanket "yes" up front (e.g. "set everything up for this project"), still pause and confirm before each bundle or pin. A slip from go-grpc to go-rest, installing globally when they meant locally, or pinning a skill they didn't want auto-loaded is hard to undo silently.

Two workflows

Pick the one that matches the user's intent.

A. Project manifest (.rsk/) — preferred for per-project skill sets

Mirrors go.mod: a declarative rsk.mod lists the skills this project depends on, rsk.lock records resolved versions, and pinned skills are auto-imported into ./CLAUDE.md via @.rsk/CLAUDE.md. Lives in <project>/.rsk/.

rsk new                                # creates .rsk/rsk.mod + .rsk/CLAUDE.md + appends import to ./CLAUDE.md
rsk install <name[@version]>           # adds to manifest, symlinks into .rsk/skills/, updates rsk.lock
rsk install <name> --pin               # also imports skill into .rsk/CLAUDE.md (auto-loaded in this project)
rsk pin <name>                         # pin an already-installed skill
rsk unpin <name>                       # remove the import (skill stays installed)
rsk list                               # show manifest entries with pinned/installed marks
rsk update <name>                      # re-resolve + re-link to latest available version
rsk install                            # (no args) re-installs everything in rsk.mod (after clone, after edits)
rsk destroy                            # delete .rsk/ and remove @.rsk/CLAUDE.md import

Pin vs install — installed skills are present on disk but not auto-loaded; pinned skills are imported in .rsk/CLAUDE.md and load every turn in that project. Pin only what truly needs auto-loading.

B. Bundle / global install — fastest path for stack-standard setups

Install a curated bundle or single skill into the project (.rsk/skills/) or globally with --global (~/.claude/skills/, ~/.config/opencode/skills/).

rsk install <name...>                              # project: bundle or skill → .rsk/skills/, writes rsk.mod
rsk install <name...> --global                     # global: all configured tool dirs, no manifest
rsk install <name> --global --for claude-code      # global, one tool only
rsk install <name> --personal                      # personal/ skill, explicit opt-in
rsk install <name> --dry-run                       # preview without writing

Names are auto-resolved against the catalog: a name that matches a bundle expands to that bundle's skills; otherwise the name is treated as a single skill. Bundles win on name collisions.

Project installs land in .rsk/skills/ and always update rsk.mod. Use --global if you want the skill linked system-wide without manifest tracking.

Quick reference

Discover (read-only — safe)

Setup (state-changing — ask first)

rsk init                              # once per machine — writes ~/.config/rsk/config.json
rsk init --force                      # overwrite existing config

rsk init prompts for:

1. Skill source: local clone (path to your ralvaskills repo) or hosted registry (skills.ralvarez.dev)
2. AI tools to support: claude-code, opencode, or both
3. Global skills dir per selected tool (defaults: ~/.claude/skills/, ~/.config/opencode/skills/)
4. Default scope for bare --global (all configured tools, or a single tool)

Update (state-changing — ask first)

rsk update [name...] [--global] [--for <tool>] [--official] [--personal] [--dry-run]

• Local-clone mode: git pull on the repo (symlinks update automatically). Add --official to also pull anthropics/skills cache.
• Registry mode: fetches latest index, re-downloads + re-links any skill whose installed version is behind.

Uninstall (state-changing — ask first)

rsk uninstall <name...> [--global] [--for <tool>] [--personal] [--dry-run]

Project uninstall also cleans the matching entries from rsk.mod / rsk.lock and unpins them from .rsk/CLAUDE.md (or opencode.json).

Status with live fetch (network — ask first; not yet implemented)

rsk status --stack [--refresh]        # planned: fetch latest versions from proxy.golang.org / pypi.org

Per the spec this is opt-in with a 24h cache; the current build returns an explicit "not yet implemented" error. Don't promise drift checks until it ships.

Common workflows

First-time machine setup (confirm each step with the user)

1. rsk init — pick local clone or registry, configure tools
2. rsk install global --global — universal skills, machine-wide

Set up a new project with tracked manifest

1. cd <project> then rsk new
2. rsk install <name> per skill (use --pin for ones that should always auto-load)
3. Commit .rsk/rsk.mod, .rsk/rsk.lock, .rsk/CLAUDE.md, and the @.rsk/CLAUDE.md import line in ./CLAUDE.md

Set up a new project with a stack bundle

1. cd <project> then rsk new
2. rsk install <stack-bundle> — e.g. rsk install go-grpc

Bring an existing manifest project up to date after `git clone` — rsk install (no args)

Add a single skill mid-project

• Tracked: rsk install <name> (+ --pin if it should auto-load)
• Untracked, system-wide: rsk install <name> --global

Update everything — rsk update (local clone) or rsk update --official (also refresh Anthropic cache)

Upgrade a single manifest skill — rsk update <name>

Bundle quick map

What's in .rsk/

.rsk/
├── rsk.mod         # TOML: version, pinned[], skills{name = version-constraint}
├── rsk.lock        # TOML: resolved {name, version, source, path} per skill
├── skills/         # symlinks into the local repo or registry cache
│   └── <name>/     # → ralvaskills/skills/.../<name>/  or  registry cache
└── CLAUDE.md       # one `@skills/<name>/SKILL.md` line per pinned skill

./CLAUDE.md gets a single appended line: @.rsk/CLAUDE.md. Both rsk new (creates it) and rsk destroy (removes it) are idempotent.

Full reference

For the complete CLI specification — exhaustive flag list, config.json shape, catalog overrides, discovery rules, edge-case behavior — see docs/SPECS.md in the ralvaskills repo.