skill-control-plane

你本地 skill 库的控制平面：用确定性规则（hook）让该用的 skill 在该用的场景每次都触发。 把社区实测的 ~50% 自动触发率推到接近 100%——⚠️ 当前仅逻辑层成立，真机实验是 P1 关口。

🚧 WIP（v0.0.1）。完整规格见 SPEC.md。

60 秒了解

• 痛点：Claude / Codex 的 skill 由模型读 description 自主触发，社区实测约 50% 成功率；用户因此退回手动斜杠命令，skill 库沦为"装完就忘"的一锤子买卖。装到 100~150 个还会因 token 预算与冲突造成 context rot。
• 解法：本地控制平面，五件套——
  • registry 清点 + 去重 + 一句话摘要
  • verify 质量门（结构 + 触发器 lint + 静态安全扫描）
  • usage 解析本地 transcript，统计死重 + 挖规则草案
  • rules + hooks rules.yaml 声明规则；UserPromptSubmit hook 命中即注入"必须 Skill(X)"
  • dashboard 本地只读看板，一键确认草案
• 跨工具：Claude Code（CLAUDE.md / skills / hooks）+ Codex（AGENTS.md）。
• MIT 开源，目标星与影响力，不收费。

60 秒上手

⚠️ P0 完成前命令为 stub。完整命令将随阶段 1–4 上线。

uv tool install --editable .   # 或 pipx install -e .
skillcli --help

skillcli scan            # 阶段 1
skillcli verify --all    # 阶段 2
skillcli usage           # 阶段 3
skillcli dashboard       # 阶段 4
skillcli rules validate  # 阶段 6

备注：CLI 命名为 skillcli 而非 SPEC 里写的 scp——后者与系统 OpenSSH scp（secure copy）撞名。详见 DECISIONS.md。

进度

• 阶段 0：脚手架（pyproject / LICENSE / CLI stub / DECISIONS）
• 阶段 1：发现与注册（discovery + registry + adapters：Claude + Codex 同步）
  • skillcli scan 在本机扫到 130 个 skill（67 Claude + 63 Codex），抓到 1 个跨工具重复
  • 17/17 unittest 通过；注册表落地 ~/.skill-control-plane/registry.json
• 阶段 2：质量门（verify：结构 + 触发器 lint + size + 静态安全扫描）
  • skillcli verify --all 把 130 个 skill 分到 verified 66 / needs-review 59 / blocked 5
  • 5 个 blocked 全为真实安全问题（curl|sh、rm -rf /、subprocess shell=True），无误报
  • 28/28 unittest（含关键反向：SKILL.md 里教学性危险示例不触发）
• 阶段 3：用量（usage：Claude JSONL 解析 + 死重 + 规则建议草案；Codex 诚实降级）
  • skillcli usage 跑通；UsageState.source 新增字段区分 claude_jsonl / unsupported / unknown
  • 真机产品洞察：30 天内 0 次显式 Skill tool_use（扩 365 天仅 6 次）—— Claude Skill 工具调用本就稀疏，多数 skill 是"隐式使用"（context 内被引用、不显式 Skill() 调用）
  • 规则建议引擎按 cwd 集中度挖（≥3 次 + ≥50% 同 cwd → suggest），合成测试验证；真机数据未触阈值
  • 39/39 unittest
• 阶段 4：看板 P0（dashboard：清单 + 徽章 + 死重 + 用量 + 隐式信号）
  • skillcli dashboard --port N 起本地只读 http（stdlib http.server，零依赖）
  • 单文件 HTML + Chart.js CDN：摘要卡片 · 双图（badge/工具分布）· 可搜可过滤可点击展开的 Skill 列表 · 4 个 callout 区（安全告警/重复/死重/规则建议）· 用量 disclaimer
  • 隐式信号 (Phase 4 新)：count_implicit_mentions text-scan，≥5 字符名+词边界+ per-session 计数；本机抓到 codex/review/frontend-design/guard 等真实命中
  • 53/53 unittest（dashboard 端点测真起 http server，不 mock）
• 阶段 4.5：UX 重做 — 把"按数据切片"改成"按用户任务切片"
  • 三 tab 心智分离：概览（健康分 + 今日 3 件该做）/ Skill 库（facet 边栏 + 真搜索 + 比较）/ 问题清单（按类型分组 + 怎么修建议）
  • 新模块：tagging.py（词频自动 tag，blacklist 过滤后本机得 15 个高质量主题：api/cli/images/files/design/...） + issues.py（每 entry 算 [{severity, type, why, how_to_fix}]）
  • registry 扩：description 全字段入库（搜索能命中正文），tags 字段（前端 facet 用）；server 加 /api/tags.json + /api/issues.json 两端点
  • 真机数据：本机 190 条 issue（5 high 安全 + 110 med 触发式 + 75 low 死重/过期 + 1 重复）；触发式 issue 都附"建议改写模板"
  • 69/69 unittest
• 阶段 5：蒸馏票 ticket-codex-maxxing/（AGENTS.md / CLAUDE.md / 3 个 skill）
• 阶段 6（P1）：规则引擎 + hooks（Claude + Codex 双套）+ 真机触发率实验（go/no-go 关口）

Codex 适配为何在 P1 而非 SPEC 原定的 P2：见 DECISIONS.md 2026-05-24 · Q5 反转。

设计信条

路由 / 策略用代码，判断 / 生成用模型。"特定情况必须调用特定 skill" 本质是确定性规则——必须用 hook 实现，不能让 LLM 猜。

License

MIT。

架构与模块设计：ARCHITECTURE.md。