用途
这份资料是一份关于“如何以本项目的房屋风格撰写智能体技能（agent skill）”的写作规范。它明确说明：技能不是教程，也不是 API 参考，而是给下一个即将因同样问题浪费两天时间的人留下的便签。格式中的所有要素都由此推导而来。
结构要求
技能文件的结构为：frontmatter、一段简短的导引（orientation）、占据大部分篇幅的 Traps（陷阱）章节，最后是 Verifying it（验证）章节，整体约 60–140 行。导引的唯一作用是让陷阱部分可读；如果开头三分之一都能在框架自带文档里读到，就应当停止。
description 承担两项职责：说明何时加载该技能，以及读者正面对的症状，使匹配基于错误而非主题。资料给出的示例说明，description 结尾类似“……或遇到 ImageVector/Painter 类型错误”的子句，才是读者困惑时真正触发的部分。
核心写作原则
- 教读者如何验证某个取值，而不要罗列会过时的取值列表。示例做法是引导读者去上游的码点列表，而不是直接列名字——列表会过时，流程不会。
- Traps 章节是产品的核心。每条陷阱先以加粗写出错误做法，再说明会发生什么，最后说明应改做什么，使快速扫读加粗行的读者能找到自己的处境。
- 不要从记忆写计数（如“共有 59 个图标”），而应给出产生该计数的命令。
- 摘录若被改名应标注
// adapted，逐字摘录则不要误标为“改编”，否则读者会去 grep 实际并不存在的原文。 - 不要以注释作为论断来源；注释只记录当时的认知，应回到工件本身确认。
- 不要写出未经重新推导的理由；“因为 X 所以失败”这类凭合理性写出的说法最易存活，因为读起来和核实过的一模一样。
- 引用 glob 时务必加引号：
grep -r *.kt会被 shell 提前展开，find . -name *.kt同样失败。 - 验证章节不能是散文式的“检查配置是否正确”，每一步都应是带明确通过条件的命令，或工件加预期内容。
评审中发现的错误类型
资料总结四轮已关闭的评审批次中，对抗性评审每次发现不同性质的错误，也大致是自稿失败的顺序：内容错误（源仓库不支持该论断，通过打开技能所引用的文件可发现）；文字与工件不符（论断来自注释或变更日志，而旁边代码已变化，需从工件重新推导）；无法运行的验证命令（看似合理却从未执行，如参数顺序错误、被 shell 吞掉的 glob、静默匹配不到任何内容的锚定模式）；机制未重新推导（陷阱真实但所述原因是猜测，需对每条理由追问“你怎么知道是这个原因”）。其中第三轮最易预防：发布前把 Verifying 章节中的每条命令原样对真实仓库运行一遍——从未运行过的命令只是论断，不是检查。
使用方式与验证命令
资料提供了一组可在技能集合根目录执行的验证命令示例：
检查 frontmatter 的 name 与文件夹名是否一致（通过条件：无输出）：
for f in skills/*/SKILL.md; do
n=$(awk -F': ' '/^name: /{print $2; exit}' "$f")
d=$(basename "$(dirname "$f")")
[ "$n" = "$d" ] || echo "MISMATCH folder=$d name=$n"
done
检查 description 是否含触发子句（通过条件：打开每个被打印的文件）：
awk '/^description:/ && !/[Uu]se when/ && !/[Rr]each for (it|this) when/ {print FILENAME}' \
skills/*/SKILL.md
检查行数是否在 60–140 区间：
wc -l skills/*/SKILL.md | sort -n | awk '$1<60 || ($1>140 && $2!="total")'
报告 Traps 章节占比：
for f in skills/*/SKILL.md; do
t=$(wc -l < "$f")
s=$(grep -n '^## Traps' "$f" | cut -d: -f1)
[ -n "$s" ] && printf '%3d%% %s\n' $(( (t - s) * 100 / t )) "$f"
done | sort -n | head -20
检查是否缺少规范验证标题：
grep -L '^## Verifying it' skills/*/SKILL.md
提取所有围栏 bash 命令自行运行：
awk '/^[[:space:]]*```bash/{f=1;next} /^[[:space:]]*```/{f=0} f' skills/*/SKILL.md | sed '/^\s*$/d'
确认交叉引用的技能在磁盘上存在：
grep -ho '`[a-z0-9]\+\(-[a-z0-9]\+\)\{1,\}`' skills/*/SKILL.md | tr -d '`' | sort -u \
| while read -r n; do [ -d "skills/$n" ] || echo "MISSING $n"; done
其中最后一条并非要求零输出：该模式也会捕获带连字符的非技能词元，通过条件是每一行输出都明显不是技能名；若出现真实技能名，则说明引用已损坏。
适用场景与限制
适用于为智能体撰写或评审技能文档的作者，尤其是需要技能在被对抗性评审后仍能站得住脚的场景。资料仅覆盖写作规范与验证方法，未说明具体的智能体运行时、平台支持范围、收费或效果数据，这些暂未提供。