Agent Skills 最佳实践

你在写什么、为什么容易翻车

Agent Skill 不是「把提示词塞进文件夹」：上下文要按触发时机分层加载，命名和目录要对齐开放标准，否则要么占满 token、要么根本不会被选中，还会在 ClawHub 一类流水线里被 官方 validate spec 直接拒掉。很多人还会在 frontmatter 里混用 Claude Code 专有字段，本地能跑、发布却过不了校验。

这份技能怎么组织知识

技能把 Anthropic 侧的最佳实践收成可执行的编写手册，核心围绕 渐进披露（Progressive Disclosure） 三层：启动只加载元数据（约百级 token）、触发后再读 SKILL.md 正文、细节放到 references/ 且引用链保持 一层深度，大文件还要 TOC 并拆分子主题。

正文还覆盖：

• 命名：kebab-case、与目录同名、优先动名词形式，避开 helper/utils 等泛化词
• 指令写法：少选项、明确自由度（高/中/低）、关键规则置顶
• 脚本：显式处理错误、常量有据、区分「执行」与「当文档读」
• 测试：先写 evaluation、对照无技能基线，再补最少说明；用「何时会用本技能」调试触发
• 校验与排障：对照症状表（描述过宽/过窄、文件过大、SKILL.md 大小写等）
• 分发与 API：各 surface 路径不同、API 侧技能上限与无网络/无运行时装包等约束

适用边界

这是 编写与治理 参考，不替你实现具体业务技能。文中提到的 ClawHub、metadata.openclaw、MCP/子代理等进阶模式在附加 reference 里展开；若你只做 Claude.ai 上传 zip，仍需单独核对目标环境的 frontmatter 白名单。