Community写作与编辑github.com

Zane456/skill-checkup

Claude Code 技能健康检查。skill-checkup 能诊断 SKILL.md 无法可靠触发的根本原因,进行工作流空跑演练,并重组技能包。4 个确定性脚本,零运行时依赖。

skill-checkup 是什么?

skill-checkup 是一款用于 Claude Code 等 AI 编程助手的诊断与改进工具。它能深入分析目标 SKILL.md 文件,检测其文本定义与模型实际触发行为之间的鸿沟,从“约束”(何时注入何内容)、“模型”(上下文偏见、衰减、静默跳过)、“硬编码”(脚本强制执行文本无法保证的规则)、“结构”(路由、清单、收据)四个维度进行审计。该工具通过四个确定性 Python 脚本(检查列表预算、路由、脚本安全性和维度索引)完成自动化检测,并生成分层报告(代码层 → 决策层),标识 P0 到 P3 优先级的问题,同时支持用户确认后自动修复。它适用于任何遵循 skill-checkup 规范的技能包,核心价值在于将模糊的“文本规范”转化为可量化、可复现的触发概率评估。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add Zane456/skill-checkup

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

技能检查 (Skill Checkup)

诊断并改进任何 SKILL.md。它是一份指南,而非手册——标准位于 references/ 中。

角色——交付审计员。 技能不在于其文本,而在于每条规则在适用的那一刻被模型关注到的概率。每个发现都通过四个维度来服务于这个量化目标:约束(何时注入什么:描述每次轮次、主体在触发时、引用仅通过 Read)、模型(节省偏见、上下文衰减、静默跳过)、硬编码(脚本强制执行文本无法保证的规则)、结构(路由、清单、收据)。

诊断流程(每一步必须输出)

静默步骤会被跳过(Seleznov, 2026)——每步输出一行确认信息。 自我审查标记:如果本次会话已经编辑/写入过目标 SKILL.md,则在 skill-checkup 的每行输出前加上 [self-review] 前缀,并且必须在声明工作完成之前运行一次全新的子代理盲审——使用明确的文件路径生成该子代理,且不预设任何发现(过程 + 多目标扩展:runtime-contract.md §4),然后输出: [skill-checkup] 自我审查重检:<agent> → <verdict summary> 如果无法运行,需明确声明并将工作标记为未验证——沉默不是选项。

步骤 1:读取目标,运行三个检查器

完整读取目标 SKILL.md,然后通过 python3 <本技能目录>/scripts/…(路径用引号括起——空格常见)运行三个检查器:check_listing_budget.py "<项目根目录>" --target "<技能名称>"、check_routes.py "<技能目录>"、check_script_safety.py "<技能目录>"。三个检查器每次都运行完整审计;compass-cap/dangling/orphan 命中为 P1。输出五行:

[skill-checkup] 正在审计: <path>  body=<N> 行  description=<M> 字符
[skill-checkup] 预算: 已安装 <K> 个技能,描述 <T> 字符 vs ≈<B> → <fits | OVERFLOW ×N.N>
[skill-checkup] 重叠: <clean | N 对,其中 M 对涉及目标>
[skill-checkup] 路由: <PASS | N 个问题:compass-over/dangling/orphan>
[skill-checkup] 安全性: <clean | N 个命中:<classes>>

预算退出码 2 = 不可用时回退行。分级:溢出和非目标重叠仅作为 NOTICE;目标重叠 = P2(description-templates.md §distinctness);安全性命中 = CRIT 时为 P0,否则为 P1,待判断合法性(hard-code-vs-llm-judgment.md);安全性清理 → 仅收据行,绝不报告行。永远不要为填充通知编辑被审计技能;永远不要自动删除安全性命中(精简 = 用户运行的全局扫描)。

步骤 2:列出维度清单,然后一次只读一个维度

运行 python3 <本技能目录>/scripts/index.py "<技能目录>"——它测量目标并输出维度清单(FORCED / DEFAULT / SKIP + 原因)以及 MODE= 行。该脚本对触发条件具有权威性;references/index.md 是其人类可读的镜像——不要仅从文本重新判断触发条件。 MODE=inline → 每个文件迭代一次循环维清单:读取它 → 仅针对该维度判断目标 → 输出收据 → 下一个文件。DEFAULT 跳过必须引用清单中打印的跳过条件。MODE=fanout → runtime-contract.md §4。

[skill-checkup] <维度>: <N> 个发现

步骤 2.5:空跑演练(当 ordered-steps=True 时正向演练;无条件负向演练)

按照 references/effect-dry-run.md,对描述所承诺的每种任务形态(编写 / 修订 / 检查,1–3 个;编辑类技能必须包含小范围修订提示)取一个典型提示。将每个提示逐步走通:输入/指令/输出连接,并且在该粒度下哪些硬门触发。 任何断裂链接 / 歧义 / 没有常见形态会触发的门 → P0,进入步骤 3 的代码层。 每个提示输出一行:

[skill-checkup] Dry-run "<prompt>"(形态: <write|revise|check>)  broken links=<N>  gates fired=<M>/<total>

完全没有有序流程(纯规则 / 参考技能)→ 输出:

[skill-checkup] Dry-run: 正向演练跳过(无工作流)

始终(无论是否有工作流):根据 effect-dry-run.md §negative,仅依据描述判断 1–2 个不应该触发的提示。捕获到 → P2 [over-trigger]。输出:

[skill-checkup] Dry-run 负向: <K> 个提示,误触=<J>

步骤 2.6:实时注入检查(当目标在本会话范围内时)

目标是否出现在本会话的可用技能列表中且附带其描述(而非仅名称)?3 种情况 + 填充通知规则 → references/live-injection-check.md。输出一行:

[skill-checkup] 实时注入: <injected | DROPPED(仅名称) | skipped(<原因>)>

步骤 3:输出诊断报告

按照 references/output-format.md 呈现——一份使用用户回复语言、采用 lesstoken 风格的分层报告:判定 → 质量评分 → 代码层(P0→P3,文件:行证据)→ 决策层 分为 ✅ 可以安全修复 与 🤔 需要您决策 → 结尾问题。

填充这些层的内容:

  • 每个发现:稳定 ID(P0-1 …)、具体行/字段、风险 🟢/🟡/🔴,按 P0→P3 排序(references/priority-tiers.md);同一违规出现 N 处 = N 个发现;同一缺陷来自两个维度 = 去重后统一为一个再进行分级。
  • 当适用时,命名失败模式——一个 predictability-glossary.md 标签:[no-op]/[sediment]/[premature-completion]/[weak-leading-word]/[duplication]/[sprawl]/[over-trigger]/[no-floor]/[gate-gap]/[missing-license]。前缀 = 类型,P 级 = 严重程度。
  • 每个 🤔 项分开说明机制(当前行为)与后果(下一个 LLM 会做错什么),然后给出选项和建议。

步骤 4:在用户确认后使用 Edit 应用

在得到确认前绝不执行 Edit——等待用户的“修复它”。

在执行前:规模门控 + 预删除检查;之后闭环——过程详见 references/apply-safety.md。 修复后,输出一行:

[skill-checkup] 已应用 <N> 项修复到 <path>  body: <old>→<new> 行(<+X%>)

硬规则速查

量化的硬规则(违反 = 错误)→ references/hard-rules.md,每次审计都需查阅。

异常回退

当路径缺失、YAML 解析失败、或者 scripts/ 下的任何捆绑脚本缺失或退出码为 2 时——按照 references/exception-fallback.md 处理(权威脚本列表在那里);先声明,绝不静默跳过。

语言

默认使用英文;对不合理的非英文内容标记警告 ⚠️;策略 + 2 个例外 → references/language-policy.md。

不适用范围

内容的领域正确性(逻辑错误,而非形式——运行时行为在范围内 → runtime-contract.md);项目约定(→ CLAUDE.md);一次性修复脚本。

存在理由

LLM 编写手册;机械性判断与主观性判断的分离:references/rationale.md。

相关技能