zxbdzh 技能创建器
本技能用于指导如何创建高质量技能。
关于技能
技能是模块化、可自包含的包，它通过提供专门知识、工作流和工具来扩展 agent 的能力。可以把它理解成特定领域或任务的“上手指南”。
它能把 agent 从通用代理，转变为拥有程序性知识的专用代理，而这些知识并不是任何模型都能完整掌握的。
技能提供什么
- 专门工作流 - 面向特定领域的多步骤流程
- 工具集成 - 针对特定文件格式或 API 的操作说明
- 领域知识 - 公司特有知识、模式定义、业务逻辑
- 打包资源 - 用于复杂和重复任务的脚本、参考资料与素材
核心原则
简洁优先
上下文窗口是公共资源。技能需要与 agent 还要使用的其他内容共享上下文窗口，包括系统提示、对话历史、其他技能的元数据以及用户的真实请求。
默认前提：agent 已经足够聪明。 只补充 agent 原本不知道的上下文。对每一段信息都要追问：“agent 真的需要这段解释吗？”以及“这段话是否值得它消耗的 token 成本？”
优先使用简洁示例，而不是冗长说明。
设定合适的自由度
技能说明的具体程度，应与任务的脆弱性和变化性相匹配：
高自由度（文本说明）：适用于存在多种可行方案、需要结合上下文决策、或主要依赖启发式方法的场景。
中等自由度（伪代码或带参数脚本）：适用于已有推荐模式、允许一定变化、或行为会受配置影响的场景。
低自由度（固定脚本、少量参数）：适用于操作脆弱且容易出错、必须保持一致性、或必须严格遵循特定顺序的场景。
可以把 agent 想象成在探索一条路径：如果是两侧都是悬崖的窄桥，就需要清晰护栏（低自由度）；如果是开阔平地，就允许多种路线（高自由度）。
技能的结构
每个技能都由一个必需的 SKILL.md 文件，以及可选的打包资源组成：
skill-name/
├── SKILL.md（必需）
│ ├── YAML frontmatter 元数据（必需）
│ │ ├── name:（必需）
│ │ └── description:（必需）
│ └── Markdown 说明（必需）
└── 打包资源（可选）
├── scripts/ - 可执行代码（Python/Bash 等）
├── references/ - 按需加载进上下文的文档
└── assets/ - 输出时会用到的文件（模板、图标、字体等）
SKILL.md（必需）
每个 SKILL.md 由以下两部分组成：
- Frontmatter（YAML）：包含
name和description字段。agent 只会读取这两个字段来判断技能何时触发，因此必须清晰且完整地描述这个技能是什么，以及应在什么场景下使用。 - 正文（Markdown）：技能触发后才会加载的使用说明与指导。
打包资源（可选）
脚本（scripts/）
用于执行需要确定性可靠性、或经常被重复改写任务的可执行代码（Python/Bash 等）。
- 适用时机：同一段代码会被反复重写，或任务需要确定性可靠性
- 示例：用于 PDF 旋转的
scripts/rotate_pdf.py - 优势：节省 token、行为确定，而且可以在不加载进上下文的情况下直接执行
- 注意：agent 仍可能需要读取脚本内容，以便打补丁或适配具体环境
参考资料（references/）
按需加载到上下文中的文档和参考材料，用于帮助 agent 完成推理和执行。
- 适用时机：存在 agent 在工作过程中应查阅的文档
- 示例：
references/finance.md（财务模式说明）、references/mnda.md（公司 NDA 模板）、references/policies.md（公司政策）、references/api_docs.md（API 规范） - 用途：数据库模式、API 文档、领域知识、公司政策、详细工作流指南
- 优势：让
SKILL.md保持精简，只在 agent 判断有需要时才加载 - 最佳实践：如果文件很大（超过 10k 词），请在
SKILL.md中提供 grep 搜索模式 - 避免重复：同一信息应只存在于
SKILL.md或references文件之一，不要两边重复。除非信息确实是技能的核心内容，否则优先放在references中，这样既能保持SKILL.md精简，也能在不占满上下文窗口的前提下让信息可发现。SKILL.md只保留必要的流程说明和工作流指导；详细参考材料、模式定义和示例应移动到参考文件。
资源文件（assets/）
这类文件不是用来加载进上下文的，而是让 agent 在生成最终输出时直接使用。
- 适用时机：技能需要在最终产出中使用某些文件
- 示例：
assets/logo.png（品牌资源）、assets/slides.pptx（PowerPoint 模板）、assets/frontend-template/（HTML/React 样板）、assets/font.ttf（字体） - 用途：模板、图片、图标、样板代码、字体、可复制或可修改的示例文档
- 优势：将输出资源与说明文档分离，让 agent 可以使用这些文件而无需把它们加载进上下文
不要在技能里放什么
技能应只包含直接支撑其功能的必要文件。不要创建多余文档或辅助文件，包括但不限于：
README.mdINSTALLATION_GUIDE.mdQUICK_REFERENCE.mdCHANGELOG.md- 等等
技能应只保留 AI 代理完成任务所需的信息。不应包含技能制作过程说明、安装与测试步骤、面向用户的额外文档等辅助背景。额外文档只会增加杂乱度并造成理解负担。
渐进式披露设计原则
技能通过三级加载系统来高效管理上下文：
- 元数据（name + description） - 始终在上下文中（约 100 词）
SKILL.md正文 - 技能触发时加载（少于 5k 词）- 打包资源 - 按需由 agent 加载（理论上不限，因为脚本可以不读入上下文而直接执行）
渐进式披露模式
应让 SKILL.md 只保留必要内容，并控制在 500 行以内，避免上下文膨胀。接近这个限制时，应把内容拆到其他文件中。拆分后一定要在 SKILL.md 里明确引用这些文件，并说明何时应读取它们，这样技能的使用者才能知道这些资源存在且知道何时使用。
关键原则： 如果一个技能支持多种变体、框架或选项，那么 SKILL.md 里只保留核心工作流和选择指导；变体相关的细节（模式、示例、配置）应放到独立参考文件中。
模式 1：带参考资料的高层指南
# PDF 处理
## 快速开始
使用 pdfplumber 提取文本：
[代码示例]
## 高级功能
- **表单填写**：完整指南见 [FORMS.md](FORMS.md)
- **API 参考**：完整方法列表见 [REFERENCE.md](REFERENCE.md)
- **示例**：常见模式见 [EXAMPLES.md](EXAMPLES.md)
只有在需要时，agent 才会去加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。
模式 2：按领域组织
当一个技能覆盖多个领域时，应按领域组织内容，以免加载无关上下文：
bigquery-skill/
├── SKILL.md（总览和导航）
└── reference/
├── finance.md（收入、计费指标）
├── sales.md（机会、销售漏斗）
├── product.md（API 用法、功能）
└── marketing.md（活动、归因）
当用户询问销售指标时，agent 只需读取 sales.md。
同样地，如果技能支持多个框架或变体，也应按变体组织：
cloud-deploy/
├── SKILL.md（工作流 + 提供商选择）
└── references/
├── aws.md（AWS 部署模式）
├── gcp.md（GCP 部署模式）
└── azure.md（Azure 部署模式）
当用户选择 AWS 时，agent 只需读取 aws.md。
模式 3：条件化细节
先展示基础内容，再链接高级内容：
# DOCX 处理
## 创建文档
新建文档时使用 docx-js。参见 [DOCX-JS.md](DOCX-JS.md)。
## 编辑文档
简单编辑可直接修改 XML。
**如需修订模式**：参见 [REDLINING.md](REDLINING.md)
**如需 OOXML 细节**：参见 [OOXML.md](OOXML.md)
只有当用户真的需要这些能力时，agent 才去读取 REDLINING.md 或 OOXML.md。
重要指导：
- 避免层层嵌套引用 - 让引用文件与
SKILL.md保持一层关系，所有参考文件都应直接从SKILL.md链接到 - 为较长参考文件补目录 - 对超过 100 行的文件，在顶部加目录，方便 agent 预览时迅速理解内容范围
技能创建流程
创建技能通常包含以下步骤：
- 通过具体示例理解技能
- 规划可复用的技能内容（脚本、参考资料、素材）
- 初始化技能（运行
init_skill.py） - 编辑技能（实现资源并编写
SKILL.md） - 打包技能（运行
package_skill.py） - 基于真实使用情况迭代
应按顺序执行这些步骤，除非有明确理由说明某一步不适用。
技能命名
- 只使用小写字母、数字和连字符；将用户给出的标题规范化为连字符格式，例如
Plan Mode->plan-mode - 生成的技能名长度应小于 64 个字符（仅计字母、数字和连字符）
- 优先使用简短、动词导向、能描述动作的短语
- 当按工具命名空间能提高清晰度或触发效果时，可按工具命名，例如
gh-address-comments、linear-address-issue - 技能目录名必须与技能名完全一致
第 1 步：通过具体示例理解技能
只有当技能的使用模式已经非常清晰时，才可以跳过此步骤。即便你是在修改已有技能，这一步通常依然有价值。
要创建高质量技能，必须清楚了解技能会如何被实际使用。这种理解可以来自用户直接给出的示例，也可以来自你生成后再由用户确认的示例。
例如，在构建图像编辑技能时，可以问：
- “这个 image-editor skill 需要支持哪些功能？编辑、旋转，还有别的吗？”
- “你能举几个它的使用例子吗？”
- “我能想到一些用户请求，比如‘帮我去掉这张图的红眼’或‘把这张图旋转一下’，还有别的常见说法吗？”
- “用户会说什么来触发这个技能？”
为避免一次性提太多问题而压垮用户，应先问最重要的问题，再按需要继续追问。
当你已经清楚技能应支持哪些功能时，这一步就可以结束。
第 2 步：规划可复用的技能内容
要把具体示例转化为高质量技能，请针对每个示例做以下分析：
- 思考如果从零开始，应该如何完成这个示例
- 找出在重复执行这些工作流时，哪些脚本、参考资料和素材会有帮助
例如：构建一个 pdf-editor 技能来处理“帮我旋转这个 PDF”这类请求时，分析结果可能是：
- 旋转 PDF 需要每次都重写同样的代码
- 把这段逻辑沉淀成
scripts/rotate_pdf.py会更有帮助
例如：设计一个 frontend-webapp-builder 技能来处理“帮我做一个待办应用”或“帮我做一个记录步数的仪表盘”时，分析结果可能是：
- 构建前端应用每次都需要重复写 HTML/React 样板
- 在
assets/hello-world/中保存一套样板工程会更有帮助
例如：构建一个 big-query 技能来处理“今天有多少用户登录过？”这类请求时，分析结果可能是：
- 每次查询 BigQuery 都要重新摸清表结构和关系
- 在
references/schema.md中记录这些表结构会更有帮助
要确定技能内容，应对每个具体示例做分析，并整理出应纳入技能的可复用资源清单：脚本、参考资料和素材。
第 3 步：初始化技能
到这里，就该真正开始创建技能了。
只有在你要开发的技能已经存在，而且当前只是要迭代或打包时，才跳过这一步；此时直接进入下一步即可。
当你从零创建一个新技能时，始终要运行 init_skill.py。这个脚本会自动生成一个模板技能目录，把技能必需的基础结构一次性搭好，从而让创建过程更高效、更可靠。
用法：
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init <skill-name> [--path <dir>] [--resources scripts,references,assets] [--examples]
--path 默认使用当前工作目录（WORKSPACE_DIR），新创建的 skill 写入 workspace，当前会话立即可用。
示例：
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init my-skill
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init my-skill --resources scripts,references
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" init my-skill --path /custom/location --resources scripts --examples
这个脚本会：
- 在指定路径创建技能目录
- 生成带有正确 frontmatter 和 TODO 占位内容的
SKILL.md模板 - 根据
--resources可选地创建资源目录 - 在设置了
--examples时可选地生成示例文件
初始化完成后，请按需完善 SKILL.md 并补充资源。如果你使用了 --examples，应把占位文件替换成真实内容，或删除它们。
第 4 步：编辑技能
无论你编辑的是新生成的技能还是已有技能，都要记住：这个技能是给另一个 agent 实例使用的。应包含那些对 agent 有帮助、且并非显而易见的信息。思考哪些程序性知识、领域细节或可复用资源，能帮助另一个 agent 实例更有效地完成这些任务。
学习已验证的设计模式
根据技能的需要，查阅以下有帮助的指南：
- 多步骤流程：参见(如果有)
references/workflows.md，了解顺序工作流与条件逻辑的组织方式 - 特定输出格式或质量标准：参见(如果有)
references/output-patterns.md，了解模板和示例模式
这些文件总结了构建高质量技能的成熟最佳实践。
从可复用内容开始
开始实现时，应先落地前面识别出的可复用资源：scripts/、references/ 和 assets/。注意，这一步可能需要用户输入。例如，在实现 brand-guidelines 技能时，用户可能需要提供品牌素材或模板放入 assets/，或提供文档放入 references/。
新增脚本后，必须通过实际运行来测试，确认没有 bug，且输出符合预期。如果存在很多相似脚本，可以只测试具有代表性的一部分，以在完成时间和可靠性之间取得平衡。
如果你使用了 --examples，请删除技能不需要的占位文件。只创建真正需要的资源目录。
更新 SKILL.md
写作原则： 始终使用祈使式 / 不定式风格。
Frontmatter
使用 YAML frontmatter 编写 name 和 description：
name：技能名称description：这是技能最主要的触发机制，用来帮助 agent 理解何时应使用该技能- 既要说明技能做什么，也要说明具体的触发场景 / 上下文
- 所有“何时使用”的信息都应写在这里，而不是正文里。正文只有在技能触发后才会加载，所以正文中的“何时使用本技能”章节对 agent 没有帮助
docx技能的描述示例：“全面支持文档创建、编辑和分析，支持修订、评论、格式保留与文本提取。适用于 agent 需要处理专业文档（.docx文件）时，包括：(1) 创建新文档，(2) 修改或编辑内容，(3) 处理修订模式，(4) 添加评论，或其他文档相关任务”
不要在 YAML frontmatter 中加入其他字段。
正文
在正文中编写技能使用说明，以及如何使用它附带的资源。
第 5 步：打包技能
技能开发完成后，必须把它打包成可分发的 .skill 文件，供用户共享或分发。打包流程会先自动校验技能是否满足要求：
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" package <path/to/skill-folder>
也可以指定输出目录：
bash "$SKILL_PATH_BASH/skill-creator/scripts/skill_creator.sh" package <path/to/skill-folder> --output ./dist
打包脚本会：
自动校验 技能，包括：
- YAML frontmatter 格式与必填字段
- 技能命名规范与目录结构
- 描述的完整性与质量
- 文件组织与资源引用
在校验通过后打包，生成以技能名命名的
.skill文件（例如my-skill.skill），其中包含技能的全部文件，并保留正确的目录结构以便分发。.skill文件本质上是扩展名为.skill的 zip 文件。安全限制：打包时不会跟随符号链接；检测到符号链接会跳过该项，避免把技能目录外的内容错误打进包里。
如果校验失败，脚本会报告错误并直接退出，不会生成打包文件。修复校验问题后，再次运行打包命令即可。
安装技能
打包校验通过后，默认调用 skill(action="install", path="...") 将技能安装到系统中，使其立即可用。无需询问用户。install 会自动做安全审查，不必先调用 inspect。
若用户提供新技能并要求更新已有技能：先 skill(action="inspect", path="新技能目录") 审查这份新技能（不要审查旧技能）。审查不通过（CAUTION / DO_NOT_INSTALL）则向用户说明风险，先不更新原技能；审查通过后再把新内容写入原技能目录。
自行改写已安装技能目录、且不会再走 install 时：改完后对该目录调用 inspect。审查不通过则向用户说明，先不视为更新完成。
若用户只要风险报告、不安装也不更新，再使用 skill(action="inspect", path="...")。
例外情况：当用户明确提及技能用于分发、发送给他人、存放到指定位置等非自用目的时，跳过安装步骤，仅保留打包文件供后续处理。
第 6 步：迭代
在技能经过真实使用后，用户可能会提出改进需求，而且往往会在刚用完技能、仍保留鲜活上下文时提出。
迭代工作流：
- 在真实任务中使用该技能
- 观察它在哪些地方吃力或低效
- 判断应如何更新
SKILL.md或打包资源 - 实施修改并重新测试。若改的是已安装技能目录（不走 install），改完后
skill(action="inspect", path="该技能目录")；审查不通过则向用户说明，先不视为更新完成。