skill-creator

Skill Creator

合约

输入：

• 请求的技能名称、目标位置、行为和现有示例

输出：

• 技能说明、可选资源和验证结果

创建/修改：

• 仅限请求的技能及其打包文件

外部副作用：

• 除非明确请求，否则不发布，也不安装到其他环境

需要确认：

• 替换无关的现有技能、安装外部依赖项或发布到授权目标位置以外的地方之前
• 加载技能不会授予额外权限。现有的明确批准仅适用于相同目标和操作；保留仅报告的限制。

委派给：

• 无

关于技能

技能是模块化软件包，可添加特定任务的工作流、工具说明、领域知识、脚本、参考资料和资源。

技能提供的内容

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司特定的知识、架构和业务逻辑
4. 捆绑资源——用于复杂和重复任务的脚本、参考资料和资源

技能的组成

每个技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

元数据： YAML frontmatter 中的 name 和 description 决定何时激活技能。描述必须包含任务、触发短语和边界；避免针对特定客户端的叙述。

捆绑资源（可选）

脚本（scripts/）

用于需要确定性可靠性的任务，或会反复重写的可执行代码（Python/Bash 等）。

• 适用情形：同一段代码反复重写，或需要确定性可靠性
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省 Token、结果确定，且可在不加载到上下文的情况下执行
• 注意：Agent 仍可能需要读取脚本以进行修补或针对特定环境进行调整

参考资料（references/）

仅在当前任务需要时加载的文档和参考材料。

• 适用情形：Agent 工作时需要查阅的文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 适用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：让 SKILL.md 保持精简，仅在 Agent 判断需要时加载
• 最佳实践：如果文件较大（>10k 字），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：每项事实只放在一个位置。将触发条件、工作流步骤、关卡和必需输出放在 SKILL.md 中。将详细的参考材料、架构、长示例和源文摘录移至 references/。

资源文件（assets/）

不用于加载到上下文，而是供 Agent 在生成的输出中使用的文件。

• 适用情形：技能需要在最终输出中使用的文件
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板文件 assets/frontend-template/、排版字体 assets/font.ttf
• 适用场景：模板、图像、图标、样板代码、字体、需要复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Agent 无需将文件加载到上下文即可使用

渐进式披露设计原则

技能使用三级加载系统来高效管理上下文：

1. 元数据（名称 + 描述） - 始终位于上下文中（约 100 个词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个词）
3. 打包的资源 - Agent 按需加载（无限制*）

*之所以不受限制，是因为脚本可以执行，而不必读入上下文窗口。

技能创建流程

按顺序遵循“技能创建流程”。只有在某个步骤的前提条件已经满足时，才能跳过该步骤，并说明原因。

步骤 1：通过具体示例了解技能

仅当已清楚了解技能的使用模式时，才能跳过此步骤。即使处理现有技能，此步骤仍然很有价值。

要创建有效的技能，必须清楚了解技能的具体使用示例。这种了解可以来自用户直接提供的示例，也可以来自经用户反馈验证的生成示例。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应该支持哪些功能？编辑、旋转，还是其他功能？”
• “能举几个这个技能的使用示例吗？”
• “我能想到用户可能会提出‘消除这张图像中的红眼’或‘旋转这张图像’之类的请求。你还想得到其他用法吗？”
• “用户说什么时应该触发这个技能？”

除非缺少的信息会使技能不安全或无法创建，否则最多只问一个澄清问题。将不确定的假设写入草稿。

只有在明确了触发语句、支持的任务和排除的任务后，才结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请针对每个示例进行分析：

1. 考虑如何从头开始执行该示例
2. 确定重复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

例如，构建用于处理“帮我旋转这个 PDF”之类请求的 pdf-editor 技能时，分析结果如下：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会很有帮助

例如，为处理“帮我构建一个待办事项应用”或“帮我构建一个跟踪步数的仪表板”之类请求而设计 frontend-webapp-builder 技能时，分析结果如下：

1. 编写前端 Web 应用每次都需要相同的样板 HTML/React 代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会很有帮助

例如，构建用于处理“今天有多少用户登录？”之类请求的 big-query 技能时，分析结果如下：

1. 每次查询 BigQuery 都需要重新发现表结构和表之间的关系
2. 将记录表结构的 references/schema.md 文件存放在技能中会很有帮助

要确定技能的内容，请分析每个具体示例，并列出应包含的可复用资源：脚本、参考资料和资源文件。

步骤 3：初始化技能

仅当正在开发的技能已存在，且需要迭代或打包时，才能跳过此步骤。此时，请继续下一步。

从头创建新技能时，务必运行 init_skill.py 脚本。 该脚本会生成所需的目录、frontmatter 和资源文件夹。

用法：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会：

• 在指定路径创建技能目录
• 生成包含正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，替换生成的 SKILL.md 占位内容，并删除所有未使用的示例文件。

第 4 步：编辑技能

编辑技能时，只包含会改变其他 Agent 可观察行为的指令：触发条件、必需操作、禁止操作、顺序门控、工具选择、输出字段、限制、回退方案或证据要求。

从可复用的技能内容开始

从上面确定的可复用资源开始实施：scripts/、references/ 和 assets/。如果缺少必需的资源或源文档，请索要该内容，或标记受影响的工作流不受支持。

此外，删除技能不需要的示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件，以展示结构，但大多数技能并不需要全部示例。

更新 SKILL.md

写作风格： 使用祈使式／不定式（动词开头的指令）撰写整个技能，不要使用第二人称。使用客观、指导性的语言（例如，“要完成 X，执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样可以保持 AI 易于理解的一致性和清晰度。

完成 SKILL.md 时，回答以下问题：

1. 技能的用途是什么？用几句话说明。
2. 何时应使用该技能？
3. 实际操作中，Agent 应如何使用该技能？引用上面开发的所有可复用技能内容，明确说明工作流。

House 写作规范

本目录的标准见 .agents/memory/system/skill-standards.md。编辑 SKILL.md 时遵循以下规范：

• 调用方式。 明确的入口点和仅提供建议的映射应设置 disable-model-invocation: true，仅供用户调用。可复用引擎不要设置此项，以便选定的工作流能够调用它们。加载引擎不授予操作权限：传递请求范围、现有授权和仅报告限制。将变更门控放在正文中，仅在缺少授权或需要扩大授权时要求批准。可调用的引擎使用直接执行路径；仅供用户明确调用的工作流提供建议。根据所选的已安装技能目录解析资源，不要假定存在仓库检出目录。
• 开头词。 将重复表达的想法浓缩为一个预训练词元（frontier、seam、tight、red）。重复使用该词元；不要再次解释句意。
• 完成标准。 每个步骤都以可核验的界限结束。将“达到理解”明确为可观察的结果（“frontier 为空”“针对缺失行为的窄范围测试失败”）。
• 删减无效内容。 删除任何不会改变模型默认行为的句子。
• 正向提示。 明确说明目标行为。将严格禁令与正向目标配对。
• 契约。 操作、编排和副作用类技能都应包含 ## Contract 区块（输入、输出、创建／修改内容、副作用、确认、委派）。
• 来源信息。 基于上游内容派生的技能应声明 source、upstream_repo、last_synced，并在 README 中添加 ## Upstream 小节。

当技能或引导文件较长、重复说明环境，或需要决定材料应放置在何处时，阅读 references/writing-for-agents.md：双重加载、就近放置、内容膨胀、按顺序拆分、将环境视为缓存、沉积。

步骤 5：打包技能

技能准备就绪后，应将其打包成可分发的 zip 文件，并分享给用户。打包过程会先自动验证技能，确保其符合所有要求：

scripts/package_skill.py <path/to/skill-folder>

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

1. 验证 技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 如果验证通过，则打包技能，创建一个以技能名称命名的 zip 文件（例如，my-skill.zip），其中包含所有文件，并保留适用于分发的正确目录结构。

如果验证失败，脚本会报告错误并退出，不会创建软件包。请修复所有验证错误，然后再次运行打包命令。

步骤 6：迭代

测试技能后，根据观察到的失败或反复出现的阻碍，更新 SKILL.md 或打包的资源。

迭代工作流：

1. 在实际任务中使用技能
2. 留意困难或低效之处
3. 确定应如何更新 SKILL.md 或打包的资源
4. 实施更改并再次测试