/skill-report

/skill-report — Skill Portfolio Report

Generate a comprehensive report of all installed skills: quick health scan, context budget, portfolio overview, and quality summary.

Arguments

• `--skip-scan`: Skip Quick Health Scan, only show Parts 2-4
• `--scan-only`: Only show Quick Health Scan (Part 1)

Steps

Step 1: Load Skill Inventory

Use the **Read** tool to load `.skill-compass/setup-state.json`. If the file does not exist, run `/setup` first and then continue from Step 2.

Extract the skill list from the `inventory` array. Each entry provides: `name`, `path`, `version`, `purpose` (category), `modified_at`. Keep the full list in memory.

If `inventory` is empty or missing, output:

No skills found in inventory. Run /setup to discover installed skills.

Then stop.

Step 2: Quick Health Scan (D1+D2+D3)

Skip this step entirely if `--skip-scan` was passed.

Build a `skillEntries` array from the inventory: `[{ name, path, modified_at }, ...]`.

Run the QuickScanner using the **Bash** tool:

const { QuickScanner } = require('./lib/quick-scan');
const scanner = new QuickScanner('cc');
const skillEntries = /* array from inventory */;
const { results, summary } = scanner.scanAll(skillEntries);

Execute with `node -e` passing the constructed skillEntries inline, for example:

node -e "
const { QuickScanner } = require('./lib/quick-scan');
const scanner = new QuickScanner('cc');
const entries = {ENTRIES_JSON};
const out = scanner.scanAll(entries);
console.log(JSON.stringify(out));
"

Replace `{ENTRIES_JSON}` with the actual JSON array. Run this from the SkillCompass base directory (`{baseDir}`).

Sort results: `high_risk` first, then `medium`, then `clean`. Within each group, sort alphabetically by `skill_name`.

For skills that are disabled (check `InboxStore.getSkillCache(name)?.disabled`) or have `ever_used === false` from `UsageReader.getSignals(name)`, mark them with verdict `never_used` for display purposes (use the `○` symbol).

Display the scan table:

Quick Health Scan — {total} skills

  ✓ {name}      D1={d1}  D2={d2}  D3={d3}
  ⚠ {name}      D1={d1}  D2={d2}  D3={d3}  ← {first finding message}
  ✗ {name}      D1={d1}  D2={d2}  D3={d3}  ← {first finding message}
  ○ {name}      D1={d1}  D2={d2}  D3={d3}   (disabled / never used)

  ✓ Clean: {n}    ⚠ Medium: {n}    ✗ High risk: {n}    ○ Skipped: {n}

Verdict symbol mapping:

• `clean` → `✓`
• `medium` → `⚠`
• `high_risk` → `✗`
• `never_used` or disabled → `○`

For `⚠` and `✗` rows, append `← {first finding message}` where the message is the `message` field of the first entry in `findings`, trimmed to 60 characters.

If any skill has `high_risk` verdict in the scan results, add a guidance line after the scan summary for the **first** such skill only (max 1 guidance):

{name} has security or structural risks; a full 6-dimension evaluation is recommended.
[Evaluate {name} (recommended) / Skip]

If `--scan-only` was passed, stop here after displaying this table.

Step 3: Installed Packages

List all directories in the skill scan roots, distinguishing top-level skills from packages:

Installed

  Skills (loaded by Claude Code):
    frontend-design     standalone skill · {activity status}

  Packages (working via hooks/Skill tools):
    superpowers         collection · SessionStart hook · 14 sub-skills
    everything-claude-code  hooks + agents · non-skill collection

  SkillCompass (this tool)

Determine package type by checking the directory:

• Has top-level SKILL.md → "standalone skill"
• Has `hooks/hooks.json` with SessionStart → "collection · SessionStart hook"
• Has `hooks/hooks.json` without SessionStart → "hooks + agents"
• Has `.claude-plugin/` but no SKILL.md → "plugin (no skill)"

For packages with sub-skills (SessionStart hook), count sub-skills by scanning `{dir}/skills/*/SKILL.md`.

Sub-skill usage data comes from `usage.jsonl` (passively tracked via PostToolUse Skill hook). If usage data exists, show top sub-skills:

    superpowers         collection · 14 sub-skills
      Recently used: writing-plans (12×), subagent-driven (6×), executing-plans (3×)

**Skill count health check:**

Count the total number of top-level skills (type = standalone, with SKILL.md loaded by Claude Code). Then:

• **30 or fewer**: No warning. Healthy range.
• **31–50**: Show note (follow locale):

  ⚠ {N} skills installed. Users on non-Opus models (200K context) may experience description truncation, reducing Claude's accuracy in selecting the right skill.

• **Over 50**: Show warning with choices (follow locale):

  ⚠ {N} skills installed. Consider cleaning up idle skills — Claude's accuracy in matching the right skill may decrease.
  [View idle skills / View usage ranking]

Step 4: Portfolio Overview

Read version count from `.skill-compass/{name}/manifest.json` for each skill (count entries in `versions` array, or use field `version_count` if present). Also check `.skill-compass/cc/{name}/manifest.json` first (new path takes priority). If manifest is missing, treat version count as 1.

Determine activity tier from usage signals only (`last_used_at` from `UsageReader.getSignals()`). Do NOT fall back to manifest `versions[].timestamp` — those reflect eval/edit history, not actual invocation, and would inflate active counts for never-invoked skills.

• `active`: `last_used_at` within last 7 days
• `idle`: `last_used_at` 7–14 days ago
• `dormant`: `last_used_at` more than 14 days ago
• `never_used`: `ever_used === false` (no usage events)

Group skills by `purpose` field (from setup-state.json inventory). Use existing category labels: `Code/Dev`, `Deploy/Ops`, `Data/API`, `Productivity`, `Other`.

Classify iteration depth:

• `heavy_iteration (≥5 versions)`: version_count >= 5
• `medium_iteration (2-4 versions)`: version_count 2–4
• `no_iteration (1 version)`: version_count == 1

For activity bars (each 10 chars wide): filled = `round((count /