skills的介绍
Agent Skills 本质上是可复用的任务方法：一个 Skill 文件夹至少包含SKILL.md，还可以附 scripts、references、assets 等资源；它既可以纯靠说明完成任务，也可以调用代码、模板或工具。
什么任务需要做成skills
从需求的角度看，哪些事情值得做成 Skill。我觉得最典型的是：一类任务会反复出现，而且做好它需要遵循一套有经验含量的流程。
这里面，最有价值的是“任务经常发生，但执行质量容易波动”。比如同样让 AI 写爬虫，有时它会先分析接口，有时直接硬解析 HTML，有时写完就结束。Skill 就可以把你认可的判断顺序、实现要求和验收方式固定下来。
| 需求类型 | 为什么需要 Skill | 例子 |
|---|---|---|
| 重复处理同类任务 | 不想每次重新交代要求 | 每次读论文都按研究问题、方法、实验、可借鉴点分析 |
| 稳定遵循工作流程 | 避免 AI 漏步骤、跳过验证 | 爬虫先分析数据入口，再实现、验证、实测 |
| 落实专业标准 | 通用回答不足以满足领域要求 | 按期刊规范检查稿件、按团队标准审查代码 |
| 协调多个工具 | 要明确工具何时使用、结果怎样衔接 | 搜索论文 → 下载 PDF → 提取内容 → 核对引用 |
| 固定交付要求 | 产物需要能被后续流程直接使用 | 新闻采集统一输出字段、去重结果、来源与时间 |
| 复用个人或团队经验 | 把有效做法变成别人也能执行的步骤 | 故障排查顺序、面试复盘方法、客户需求分析流程 |
判断时可以问三句：以后还会不会做？有没有值得复用的方法？做好与做差有没有明确标准？三项都明显，就很适合做成 Skill；偶尔问个知识点、改一句话，直接对话通常就够了。
skill定义和目录结构
taiwan-entertainment-news-crawler/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── references/ │ ├── input-contract.md │ ├── source-analysis.md │ ├── output-schema.md │ ├── credibility-rules.md │ └── validation.md ├── scripts/ │ └── validate_output.py └── tests/ └── test_validate_output.py
整体调用关系
用户提出采集需求 │ ▼ SKILL.md：决定完整工作流程 │ ├── input-contract.md：确定输入参数 ├── source-analysis.md：分析数据入口 ├── output-schema.md：规定结果结构 ├── credibility-rules.md：标记消息来源状态 └── validation.md：规定如何验收 │ ▼ 生成一个独立的可运行爬虫项目 │ ▼ validate_output.py：检查最终 JSON │ ▼ test_validate_output.py：保证验证器本身正常
skill大概率就是这样，他没有侵入到具体项目代码去，几个发挥作用的md文档都只是和模型在对话
只是另外写了两个脚本： validate_output.py：检查最终 JSON；test_validate_output.py：保证验证器本身正常 来去检查最终结果而已；
作用
要我说啊，skill这东西最大的价值就是我能够去复用大佬们的工作经验、
这对公司开发人员来说有一个很好的搬运价值；过去我们借鉴大佬们的，更多是他们的源码项目；他们提出的一些架构；而skills的出现让我们得以学习他们的工作习惯。这是进一步的学习深入。
另外，我们都知道skills能够让prompts得到复用性，让工作流程得到一个一致性，而且具有可迭代行；这也是好处嘛。
我们要掌握的能力：
1、我们要时不时的去浏览各种skills广场，很多时候正式这种浏览，提高了我们的认知，你会知道别人的工作范式之于现在我们自身的学习方式是否更高效。
2、我们要学会自己写skills,这就要求我们要了解skills的特性；虽说最简单的skills无非是一个markdown文档，而且他的本质就是在其中交代对ai的指令，但它还是有一定的tricks在的；首先我们要明确自己的需求，然后在描述里面定义好 skill description,包括他是否需要被触发；另外其实不同功能的skills它的体量是不一样的；譬如调研型的skills.,数据处理性（需要脚本），代码生成型，我们需要视情况去创建更多的子文件夹来存放诸如脚本(scripts)，说明文档（references)，文件资产(resoures)等等; 其次，对于输入，输出的要求和格式；以及对于代码生成完成之后的审计和验证标准，我们都要定义好；
Skill 创建流程
1. 明确需求
什么任务重复发生？
什么经验值得固化？
哪些步骤容易出错？
从而，你不会为了“写一句邮件”创建 Skill，但每周生成销售分析报告值得；
2、定义触发条件
也就是description:，告诉agent什么时候想起我。这是 Skill 和普通 Prompt 最大区别之一。
3、设计输入输出
没有输入输出约束，Skill 很容易退化成聊天。
4、根据复杂度决定目录结构
5、增加验证
这个是很多 Prompt 用户不会考虑的。普通 Prompt：写完代码结束。
工程 Skill写完代码：我们不能只凭感觉判断。建议遵循“便宜检查优先、昂贵检查靠后”的原则，设置层层递进的质量门（Quality Gates）
置层层递进的质量门（Quality Gates）
| 层级 | 验收维度 | 核心检查项 |
|---|---|---|
| 1 | 产物完整性 | 文件是否齐全、目录结构是否正确、入口点是否存在。 |
| 2 | 结构合法性 | 代码能否被解析（AST），JSON/YAML/XML 格式是否合法。 |
| 3 | Schema 合规 | 字段、类型、枚举值、必填项是否符合定义（如 OpenAPI、DB Schema）。 |
| 4 | 静态质量 | 运行 Formatter、Linter、Typecheck，确保风格与语法无误。 |
| 5 | 构建验证 | 项目是否真正可编译或打包（如npm run build,mvn package）。 |
| 6 | 单元测试 | 核心函数逻辑是否正确，覆盖正常、空值、极值等场景。 |
| 7 | 集成测试 | 模块间协作是否正常（API、数据库、文件系统交互）。 |
| 8 | 运行时冒烟 | 软件能否启动并响应（如请求健康检查接口、运行 CLI）。 |
| 9 | 非功能质量 | 安全性（依赖审计）、性能基线、兼容性检查。 |
| 10 | 仓库卫生 | git diff检查，确保无临时文件、无密钥泄露、无误改其他文件。 |
| 11 | 输出验收 | 最终交付物是否严格满足用户的原始需求（格式、路径、内容） |
第二是流程验收;
必须验证其工作流是否可靠。我们需要从以下五个维度对 Skill 本身进行“图灵测试”：
1)触发准确性；
- 该出手时才出手：明确点名时能触发，需求匹配时能触发，但在相似但不适用的场景（如“修改样式”而非“创建项目”）下绝不能误触发。
- 抗噪能力：在带有真实上下文噪声时，仍能精准识别意图。、
2）环境识别能力
- 尊重现有资产：Skill 在动手前应“环顾四周”——识别语言框架、包管理器（别在有
pnpm-lock.yaml的项目里用npm）、现有的测试与构建命令。 - 遵守约束：阅读
AGENTS.md、README和贡献指南，不假定所有项目都是从零开始。、
3）过程遵循
- 言行一致：验证 Skill 是否真的执行了规定步骤，而不是在回答里撒谎说“已验证”。
- 权限克制：不擅自提升权限，不执行危险操作，不修改任务范围之外的模块。
4）失败处理机制
- 闭环思维：生成代码 → 快速验证 → 失败则定位修复 → 重新验证。
- 拒绝死循环：限制自动修复次数。
- 诚实报告：如果某项验证无法运行，必须明确告知用户“哪一项没跑、为什么、你可以手动执行什么命令”，严格区分“未验证”和“验证通过”。
5）幂等性与效率
- 拒绝重复劳动：重复运行同一 Skill 不应产生无意义的 Diff，不重复插入配置，不覆盖用户已有实现。
- 边界控制：不读取大量无关文件，不消耗不必要的 Token。
为了让上述理念落地，建议将以下Validation规范直接写入你的 Skill 定义中，作为 AI 执行任务时的“宪法”：
## Validation Protocol
完成代码修改后，必须严格执行以下步骤：
- 范围确认：确认修改范围仅包含任务必需的文件。
- 结构校验：对生成的 JSON、YAML 或结构化输出执行解析和 Schema 校验。
- 静态检查：运行仓库已有的格式化、Lint 和类型检查命令。
- 单元测试：运行与改动直接相关的单元测试用例。
- 冒烟测试：若改动影响构建或启动，必须执行构建及运行时冒烟测试。
- 卫生检查：检查
git diff，确保没有临时文件、密钥或无关修改。- 修复闭环：如果验证失败，进行最小化修复并重新运行受影响的检查。
- 诚实原则：不得把未运行的检查描述为“通过”。
- 最终报告：输出必须包含修改内容、实际运行的命令、每项结果、未运行项及原因、剩余风险。
