/setup

/setup - Skill Inventory & Health Check

This command gives users a quick local inventory of installed skills and surfaces only high-signal issues. It supports two modes:

• **Manual mode**: the user explicitly runs `/setup` or `/skill-compass setup`
• **Auto-trigger mode**: first-run helper shown before another command

In auto-trigger mode, setup must never replace or derail the user's original request. Its job is to help briefly, save state, and return control to the dispatcher.

Step 1: Determine Mode and Load State

1. Detect whether setup was invoked manually or as a first-run auto-trigger. 2. If auto-triggered, preserve the original command name and arguments as `resume_command` and `resume_args`. 3. Use `.skill-compass/setup-state.json` as the primary persisted state file. 4. For backward compatibility, if `.skill-compass/setup-state.json` is missing but `.skill-compass/.setup-done` exists, read the legacy marker and migrate the minimal fields into `setup-state.json`. 5. Load the standard OpenClaw config file `~/.openclaw/openclaw.json` if it exists. If present, read optional extra skill roots from `skills.load.extraDirs`. 6. If setup was auto-triggered and a current setup state already exists, return control to the dispatcher immediately so it can continue the original command.

Step 2: Confirm Auto-Trigger (auto-trigger mode only)

When auto-triggered, ask the user first:

> Quick skill inventory (~5 sec) before continuing `{resume_command}`? [OK / Skip]

• If the user says `Skip`:
• Write `.skill-compass/setup-state.json` with `{"version": 1, "skipped": true, "timestamp": "{ISO}"}`
• Also write `.skill-compass/.setup-done` for compatibility
• Return control to the dispatcher immediately so it can continue the original command
• If the user agrees:
• Continue with setup

Manual `/setup` does not need this confirmation.

Step 3: Discover Skills

Build the scan root list in this priority order:

1. `.claude/skills/` (project-level Claude Code) 2. `.openclaw/skills/` (project-level OpenClaw, if present) 3. Each path listed in `skills.load.extraDirs` from `~/.openclaw/openclaw.json` 4. `~/.claude/skills/` (user-level Claude Code) 5. `~/.openclaw/skills/` (user-level OpenClaw, if present)

Resolve only directories that actually exist.

Scan each root for `*/SKILL.md` and `*/skill.md` (immediate children only — this matches Claude Code's own discovery pattern).

**Do NOT scan recursively.** Sub-skills inside packages (e.g., `superpowers/skills/writing-plans/SKILL.md`) are discovered passively via `PostToolUse Skill` hook when users invoke them. Scanning recursively would pick up internal files (agent definitions, translations, other-platform configs) that aren't user-facing skills.

Exclude:

• paths containing `node_modules/`, `.git/`, `test-fixtures/`, `.skill-compass/`
• SkillCompass's own SKILL.md at `{baseDir}`

Package Detection

For each directory in the scan roots that does NOT have a top-level SKILL.md, check if it looks like an installed package. A directory is a **package** if it has at least one of:

• `.claude-plugin/` directory
• `hooks/hooks.json` file
• `package.json` file

Add packages to `inventory` with `type: "package"` (not `type: "skill"`). Include:

• `name`: directory name
• `type`: `"package"`
• `path`: directory path
• `has_hooks`: whether `hooks/hooks.json` exists
• `has_session_start`: whether hooks.json contains a SessionStart entry
• `is_git`: whether `.git/` exists

Sub-skills inside packages (e.g., `superpowers/skills/writing-plans/SKILL.md`) are NOT added to inventory individually. They are passively discovered via the `PostToolUse Skill` hook when users invoke them through the Skill tool.

Package Security Scan

For each detected package, recursively find all SKILL.md files within the package directory (`**/SKILL.md`, excluding `node_modules/` and `.git/`). Run D3 security pattern matching only (from `lib/patterns.js`) on each file:

• Secret patterns
• Dangerous command patterns
• Injection patterns
• Exfiltration patterns
• Embedded shell patterns (`!` syntax)

This is pattern matching only — no D1/D2 evaluation, no LLM calls. Results are NOT added to inventory. Display inline:

If all clean:

{package_name}: {N} sub-skill files scanned, no security issues ✓

If issues found:

{package_name}: {N} sub-skill files scanned, {M} issue(s) found
  ⚠ {filename}: {finding description}

EN: Same format, follow locale.

Package Sub-Skill Map

During the package scan above, build a reverse lookup map: `sub_skill_name → package_name`. For each SKILL.md found inside a package, extract the `name` field from frontmatter (or use the directory name as fallback).

Write the map to `.skill-compass/cc/package-skill-map.json`:

{
  "writing-plans": "superpowers",
  "executing-plans": "superpowers",
  "brainstorming": "superpowers",
  "subagent-driven-development": "superpowers"
}

This map is used by `hooks/scripts/skill-usage-tracker.js` to attribute sub-skill invocations to their parent package when the PostToolUse Skill payload doesn't include the package prefix. This ensures usage records always have the qualified form (`superpowers:writing-plans`) for traceability.

Deduplicate by canonical skill identity:

• prefer earlier roots in the priority order above
• if the same skill exists at both project and user level, keep the project-level copy
• if frontmatter `name` is missing, fall back to the skill directory name

Keep the full deduplicated list in memory for persistence and batch actions.

If no skills are found:

No installed skills found in the scanned roots.
If your OpenClaw skills live in a custom path, add it to `skills.load.extraDirs` in `~/.openclaw/openclaw.json`.

Save an empty snapshot state, write `.skill-compass/.setup-done`, and:

• in auto-trigger mode: return control to the dispatcher so it can continue the original command
• in manual mode: stop

If more than 20 skills are found:

• so