aniboy2k-gif/skill-advisor
GitHub: aniboy2k-gif/skill-advisor
一个面向 Claude Code 的只读技能诊断工具，用于扫描和审计技能配置问题并输出可审查的 JSON 修复提案，而不会修改任何文件。
Stars: 0 | Forks: 0
# skill-advisor
[](https://code.claude.com/docs/en/skills)
[](LICENSE)
**skill-advisor** 是一个用于 [Claude Code](https://code.claude.com) 的只读诊断技能。它永远不会修改 SKILL.md 文件——它只显示问题并输出结构化的 JSON 提案，供您在准备好时审查并应用。
## 何时使用
- 即使您已安装技能，该技能也没有自动加载
- 两个技能似乎同时对同一个文件做出反应
- 您想在手动编辑技能配置之前进行安全检查
- 您想知道哪些技能没有设置基于文件的自动触发器
## 功能
### 查找不可达和配置错误的技能 — `--scan`
审计所有已安装的技能并按严重程度对问题进行分类：
| 代码 | 严重程度 | 含义 | 用户影响 |
|------|----------|---------|-------------|
| C1 | **严重** | `file_path_globs` 中的绝对路径损坏 | 技能静默加载失败 |
| H0 | **高** | 幽灵技能——所有机制中均无触发器 | 技能完全不可达 |
| H1 | **高** | 缺少 `file_path_globs` | 技能不会在文件编辑时加载 |
| M1 | **中** | 2个及以上技能声明了重复的 glob 字符串 | 可能导致重复加载 |
| I1 | **信息** | `description` 字段为空 | 降低索引质量 |
*H0 的严重程度高于 H1：幽灵技能完全不可达，而 H1 技能仍然可以通过 utterance patterns（话语模式）触发。*
### 审查工作后的技能覆盖情况 — `--session-review`
完成一项任务后，检查哪些已安装的技能与您编辑的文件相关——以及哪些可能错过了加载。
分析当前 Claude Code 会话的 JSONL 文件，以根据文件更改推荐相关技能：
```
/skill-advisor --session-review → Immediate analysis (most recent session)
/skill-advisor --session-review --confirm → Choose session interactively
/skill-advisor --session-review --json → Machine-readable output
```
示例输出：
```
## /skill-advisor --session-review
⚠ Candidate recommendations only — load history not directly verified.
Session: abc123.jsonl (2026-04-23 09:18, 12365 KB)
Parsed: 160 file edit events / 758 tool_uses
Related Skill Candidates:
[medium] skill-creator — SKILL.md ← **/.claude/skills/**
[low] doc-coauthoring — README.md ← **/README.md
```
### 获取可审查的改进提案 — `--enrich [skill-name]`
读取目标技能的 SKILL.md，可选地获取 `anthropics/skills` 来源的官方 README，并输出一个 `SkillPatchProposal[]` 数组——即供您在应用前审查的结构化建议。
### 机器可读输出 — `--scan --json`
返回用于 CI 流水线或 shell 脚本的 JSON 数组。
## 设计上的安全性
skill-advisor 永远不会写入 SKILL.md。对技能配置的更改应始终是经过意图确认和审查的。
| 操作 | 工具 |
|--------|------|
| 诊断与建议 | **skill-advisor**（本工具） |
| 应用更改 | `skill-creator --apply-proposal` *(第二阶段)* |
## 什么是 Claude Code 技能？
Claude Code 技能是扩展 Claude 功能的 `SKILL.md` 文件。每个技能可以定义三种类型的**触发机制**：
| 机制 | 工作原理 |
|-----------|-------------|
| `file_path_globs` | 当您编辑匹配的文件路径时自动加载该技能 |
| `tool_events` | 当特定工具（Edit, Write...）用于匹配文件时自动加载 |
| `utterance_patterns` | 当您用自然语言描述任务时，帮助 Claude 识别该技能 |
skill-advisor 会审计这全部三种机制。一个都不具备的技能就是“幽灵技能”——已安装但无法访问。
## 前置条件
- 已安装并运行 [Claude Code](https://code.claude.com)
- `skill-index.sh` SessionStart hook 已激活
检查它是否已安装：
ls ~/.claude/hooks/skill-index.sh
# 如果已安装，将打印路径——如果未找到，请安装 Claude Code hooks 包
## 安装
```
# Clone 和 install
git clone https://github.com/aniboy2k-gif/skill-advisor
cp -r skill-advisor ~/.claude/skills/
# ↑ 这将复制 SKILL.md、scripts/session-review.py 和 references/
# 重建 skill index，以便 Claude Code 识别新 skill
# （这将重新生成 skill-advisor 读取的 /tmp/skill-index.json）
zsh ~/.claude/hooks/skill-index.sh
```
启动或重启 Claude Code 会话——skill-advisor 将立即可用。
## 用法
```
/skill-advisor → Full scan (default)
/skill-advisor --scan → Coverage audit with severity labels
/skill-advisor --scan --json → JSON output for automation
/skill-advisor --enrich → Deep analysis + SkillPatchProposal output
/skill-advisor --session-review → Post-work skill candidate recommendations
/skill-advisor --session-review --confirm → Choose session interactively
```
### `--scan` 输出示例
```
## skill-advisor --scan (2026-04-23)
| Skill | globs | events | Type | Issues |
|------------------|-------|--------|-------------|---------|
| doc-coauthoring | 8 | 10 | normal | — |
| skill-creator | 7 | 12 | normal | — |
| my-custom-skill | 0 | 0 | manual-only | ℹ H1-M |
Issue list
[HIGH] orphan-skill: H0 Ghost skill — no triggers defined
[HIGH] half-baked-skill: H1 file_path_globs missing
[MEDIUM] skill-a, skill-b: M1 duplicate glob "**/*.md"
Note: H1-M (manual-only) = skill relies on utterance patterns only,
intentionally excluded from the H1 warning.
⚠ M1 matches exact strings only — fnmatch path overlap detection coming in Phase 2.
```
### `SkillPatchProposal` 输出示例 (`--enrich`)
```
[
{
"schema_version": "1.0",
"skill": "doc-coauthoring",
"target_field": "file_path_globs",
"proposal_type": "add_glob",
"value": "**/*.mdx",
"current_value": ["**/*.md"],
"source": "official_readme",
"source_url": "https://github.com/anthropics/skills/...",
"fetched_at": "2026-04-23T10:00:00+0900",
"confidence": "high",
"reason": "MDX files mentioned in official README"
}
]
```
**`proposal_type` 取值（第一阶段）：** `add_glob` · `update_description` · `fix_path` · `update_utterance`
## I/O 契约
## 限制
- M1 仅检测**完全相同的字符串重复**——fnmatch 路径重叠属于第二阶段功能
- 第一阶段中不提供 `--apply`——需通过 `skill-creator` 手动应用提案
- `source_type` 分类基于路径启发式——未检测官方技能的伪装
## 路线图
### ✅ 第一阶段 (当前)
- 扫描 C1 / H0 / H1 / M1 / I1 问题并进行严重程度分类
- 生成 `SkillPatchProposal` JSON（4 种提案类型）
- 在 `skill-index.json` 不可用时的自动回退扫描
- `--session-review`：通过 JSONL 会话分析提供工作后的技能候选推荐
### 🔜 第一.五阶段 (下一个里程碑)
- 在 `skill-auto-loader.sh` 中加入加载事件日志，以便直接对比
- 使 `--session-review` 能够显示“实际已加载”与“本应加载”的对比
### 🔜 第二阶段 (计划中)
- 直接应用：自动将提案发送给 `skill-creator`
- 更好的冲突检测：针对 M1 的基于 fnmatch 的路径重叠检测
- 更智能的提案：带有来源新鲜度跟踪的置信度评分
- 官方技能的可信来源验证
- `--session-review` 基于话语的技能发现（语义分析）
## 许可证
MIT
用于 CI / 脚本编写
| | 定义 | |-|-----------| | **stdin** | 无 | | **stdout** | 文本报告；`--json` → JSON 数组 | | **stderr** | 执行错误消息 | | **exit 0** | `--scan`：无问题 / `--session-review`：始终返回（信息工具） | | **exit 1** | `--scan`：存在可处理的发现（适用于 CI 门控） | | **exit 2** | 执行失败——文件访问错误、解析错误等。 |标签：AI编程助手, Claude Code, Cutter, DLL 劫持, Glob模式, IDE插件, JSONL分析, JSON格式, MIT许可, SEO优化, WebSocket, 云安全监控, 人工智能, 代码审查, 依赖分析, 只读模式, 大语言模型, 威胁情报, 安全检查, 幽灵技能, 开发者工具, 技能诊断, 故障排查, 数据管道, 文件匹配, 时序数据库, 智能推荐, 死触发器, 用户模式Hook绕过, 系统诊断, 编程效率, 质量保证, 路径检测, 软件工程, 逆向工具, 静态分析