rsk-guide

name	rsk-guide
version	0.3.1
description	Operator's guide for the rsk CLI — manage ralvaskills via the .rsk/ project manifest (rsk new, rsk install, rsk pin) or via bundle installs, plus global installs and the official Anthropic cache. Use when the user mentions rsk, asks how to install/pin/update skills, wants to add a skill to a project, or wants to set up ralvaskills on a new machine. Companion to cli-tool-architect (CLI design) and skill-builder (authoring new skills).

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)

Command	Purpose
rsk catalog	All available skills
rsk catalog --bundles	All available bundles
rsk catalog --bundle <name>	Skills in a specific bundle
rsk catalog --source local|official	Filter by source
rsk catalog --personal	Include personal skills
rsk catalog -o json	Machine-readable output
rsk list	Project manifest entries (installed/pinned marks)
rsk list --global	Skills linked in global tool dirs
rsk list --global --for <tool>	Scope global listing to one tool
rsk status	What's installed across project + global; bundle tags; pinned tags (no network)
rsk status --global / --project	Restrict scope
rsk status --for <tool>	Scope --global to one tool

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

Bundle	Source	Use for
global	local	Every machine — universal workflow + meta skills
docs	official	Document creation (docx/xlsx/pdf/pptx/find-docs)
design	mixed	Frontend / UI projects
go-grpc	local	Go gRPC services
gin	local	Go REST services (Gin)
nethttp	local	Go REST services (stdlib net/http)
go-cli	local	Go command-line tools
fastapi	local	Python REST services (FastAPI)
python-grpc	local	Python gRPC services
python-cli	local	Python command-line tools
llm-app	local	LLM apps / RAG pipelines
ros2	local	ROS2 robotics
event-driven	local	Schema-first messaging (NATS/Kafka/RabbitMQ)
observability	local	Signals + dashboards/alerts
code-review	local	Reviewer triad: security, contracts, performance

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.