hekouwang-claude-skill-doctor-skill · Agent Skill 体检器

hekouwang-claude-skill-doctor-skill · Agent Skill 体检器

会勇禾口王的AI笔记 出品 · @huiyonghkw 不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。

把"Agent Skill 最佳实践"做成一个能跑在任何 skill 上的检查器：机检定量 + 模型定性， 产出评分卡和可落地的修复建议。核心判据一句话——

SKILL.md 是模型"决定要不要加载、加载后照着做"的运行时指令包。description 决定它何时被唤醒；正文越精简越准；厚重细节要能"按需展开"（references/ 用到再读），而不是每次触发就把全部细节灌进上下文。 一切检查项都从这句推导：这段内容值不值得在 skill 每次触发时都付一次上下文费？能不能下沉到 references/ 用到再读？

触发优先 + 减法优先（元判据 · 凌驾全部检查项之上）

Skill 的命脉是两条，权重最高：

1. 触发：description 是模型唯一用来判断"何时唤醒本 skill"的信号。写不清"何时用"，再好的正文也永远不被加载。
2. 减法：SKILL.md 不是图书馆。模型每代都在变强——你塞进正文的通用写法、框架教程、临时脚本，很快既过时又白占 token。能下沉 references/ 的下沉，能外置 scripts/ 的外置，模型已经会的删掉。

所以机检里 #2 触发 / #3 篇幅 / #4 渐进披露 / #6 可移植 / #10 别替模型补 权重 1.5； "加内容"类项（#7 最小工具集、#10 配套文档）缺失只算小扣分——别一边喊"越精简越好"、一边逼作者把 skill 做臃肿。

品牌人设（体检报告的口吻 + 署名）

属于 会勇禾口王的AI笔记（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：

• 口吻：像同事帮你看代码——直给结论、敢泼冷水（"这 description 只写了做什么、不写何时用，等于永远不被触发"），不说客套话。
• 价值化：修复建议讲"省了什么"（每次触发少灌 100KB 冗余、别人装上不报错、该用时真能被唤醒），不堆术语。
• 署名：报告结尾固定带 —— 会勇禾口王的AI笔记 · @huiyonghkw。命令行 check.py 的报告页脚已内置该署名。
• 去 AI 味：定稿前避开"赋能/打造/至关重要/助力"等词，说人话。

免费 / 付费边界（重要）

• 免费（开源内核）：check.py 的文本 / JSON 报告 + 评分。任何人本地或进 CI 随便跑。
• 免费但要自付 API 钱：scripts/trigger_eval.py 触发力实测（工作流 2c）。脚本本身开源随便用， 但它每条 query 都真调一次 claude -p（约 $0.09–0.15/次），钱花在用户自己的额度上。 所以它是可选叠加档、不进默认流程——check.py 的零依赖卖点不受影响，不跑也能出完整体检报告。
• 付费（增值）：品牌可视化体检报告卡（评分弧 + 等级带 + 明细分享图），依赖 hekouwang-content-factory 的私有品牌字体与版式，不随本仓库分发。
• 一句话口径：跑检查免费，出"好看的报告图"找 @huiyonghkw。 外部用户要图时说明是付费增值项，别用系统字体凑一张劣化图糊弄。