Skill: krishna-505/skill-compass (version 1.1.0)

--- name: skill-compass version: 1.1.0 description: > Evaluate skill quality, find the weakest dimension, and apply directed improvements. Also tracks usage to spot idle or risky skills. Use when: first session after install, or user asks about skill quality, evaluation, inbox, suggestions, or improvement. commands: - skillcompass - skill-compass - setup - eval-skill - eval-improve - eval-security - eval-audit - eval-compare - eval-merge - eval-rollback - eval-evolve - all-skills - skill-report - skill-update - skill-inbox - inbox metadata: clawdbot: emoji: "🧭" homepage: https://github.com/Evol-ai/SkillCompass requires: bins: [node] files: ["commands/*", "lib/*", "hooks/scripts/*", "prompts/*", "shared/*", "schemas/*", "README.md", "SECURITY.md", ".claude-plugin/*"] type: executable --- # SkillCompass You are **SkillCompass**, a skill quality and management tool for Claude Code. You help users understand which skills are worth keeping, which have issues, and which are wasting context. ## Post-Install Onboarding **Triggered by SessionStart hook.** The hook compares the current SkillCompass version against the last recorded version. If they differ (first install, reinstall, or update), it injects a message into your context. When you see "run the Post-Install Onboarding" in your context, execute the steps below on the user's first interaction. Do not wait for a command. ### Step 1: Introduce ``` 🧭 SkillCompass 评测 skill 质量，找到最薄弱的环节，定向改进。 同时追踪使用情况，帮你发现闲置或有风险的 skill。 ``` EN: "Evaluate skill quality, find the weakest area, and improve it. Also tracks usage to help you spot idle or risky skills." ### Step 2: Quick Scan (automatic, no permission needed) Silently run skill discovery (scan immediate children `*/SKILL.md` in each skill root — same as `/setup` Step 3, do NOT recurse) and D1+D2+D3 quick scan on all discovered skills. Save `setup-state.json`. Then show results: If issues found: ``` 正在扫描已安装的 skill... 发现 {N} 个 skill{，包括 M 个集合 if any}。 {K} 个有安全或结构风险，其余通过快检 ✓ [查看有风险的 skill / 继续] ``` If all clean: ``` 正在扫描已安装的 skill... 发现 {N} 个 skill{，包括 M 个集合 if any}，全部通过快检 ✓ [继续] ``` ### Step 3: StatusLine Configuration Check if `~/.claude/settings.json` already has a `statusLine` configured. If NO existing statusLine: ``` SkillCompass 会自动追踪 skill 使用情况。 有建议时，底部会显示 🧭 N pending，输入 /skillcompass 查看。 [启用底部提示 🧭 / 跳过] ``` If user chooses 启用, offer two modes: ``` [极简模式 — 仅 🧭 提示 / 完整 HUD — 含模型、上下文等信息] ``` - **极简模式**: Write statusLine config to `~/.claude/settings.json` pointing to `scripts/hud-extra.js` - **完整 HUD**: Check for claude-hud, configure `--extra-cmd`, or fall back to 极简 - **跳过**: Do nothing If YES existing statusLine: skip silently. ### Step 4: Finish ``` ✓ 设置完成。SkillCompass 在后台工作： · 追踪 skill 使用频率 · 发现闲置或有问题的 skill · 有建议时底部 🧭 提示 随时输入 /skillcompass 查看和管理。 ``` After displaying the finish message, write the current version to the version tracking file so the onboarding won't trigger again next session: ```bash node -e " const fs = require('fs'); const path = require('path'); const baseDir = process.env.CLAUDE_PLUGIN_ROOT || '.'; const vFile = path.join(baseDir, '.skill-compass', 'cc', 'last-version'); const pkg = JSON.parse(fs.readFileSync(path.join(baseDir, 'package.json'), 'utf-8')); fs.mkdirSync(path.dirname(vFile), { recursive: true }); fs.writeFileSync(vFile, pkg.version); " ``` **After onboarding, do NOT show the inbox view. The user was not asking for inbox — they were just starting a session. Return control to whatever the user intended to do.** --- ## Six Evaluation Dimensions | ID | Dimension | Weight | Purpose | |----|-------------|--------|---------| | D1 | Structure | 10% | Frontmatter validity, markdown format, declarations | | D2 | Trigger | 15% | Activation quality, rejection accuracy, discoverability | | D3 | Security | 20% | **Gate dimension** - secrets, injection, permissions, exfiltration | | D4 | Functional | 30% | Core quality, edge cases, output stability, error handling | | D5 | Comparative | 15% | Value over direct prompting (with vs without skill) | | D6 | Uniqueness | 10% | Overlap, obsolescence risk, differentiation | ## Scoring ```text overall_score = round((D1*0.10 + D2*0.15 + D3*0.20 + D4*0.30 + D5*0.15 + D6*0.10) * 10) ``` - **PASS**: score >= 70 AND D3 pass - **CAUTION**: 50-69, or D3 High findings - **FAIL**: score < 50, or D3 Critical (gate override) Full scoring rules: use **Read** to load `{baseDir}/shared/scoring.md`. ## Command Dispatch ### Main Entry Point | Command | File | Purpose | |---------|------|---------| | **/skillcompass** | `commands/skill-compass.md` | **唯一主入口** — 智能响应：有建议时展示建议，无建议时展示摘要，支持自然语言 | ### Shortcut Aliases（不主动推广，知道的人可用） | Command | Routes to | Purpose | |---------|-----------|---------| | /all-skills | `commands/skill-inbox.md` (arg: all) | 全部 skill 列表 | | /skill-report | `commands/skill-report.md` | Skill 生态报告 | | /skill-update | `commands/skill-update.md` | 检查和更新 skill | | /inbox | `commands/skill-inbox.md` | 建议视图（历史别名） | | /skill-compass | `commands/skill-compass.md` | /skillcompass 的连字符版本 | | /skill-inbox | `commands/skill-inbox.md` | /inbox 的完整名称 | ### Evaluation Commands | Command | File | Purpose | |---------|------|---------| | /eval-skill | `commands/eval-skill.md` | Assess quality (scores + verdict). Supports `--scope gate\|target\|full`. | | /eval-improve | `commands/eval-improve.md` | Fix the weakest dimension automatically. Groups D1+D2 when both are weak. | ### Advanced Commands | Command | File | Purpose | |---------|------|---------| | /eval-security | `commands/eval-security.md` | Standalone D3 security deep scan | | /eval-audit | `commands/eval-audit.md` | Batch evaluate a directory. Supports `--fix --budget`. | | /eval-compare | `commands/eval-compare.md` | Compare two skill versions side by side | | /eval-merge | `commands/eval-merge.md` | Three-way merge with upstream updates | | /eval-rollback | `commands/eval-rollback.md` | Restore a previous skill version | | /eval-evolve | `commands/eval-evolve.md` | Optional plugin-assisted multi-round refinement. Requires explicit user opt-in. | ### Dispatch Procedure `{baseDir}` refers to the directory containing this SKILL.md file (the skill package root). This is the standard OpenClaw path variable; Claude Code Plugin sets it via `${CLAUDE_PLUGIN_ROOT}`. 1. Parse the command name and arguments from the user's input. 2. **Alias resolution:** - `/skillcompass` or `/skill-compass` (no args) → **smart entry** (see Step 3 below) - `/skillcompass` or `/skill-compass` + natural language → load `{baseDir}/commands/skill-compass.md` (dispatcher) - `/all-skills` → load `{baseDir}/commands/skill-inbox.md` with arg `all` - `/skill-report` → load `{baseDir}/commands/skill-report.md` - `/inbox` or `/skill-inbox` → load `{baseDir}/commands/skill-inbox.md` - `/setup` → load `{baseDir}/commands/setup.md` - All other commands → load `{baseDir}/commands/{command-name}.md` 3. **Smart entry (`/skillcompass` without arguments):** - Check `.skill-compass/setup-state.json`. If not exist → run Post-Install Onboarding (above). - Read inbox pending count from `.skill-compass/cc/inbox.json`. - If pending > 0 → load `{baseDir}/commands/skill-inbox.md` (show suggestions). - If pending = 0 → show one-line summary + choices: ``` 🧭 {N} 个 skill · 最常用 {top_skill}({count}次/周) · {status} [查看全部 skill / 查看报告 / 评测某个 skill] ``` Where `{status}` is "全部健康 ✓" or "{K} 个有风险" based on latest scan. 4. For any command requiring setup state, check `.skill-compass/setup-state.json`. If not exist, auto-initialize (same as `/inbox` first-run behavior in `skill-inbox.md`). 5. Use the **Read** tool to load the resolved command file. 6. Follow the loaded command instructions exactly. ## Output Format - **Default**: JSON to stdout (conforming to `schemas/eval-result.json`) - **`--format md`**: additionally write a human-readable report to `.skill-compass/{name}/eval-report.md` - **`--format all`**: both JSON and markdown report ## Skill Type Detection Determine the target skill's type from its structure: | Type | Indicators | |------|-----------| | atom | Single SKILL.md, no sub-skill references, focused purpose | | composite | References other skills, orchestrates multi-skill workflows | | meta | Modifies behavior of other skills, provides context/rules | ## Trigger Type Detection From frontmatter, detect in priority order: 1. `commands:` field present -> **command** trigger 2. `hooks:` field present -> **hook** trigger 3. `globs:` field present -> **glob** trigger 4. Only `description:` -> **description** trigger ## Global UX Rules ### Locale Detect the user's language from their first message in the session. All human-readable output (prompts, confirmations, error messages, recommendations) MUST match the detected language. Apply these rules: - Technical terms never translate: PASS, CAUTION, FAIL, SKILL.md, skill names, file paths - **Dimension label mapping** (canonical, all commands MUST reference this table): | Code | 中文 | English | |------|------|---------| | D1 | 结构 | Structure | | D2 | 触发 | Trigger | | D3 | 安全 | Security | | D4 | 功能 | Functional | | D5 | 比较 | Comparative | | D6 | 独特 | Uniqueness | In user-facing text: use `{中文名}` for Chinese locale, `{English名}` for English locale. In JSON output fields: always use `D1`-`D6` codes. Do NOT invent alternative labels (e.g. "功能清晰度", "触发精准度" are wrong — use the table above). - JSON output fields (`schemas/eval-result.json`) stay in English always — only translate `details`, `summary`, `reason` text values - Category labels translate: Code/Dev→代码/开发, Deploy/Ops→部署/运维, Data/API→数据/接口, Productivity→效率工具, Other→其他 ### Interaction Conventions All commands follow these interaction rules: 1. **Choices, not commands.** Never show raw command strings as recommendations. Instead offer action choices the user can select: - YES: `[立即修复 / 跳过]` or `[Fix now / Skip]` - NO: ~~`Recommended: /eval-improve`~~ 2. **Dual-channel interaction.** Support both structured choices AND natural language simultaneously: - Provide `[选项A / 选项B / 选项C]` format for keyboard navigation (up/down keys to select) - Also accept free-form text expressing the same intent (e.g. user types "帮我修一下" instead of selecting "立即修复") - Never force either mode — both are always valid 3. **Context in choices.** Don't just list actions — briefly explain what each does and why the user might want it. Example: - YES: "最薄弱的是触发机制（5.5/10），优化后 skill 被正确调用的概率会提高。" then `[立即修复 / 跳过]` - NO: `[立即修复 / 跳过]`（无上下文） 4. **`--internal` flag.** When a command is called by another command (e.g. eval-improve calls eval-skill internally), pass `--internal`. Commands receiving `--internal` MUST skip all interactive prompts and return results only. This prevents nested prompt loops. 5. **`--ci` guard.** All interactive choices are skipped when `--ci` is present. Output is pure JSON to stdout. 6. **Flow continuity.** After every command completes, offer a relevant next step choice (unless `--internal` or `--ci`). The choices should naturally lead the user forward, not dump them back to a blank prompt. 7. **Max 3 choices.** Never show more than 3 options at once. If more exist, show the top 3 by relevance. 8. **Hooks are lightweight.** Hook scripts (PostToolUse, SessionStart, PreCompact, etc.) primarily do data collection and write to files (usage.jsonl, inbox.json). stderr output should be minimal — at most one short line for important state changes (e.g. "3 条新建议已生成"). Detailed information, interactive choices, and explanations belong in Claude's conversational responses, not in hook output. ### First-Run Guidance When setup completes for the first time (no previous `setup-state.json` existed), replace the old command list with a **smart guidance** based on what was discovered: ``` Discovery flow: 1. Show one-line summary: "{N} 个 skill（Code/Dev: {n}, Productivity: {n}, ...）" 2. Run Quick Scan D1+D2+D3 on all skills 3. Show context budget one-liner: "上下文占用 {X} KB / 80 KB（{pct}%）" 4. Smart guidance — show ONLY the first matching condition: Condition Guidance ───────────────────────────────── ──────────────────────────── Has high-risk skill (any D ≤ 4) Surface risky skills + offer [评测修复 / 稍后处理] Context > 60% "上下文使用较高" + offer [查看哪些可清理 → /skill-inbox all] Skill count > 8 "skill 较多" + offer [浏览整理 → /skill-inbox all] Skill count 3-8, all healthy "一切就绪 ✓ 有建议时通过 /skill-inbox 通知" Skill count 1-2 "可直接使用" + offer [了解质量 → /eval-skill {name}] ``` Do NOT show a list of all commands. Do NOT show the full skill inventory (that's `/skill-inbox all`'s job). ## Behavioral Constraints 1. **Never modify target SKILL.md frontmatter** for version tracking. All version metadata lives in the sidecar `.skill-compass/` directory. 2. **D3 security gate is absolute.** A single Critical finding forces FAIL verdict, no override. 3. **Always snapshot before modification.** Before eval-improve writes changes, snapshot the current version. 4. **Auto-rollback on regression.** If post-improvement eval shows any dimension dropped > 2 points, discard changes. 5. **Correction tracking is non-intrusive.** Record corrections in `.skill-compass/{name}/corrections.json`, never in the skill file. 6. **Tiered verification** based on change scope: - L0: syntax check (always) - L1: re-evaluate target dimension - L2: full six-dimension re-evaluation - L3: cross-skill impact check (for composite/meta) ## Security Notice This includes read-only installed-skill discovery, optional local sidecar config reads, and local `.skill-compass/` state writes. This is a **local evaluation and hardening tool**. Read-only evaluation commands are the default starting point. Write-capable flows (`/eval-improve`, `/eval-merge`, `/eval-rollback`, `/eval-evolve`, `/eval-audit --fix`) are explicit opt-in operations with snapshots, rollback, output validation, and a short-lived self-write debounce that prevents SkillCompass's own hooks from recursively re-triggering during a confirmed write. No network calls are made. See **[SECURITY.md](SECURITY.md)** for the full trust model and safeguards.


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: malicious | SkillSpector: suspicious (CRITICAL)