AGENT SKILL OPS MANUAL | 飞行操作手册

SEC-01

Skill 的文件夹结构

每个 Skill 都必须遵循这样的目录结构：

📁 skill-name/ # Skill 文件夹名称

├── 📄 SKILL.md # 必需：元数据 + 核心指令（少于 500 行）

├── 📂 scripts/ # 可执行代码（Python/Bash），设计为小型 CLI 工具

├── 📂 references/ # 参考资料（API 文档、速查表等）

└── 📂 assets/ # 模板或静态文件，用于输出

01 SKILL.md：这是 Skill 的"大脑"，负责导航和高层流程控制。
02 References：从 SKILL.md 直接引用，只放一层子目录。
03 Scripts：用于处理容易出错或重复的操作，减少变数。不要把库代码放在这里。

SEC-02

优化元数据，让 Skill 更容易被发现

SKILL.md 文件开头的 name 和 description 是 Agent 在决定是否调用某个 Skill 之前唯一能看到的两个字段。如果这两个字段写得不够清晰、不够具体，你的 Skill 就等于"隐身"了。

严格遵守命名规则

name 字段必须是 1-64 个字符，只能包含小写字母、数字和连字符（不能连续出现连字符），并且必须和父文件夹名称完全一致（例如：name: angular-testing 必须放在 angular-testing/SKILL.md 文件中）。

写触发优化的描述

（最多 1024 个字符）。这是 Agent 路由决策时唯一看到的元数据。用第三人称描述功能，并包含"负面触发词"。

⚠ 不好的例子

"React 技能。"（太模糊）

✓ 好的例子

"使用 Tailwind CSS 创建和构建 React 组件。当用户想要更新组件样式或 UI 逻辑时使用。不要用于 Vue、Svelte 或纯 CSS 项目。"

SEC-03

渐进式披露与资源管理

保持上下文窗口整洁，只在需要时才加载信息。SKILL.md 是高层逻辑的"大脑"；把细节内容放到子目录中。

01 保持 SKILL.md 精简：主文件限制在 500 行以内。用它来做导航和主要流程控制。
02
使用扁平化子目录：把大块内容移到标准文件夹。文件只放一层深度（例如：references/schema.md，而不是 references/db/v1/schema.md）。
- references/：API 文档、速查表、领域逻辑。
- scripts/：用于确定性任务的可执行代码。
- assets/：输出模板、JSON 模式、图片。
03 即时加载（JiT）：明确告诉 Agent 什么时候读取文件。在你指示之前，它看不到这些资源（例如："查看 references/auth-flow.md 了解具体的错误代码"）。
04 显式路径：始终使用相对路径，用正斜杠（/），不管操作系统是什么。

⚠ 注意事项

Skill 是为 Agent 设计的，不是为人类设计的。为了保持上下文窗口精简，避免不必要的 Token 消耗，不要创建：

文档文件：README.md、CHANGELOG.md 或 INSTALLATION_GUIDE.md。
冗余逻辑：如果 Agent 不需要帮助就能可靠地处理某个任务，就删掉相关指令。
库代码：Skill 应该引用现有工具，或包含小型、单一用途的脚本。长期维护的库代码应该放在标准仓库的 CLI 目录中。

SEC-04

使用具体的程序指令，而不是散文

为 LLM 创建指令，而不是为人类。

使用分步骤编号

把工作流程定义为严格的时间顺序。如果有决策树，清晰地画出来（例如："第 2 步：如果需要源码映射（source map），运行 ng build --source-map。否则，跳到第 3 步。"）。

提供具体模板

Agent 的模式匹配能力非常强。与其花大段文字描述 JSON 输出应该长什么样，不如把模板放在 assets/ 文件夹里，然后告诉 Agent 复制它的结构。

用第三人称命令式写作

把指令框定为对 Agent 的直接命令（例如："提取文本..." 而不是 "我将提取..." 或 "你应该提取..."）。

使用一致的术语

在 Skill 文件中引用概念时要具体且一致。

使用一致的术语：选择一个单一术语来指代特定概念。
具体性：使用你描述的领域中最具体的术语。例如，在 Angular 中使用"模板"（template）这个概念，而不是"html"、"markup"或"view"。

SEC-05

为重复操作打包确定性脚本

不要让 LLM 每次都从零开始写复杂的解析逻辑或样板代码。

01 把脆弱/重复的任务外包出去：如果 Agent 需要解析复杂数据集或查询特定数据库，给它一个测试过的 Python、Bash 或 Node 脚本，放在 scripts/ 目录里运行。
02 优雅地处理边缘情况：Agent 依靠标准输出（stdout）和标准错误（stderr）来判断脚本是否成功。编写返回高度描述性、人类可读错误消息的脚本，这样 Agent 就知道如何自我纠正，而不需要用户干预。

SEC-06

验证指南

既然 LLM 会使用你的 Skill，确保它们有用的最好方法就是和 LLM 一起协作验证。

为你的 Skill 准备评估（evals）非常重要，以确保你做的改动有积极影响，不会导致功能倒退。一个流行的 Skill 基准测试是 SkillsBench，可以给你一些灵感。

一旦你完成了 Skill 的初稿，可以通过以下步骤来验证你的工作：

发现性验证

Agent 严格根据 YAML 元数据来加载 Skill。测试 LLM 如何单独解读你的描述，以防止误触发（比如明明是用于 Angular 的 Skill，却在 React 项目上被触发）。

把下面这段文字原封不动地粘贴到一个新的 LLM 对话中：

📋 LLM 验证提示模板

我正在基于 agentskills.io 规范构建一个 Agent Skill。Agent 将完全根据下面的 YAML 元数据来决定是否加载这个 Skill。

name: angular-vite-migrator

                                    description: 将 Angular CLI 项目从 Webpack 迁移到 Vite 和 esbuild。当用户想要更新构建器配置、用 rollup 等效插件替换 webpack 插件，或加速 Angular 编译时使用。

严格基于这个描述：
1. 生成 3 个你 100% 确定应该触发这个 Skill 的真实用户提示。
2. 生成 3 个听起来相似但不应该触发这个 Skill 的用户提示（例如，把 React 应用迁移到 Vite，或只是更新 Angular 版本）。
3. 评价这个描述：它太宽泛了吗？建议一个优化后的重写版本。

此外，用你期望触发 Skill 的任务提示 Agent，并检查它的思考过程。和 Agent 来回对话，找出它选择（或不选择）特定 Skill 的原因。

逻辑验证

确保你的分步指令是确定性的，不会强迫 Agent 去"编造"（hallucinate）缺失的步骤。

把你的整个 SKILL.md 和目录结构喂给 LLM：

📋 逻辑验证提示模板

这是我的 SKILL.md 完整草稿及其支持文件的目录树。


                                    ├── SKILL.md

                                    ├── scripts/esbuild-optimizer.mjs

                                    └── assets/vite.config.template.ts

[在这里粘贴你的 SKILL.md 内容]

扮演一个刚刚触发这个 Skill 的自主 Agent。基于"把我的 Angular v17 应用迁移到 Vite"这个请求，模拟你的逐步执行过程。

对于每一步，写出你的内心独白：
1. 你具体在做什么？
2. 你在读取或运行哪个具体的文件/脚本？
3. 标记任何执行障碍：指出你被迫猜测或编造的准确位置，因为我的指令含糊不清（例如，如何把 Angular 环境文件映射到 Vite 的 import.meta.env）。

边缘情况测试

强迫 LLM 去寻找漏洞、不支持的配置，以及 Web 工具固有的失败状态。

让 LLM 攻击你的逻辑：

📋 边缘情况测试提示模板

现在，切换角色。扮演一个无情的 QA 测试员。你的目标是打破这个 Skill。
问我 3 到 5 个关于 SKILL.md 中边缘情况、失败状态或缺失回退机制的高度具体、具有挑战性的问题。重点关注：

• 如果 scripts/esbuild-optimizer.mjs 因为遗留的 CommonJS 依赖而失败怎么办？
• 如果用户的 angular.json 包含 Vite 不支持的深度定制 Webpack 构建器（@angular-builders/custom-webpack）怎么办？
• 我对用户的 Node 环境做了什么隐含的假设？

现在还不要修复这些问题。只问我编号的问题，然后等我来回答。

架构优化

LLM 经常试图把大型配置文件直接塞进主提示。用这一步来强制执行渐进式披露，缩小 Token 占用。

让 LLM 应用你的修复并重组 Skill：

📋 架构优化提示模板

基于我对边缘情况问题的回答，重写 SKILL.md 文件，严格执行渐进式披露设计模式：

1. 保持主 SKILL.md 严格作为高层步骤集，使用第三人称命令式（例如，执行 esbuild 脚本，读取 Vite 配置模板）。
2. 如果文件中有密集的规则、大型 vite.config.ts 模板，或复杂的 angular.json 模式，把它们移除。告诉我创建一个新文件在 references/ 或 assets/ 中，并用一个严格的命令替换 SKILL.md 中的文本，只在需要时读取那个特定文件。
3. 在底部添加一个专门的错误处理部分，整合我关于 Webpack 回退和 CommonJS 解析的答案。

打造 Agent Skill 的最佳实践指南