@vruum/skills-operator

@vruum/skills-operator

OAuth-gated installer for the Vruum operator skill bundle. If you're a Vruum operator (an account that owns 2+ companies in Vruum), this gives you the current operator skills for Claude Code / Codex CLI with one command — no private GitHub access required.

npx @vruum/skills-operator install

What it does

• Opens your browser for Vruum OAuth sign-in (PKCE + state, loopback redirect).
• Saves the session to ~/.vruum/auth.json (mode 0600).
• Downloads the latest operator skill tarball from api.vruum.ai (server verifies your operator role on every request).
• Extracts to ~/.vruum/skills-operator/<sha>/, updates ~/.vruum/skills-operator/current → <sha>/.
• Symlinks each skill into ~/.claude/skills/ and ~/.agents/skills/ via current/ so rollback is atomic.

Commands

npx @vruum/skills-operator install                 # fetch latest
npx @vruum/skills-operator install --force         # override dual-install safety
npx @vruum/skills-operator update                  # alias for install
npx @vruum/skills-operator rollback [--to <sha>]   # flip `current` to a prior build, no network
npx @vruum/skills-operator uninstall               # remove symlinks + skills-operator/

Auth

The first install triggers a loopback OAuth flow. Your session is cached at ~/.vruum/auth.json and refreshes automatically. If the refresh token becomes invalid (password change, session revoked), re-run install to trigger fresh sign-in. The installer never silently wipes auth state — you always see an explicit prompt.

Role revocation

When an admin removes your operator role, the next update-check emits OPERATOR_ROLE_REVOKED inside the skill preamble. Existing installed skills keep working locally but can't upgrade until the role is restored.

Dual-install safety

If you also have ./.agents/setup installed from a local vruum_ai checkout, the operator installer refuses to overwrite those symlinks without --force. Re-running ./.agents/setup explicitly makes the local checkout canonical and replaces operator-installer symlinks.

The public and operator npm bundles can also coexist in the same harness. For overlapping skill names, this bundle takes precedence while its installation is valid. Public installs and uninstalls preserve this bundle's links and update checker. If an operator link becomes stale, the next public install restores the public skill instead of leaving a broken link.

Windows

Symlinks require admin or dev-mode on Windows. Without either, the installer falls back to copying files — works fine, but rollback requires re-running install.

Telemetry (opt-in)

Set telemetry: community (or anonymous) in ~/.vruum/config.yaml to help surface installer bugs. Payload is fixed-shape (version, platform, node, phase, error_class, session_id) and carries zero PII. Default is off.

Pairs with

The Vruum MCP server at https://api.vruum.ai/mcp. The installed skills run as local workflows in your AI assistant; the MCP server provides the tools (including the skill tool, action=invoke) and data those workflows call.

Register the MCP server in your assistant (one-time, after install):

• Claude Code — add to ~/.claude.json:

  "mcpServers": {
    "vruum-local": { "type": "http", "url": "https://api.vruum.ai/mcp" }
  }
  

• Codex CLI — add to ~/.codex/config.toml:

  [mcp_servers.vruum-local]
  url = "https://api.vruum.ai/mcp"
  

• Other assistants — connect to https://api.vruum.ai/mcp (HTTP transport, OAuth via standard MCP flow).

After registration, restart your assistant. Tools like mcp__vruum-local__get_outreach_review should appear in your tool list.

Issues

github.com/vruum-gtm/skills-operator/issues