skills-creation

技能创建与维护

用于在 Editframe 集中式技能系统中创建和更新技能的 Agent 指南。

概述

技能是 Agent 能力的基础。此技能提供以下指引：

• 从零创建新技能，并获得用户指导
• 更新现有技能，并进行验证
• 通过结构化编写维护技能质量
• 更改后在各 Agent 目录间同步技能

快速入门：创建新技能

1. 询问用户想要创建什么技能
2. 收集需求：用途、能力、使用场景
3. 在 .skills/internal/{skill-name}/ 中创建技能结构
4. 编写内容（SKILL.md + 可选的 references/）
5. 验证结构和 frontmatter
6. 同步更改至各 Agent 目录
7. 提交到 git

Agent 工作流指引

阶段 1：需求探索

用户请求创建新技能或更新技能时：

1. 提出澄清问题：

   • “此技能的主要用途是什么？”
   • “谁会使用此技能（哪些 Agent/用户）？”
   • “核心能力或主题有哪些？”
   • “这是在更新现有技能，还是创建新技能？”

2. 记录需求：

   • 技能名称（kebab-case：my-skill-name）
   • 描述（面向大模型的一句话说明）
   • 要涵盖的主要章节/主题
   • 示例使用场景

阶段 2：结构规划

编写前，先规划技能结构：

1. 确定技能类型：

   • 参考类技能：记录现有系统/API（最常见）
   • 教程类技能：通过示例进行循序渐进的学习
   • 操作指南类技能：提供特定任务的指导
   • 解释类技能：深入理解概念

2. 对计划编写的每部分内容进行分类：

   编写任何内容前，将计划纳入的每个章节归类：

   • 操作流程 -- 如何执行某项操作（部署、回滚、创建发布版本）。内容稳定。以散文形式编写。
   • 架构信息 -- 系统的高层运作方式（各部分如何连接、系统为何采用某种结构）。稳定性中等。以简洁的叙述形式编写，但避免罗列具体细节。
   • 枚举数据 -- 各类清单、数值表格、数量、名称、版本（服务列表、资源分配、软件包名称、密钥名称、路由表）。易变，不要写入技能。 应引导 Agent 查阅源文件，或创建用于查询源文件的配套脚本（参见下文“配套脚本”）。

   目标是：配置文件发生更改时，无需更新任何技能文档。技能教 Agent 如何推理某个领域；脚本和源文件提供当前事实。

3. 规划文件结构：

   .skills/internal/{skill-name}/
   └── SKILL.md                    # Main entry point (required)
   

   或者，若内容较为详细：

   .skills/internal/{skill-name}/
   ├── SKILL.md                    # Overview + quick start
   └── references/
       ├── topic-1.md              # Deep dive on topic 1
       ├── topic-2.md              # Deep dive on topic 2
       └── topic-3.md              # Examples/guides
   

4. 快速参考模板：

   • SKILL.md：200-400 个词，用于介绍技能
   • 每份参考文档：400-800 个词，涵盖一个主题
   • 注重清晰易懂，便于大模型理解

阶段 3：内容创作

SKILL.md frontmatter（必需）：

---
name: skill-name-kebab-case
description: One sentence describing what this skill does and who should use it.
---

name 必须始终使用短横线分隔格式，且不能包含空格。按名称加载技能的工具在名称包含空格时可能会静默失败或行为异常。name 字段是机器标识符；请在正文中使用 # Heading 作为面向人类的显示名称。

SKILL.md 正文（推荐结构）：

# {Skill Title}

{2-3 sentence overview}

## Quick Start

{Most essential information to start using - code snippet, key concept, or first steps}

## Key Concepts

{Explain the main ideas or capabilities}

## Common Patterns

{Show 2-3 typical use cases with examples}

## When to Use This Skill

{Guidance on when agents should invoke this skill}

参考文件（可选，适用于复杂技能）：

---
name: reference-title
description: What this reference covers
---

# Reference Title

{Introduction}

## Section 1
{Content}

## Section 2
{Content}

写作指南：

• SKILL.md 的目标长度为 300-500 个词
• 优先使用具体示例，而非抽象解释
• 适用时加入代码块或代码片段
• 使用相对路径在技能之间建立链接：[skill-name](...)
• 面向大模型编写（清晰、有条理，不带营销内容）
• 切勿重复源文件中的数据。 如果可以从仓库中已有的配置文件、脚本或定义推导出信息，就不要将其复制到技能中。请改为告知 Agent 在哪里查找（"运行 scripts/deploy-info telecine 获取当前服务列表"），或要读取哪个文件（"查看 telecine/deploy/worker-resources.config.ts 获取当前资源分配"）。技能应当是推理指南，而不是事实缓存。
• 检查是否过时： 定稿任何章节之前，先问自己：“如果有人明天修改配置文件，这段文字会不会变得不准确？”如果会，就改为引用源文件，而不是重述其内容。

配套脚本

有些技能需要配套脚本——一种用于查询本地配置文件并输出当前数据，供 Agent 使用的脚本。它可以替代技能正文中硬编码的表格和列表。

何时创建配套脚本：

• 技能涉及会变化的配置（服务列表、资源分配、软件包版本、路由表、密钥名称）
• 需要读取并关联多个源文件，才能回答常见问题
• 源文件格式需要领域知识才能解析（Pulumi TypeScript、GitHub Actions YAML、复杂配置）

设计原则：

• 仅限本地。 不联网、不使用 Docker、不进行身份验证。脚本解析磁盘上的文件，运行时间应少于一秒。
• 放在根目录。 将配套脚本放在 monorepo 根目录下的 scripts/ 中，而不是软件包内。
• 结构化纯文本输出。 每行一个字段，类似 YAML。便于人类和大模型阅读。不要使用 JSON（占用上下文窗口过多），也不要使用美化排版的表格（难以准确解析）。
• 轻量包装模式。 使用一个 bash 脚本（scripts/{name}）调用 npx tsx scripts/{name}.ts。与现有约定一致（参见 scripts/skills-sync）。

何时不创建配套脚本：

• 数据位于一个简单文件中，Agent 可以直接读取（例如 package.json）
• 技能领域纯属流程性内容（操作步骤、调试工作流）
• 数据很少变化（部署流程、工具链选择）

在这些情况下，只需告知 Agent 要读取哪个文件："查看 telecine/deploy/worker-resources.config.ts 获取当前资源分配。"

示例：deployments 技能使用 scripts/deploy-info telecine 和 scripts/deploy-info elements，从本地配置文件中查询当前服务、资源、路由、密钥、软件包和发布流水线步骤。

阶段 4：验证

同步前，请验证该技能：

1. 文件结构检查：

   # Verify files exist
   ls -la .skills/internal/{skill-name}/
   
   # Should see: SKILL.md (required)
   # May see: references/ directory with additional .md files
   

2. Frontmatter 验证：

   • 必需字段齐全：name、description
   • name 使用 kebab-case，并与目录名称一致
   • description 为单句
   • 无语法错误（有效的 YAML）

3. 内容验证：

   • 引言部分清晰
   • 子章节组织有序
   • 包含具体示例
   • 链接格式正确：[text](path) 或 [text](references/file.md)

4. 漂移检查：

   • 扫描每个章节，查找枚举数据：数值表、名称项目符号列表、硬编码的计数或版本
   • 对每一处都问：“这些数据是否存放在可能独立变化的源文件中？”
   • 如果是：替换为对源文件或配套脚本的引用
   • 常见问题：服务／工作进程列表、资源分配、软件包名称、密钥名称、路由表、管道步骤列表、环境变量

5. 示例检查：

   # Manually verify the content structure
   cat .skills/internal/{skill-name}/SKILL.md
   

阶段 5：同步

技能完成并通过验证后：

1. 向用户确认：“是否准备好将此技能同步到所有 Agent 目录？”

2. 运行同步脚本：

   npm run skills:sync
   

3. 验证同步：

   # Check that files now exist in all 3 directories
   ls -la .skills/internal/{skill-name}/SKILL.md
   ls -la .cursor/skills/{skill-name}/SKILL.md
   ls -la .claude/skills/{skill-name}/SKILL.md
   

4. 报告成功：

   ✅ Skill synced successfully!
   
   Synced to:
   - .skills/internal/ (canonical source)
   - .cursor/skills/ (Cursor agent)
   - .claude/skills/ (Claude Code agent)
   

阶段 6：提交到 Git

如果技能已完成并获批准：

1. 暂存更改：

   git add .skills/internal/{skill-name}/
   

2. 创建提交：

   git commit -m "Create {skill-name} skill"
   

3. 确认提交：

   git log -1 --name-status
   

完整交互示例

用户：“我需要一个用于调试视频渲染问题的技能。”

Agent（发现阶段）：

我会帮你创建一个视频渲染调试技能。先收集一些信息：

1. 是否应涵盖常见的渲染错误（伪影、播放问题、编码）？
2. 主要用户是谁（开发者、内容创作者）？
3. 该技能涵盖哪些系统（Elements、React、API）？

用户：“都要——这是给调试 Elements 渲染问题的开发者用的。”

Agent（规划阶段）：

好极了！我会创建一个名为 elements-rendering-debug 的参考技能，其中包含：

• SKILL.md：调试工作流概述
• references/common-issues.md：伪影、播放和内存问题
• references/diagnostics.md：检查和排查方法
• references/solutions.md：常见修复方法和变通方案

Agent（创建阶段）：

正在创建技能结构……

[写入文件]

Agent（验证阶段）：

正在验证技能： ✅ 目录结构正确 ✅ SKILL.md frontmatter 有效 ✅ 已包含所有参考资料 ✅ 链接格式正确

Agent（同步阶段）：

是否准备好将此技能同步到所有 Agent 目录？

正在运行：npm run skills:sync

✅ 同步成功！

• .skills/internal/elements-rendering-debug/（规范版本）
• .cursor/skills/elements-rendering-debug/
• .claude/skills/elements-rendering-debug/

Agent（提交阶段）：

正在提交到 git：

git add .skills/internal/elements-rendering-debug/
git commit -m "Add elements-rendering-debug skill"

✅ 完成！现在所有 Agent 目录中都可以使用该技能。

示例：识别并提取易变数据

本示例展示了初稿包含会随时间变化的数据时会发生什么。

Agent 编写了一项部署技能，其中包含一张表格：

服务	CPU	内存	最大实例数
web	1000m	1Gi	10
render-fragment	2000m	4Gi	200

审查（第 4 阶段的漂移检查）发现了这个问题：CPU、内存和实例数都来自 worker-resources.config.ts 和 Pulumi cloudrun.ts 文件。如果有人将 render-fragment 的内存调整到 8Gi，技能文档就会立即过时。

解决方案：创建一个配套脚本（scripts/deploy-info），用于解析这些源文件并输出当前值。将技能中的表格替换为：

运行 scripts/deploy-info telecine，查看当前服务和资源分配。

技能保留其流程性和架构性内容（部署如何运作、如何扩缩资源、如何回滚）。易变数据始终通过实时查询获取。

更新现有技能

更新现有技能：

1. 定位技能：

   ls .skills/internal/{skill-name}/
   

2. 进行更改：

   • 编辑 SKILL.md 内容
   • 添加或修改参考文件
   • 按需更新 frontmatter

3. 验证（与上文第 4 阶段相同）

4. 同步：

   npm run skills:sync
   

5. 提交：

   git add .skills/internal/{skill-name}/
   git commit -m "Update {skill-name} skill"
   

技能目录

检查规范目录，列出当前技能：

ls .skills/internal/

每个子目录都是一项技能。阅读其 SKILL.md frontmatter，查看名称和描述。

关键文件和脚本

脚本

• npm run skills:sync - 将内部技能同步到所有 Agent 目录
• npm run skills:sync:dry - 预览将要同步的内容
• npm run skills:sync:verbose - 显示详细的同步输出
• npm run skills:generate - 生成对外发布的技能

目录

• .skills/internal/ - 规范的事实来源（提交到 git）
• .cursor/skills/ - Cursor Agent 的同步副本
• .claude/skills/ - Claude Code Agent 的同步副本
• .skills/external/ - 生成的外部技能（已加入 gitignore）

文档

• skills/SYNC.md - 完整的技能同步系统文档
• .skills/internal/skills-docs/SKILL.md - 详细的技能文档系统

根据使用情况改进技能

内部技能应在使用过程中自我改进。当 Agent 遵循技能后，结果有误、不完整或不理想，并且用户提供了反馈时，Agent 应在完成任务前更新技能。

何时更新技能：

• 技能指南导致了错误结果，需要用户纠正
• 技能缺少某个步骤或注意事项，需要用户补充
• 用户提供的原则或约束适用于当前任务之外的场景

如何更新：

• 提炼共性。 从具体情况中总结可复用的经验。“始终将内容分类为流程性、架构性或枚举类”，而不是“构建 deployments 技能时，我们发现服务表格会过时。”
• 保持简洁。 改进应让技能更精准，而不是更长。如果要添加一段内容，就找一段删去或精简。
• 不要简单追加。 技能不是日志。不要添加“经验总结”章节，也不要不断累积示例。应将改进融入现有结构——修改指南、添加验证检查或调整阶段说明。
• 同步并提交。 更新技能遵循相同的工作流：在 .skills/internal/ 中编辑，运行 npm run skills:sync，然后提交。

不要这样做：

• 不要记录特定会话的细节（“2 月 17 日我们发现……”）
• 不要将每个边缘情况都新增为一个项目符号——技能应保持通用
• 不要为了迁就一次性的例外而弱化现有指南

何时不应创建技能

以下情况不需要技能：

• 一次性任务或调试过程
• 临时实用工具或脚本
• 应写在代码注释中的内容
• Agent 可以直接回答的问题

以下情况适合使用技能：

• 可重复的流程（创建新项目、调试模式）
• 多个 Agent 都应遵循的指南
• 需要便于发现的知识
• 应标准化的实践

优质技能的提示

✅ 目标明确 - 一个技能对应一个明确的目标或领域 ✅ 自成一体 - 无需依赖其他内容也能理解 ✅ 实用 - 包含真实示例和模式 ✅ 易于发现 - 名称能清楚说明其涵盖内容 ✅ 可链接 - 适时引用其他技能 ✅ 保持更新 - 实践发生变化时及时更新

故障排除

问：技能未同步？ 答：运行 npm run skills:sync:dry，检查是否有错误。检查 .skills/internal/ 中的文件权限。

问：应该在 .cursor/ 还是 .skills/ 中编辑？ 答：始终在 .skills/internal/（规范来源）中编辑。提交到 git 的正是这里的内容。

问：可以有针对特定 Agent 的技能吗？ 答：不可以，所有 Agent 获得的技能都相同。使用 .skills/internal/ 作为唯一来源。

问：如何删除技能？ 答：从 .skills/internal/ 中删除，然后运行 npm run skills:sync。该技能会自动从 Agent 目录中移除。

问：需要撤销技能变更？ 答：使用 git：git checkout HEAD -- .skills/internal/{skill-name}/，然后运行 npm run skills:sync。