create-skill

Create Skill

这个 Skill 用于指导如何创建有效的 Skill。

关于 Skill

Skill 是模块化、自包含的文件夹，用于通过专门知识、工作流和工具扩展 Agent 的能力。可以把它们理解为特定领域或任务的“入门指南”：它们把一个普通 Agent 从通用 Agent 转换为专门的跨端 Agent，让 Agent 具备模型本身无法完全掌握的流程性知识。

Skill 提供什么

1. 跨端专门工作流 - 面向跨端特定领域的多步骤流程
2. 跨端工具集成 - 针对特定的跨端工具进行说明，如 Expo, CI/CD 等
3. 跨端领域知识 - 跨端特定知识如通信桥， 原生模块， 业务逻辑等
4. 捆绑资源 - 面向复杂或重复任务的脚本、参考资料和资产

核心原则

简洁是关键

上下文窗口是一种公共资源。Skill 会和 Agent 所需的其他所有内容共享上下文窗口：系统提示、对话历史、其他 Skill 的元数据，以及用户当前的实际请求。

默认假设：Agent 已经非常聪明。只需要一点经验指点就能完成工作!!!! 只添加 Agent 尚不具备的上下文。审视创建的 Skill 的每一段信息：“Agent 真的需要这段解释吗？”以及“这段内容值得占用这些 token 吗？”

• 抽象理念 > 实现具体, 避免长文的解释和实现描述，只需要用最简洁的语言指出一个关键词即可。

• 务必优先使用简洁示例，而不是冗长解释。

• 禁止将同一份描述在 Skill 重复多次

Bad Example:

使用这个 Skill 创建 React Native New Architecture TurboModule。先确认 RN 版本、模块边界和平台范围，再选择 Android/iOS 平台实现或纯 C++ 跨端实现，避免把旧桥 NativeModule 模板套进新架构项目。

## Stop Rule
1. RN 版本：精确版本或版本范围，至少要能判断是否属于 `0.82+`、`0.76-0.81`、`0.74-0.75`、`0.68-0.73`。

## Good Example:
为 React Native 创建新架构支持的 TurboModule
## Stop Rule
1. RN 版本: `0.82+`、`0.76-0.81`、`0.74-0.75`、`0.68-0.73`。

设置合适的自由度

根据任务的脆弱程度和变化空间，匹配说明的具体程度：

高自由度（文本说明）：当多种方案都有效、决策依赖上下文，或需要启发式判断时使用。

中自由度（伪代码或带参数脚本）：当存在推荐模式、允许部分变化，或配置会影响行为时使用。

低自由度（具体脚本、少量参数）：当操作脆弱且容易出错、一致性非常关键，或必须遵循特定顺序时使用。

可以把 Agent 想象成正在野外探险：狭窄桥梁和悬崖需要明确护栏（低自由度），开阔平原则允许多种路线（高自由度）。

前置问题最佳实践

当 Skill 需要收集前置信息或向用户提问时，必须设计可复用的前置问题流程：

1. 提问前先读取目标项目根目录的 .hyar/ARCH_CONTEXT.md。如果已有同一环境变量、前置项或决策问题的答案，优先复用，不重复询问。
2. 仍缺信息时，每次只问最小必要问题，并提供一个标记为“最佳实践”的可选项。
3. “最佳实践”选项必须给出可执行默认值，不要只写“推荐”。默认值遵循：最小化 > 最大化；最新技术 > 老技术；通用技术 > 小范围技术。
4. 用户回答任一 Skill 前置问题后，必须使用或触发 arch-context-collect，把问题描述、前置项名称、用户回答、适用 Skill 和更新时间写入 .hyar/ARCH_CONTEXT.md。
5. 同一个环境变量或前置项的问题描述只存储一份；后续回答只更新答案或追加适用 Skill。

Skill 的组成

每个 Skill 都由必需的 SKILL.md 文件和可选的捆绑资源组成：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - 可执行脚本
    ├── references/       - 按需加载的文档和参考资料
    └── assets/           - 最终产物使用的模板、图片、样板等资产

SKILL.md（必需）

每个 SKILL.md 都包含：

• Frontmatter（YAML）：包含 name, description 字段。Agent 只会读取这些字段来判断何时使用该 Skill，因此必须清晰、完整地描述这个 Skill 是什么，以及应该在什么情况下使用。
• 正文（Markdown）：使用该 Skill 的说明和指导。只有在 Skill 触发之后才会加载（如果触发的话）。

元数据（推荐）

元数据作为 Skill 描述的补足，不要对 Skill Description 本身做不必要的补充，更多的应该描述其更多的使用场景，以确保智能体能准确的调用该 Skill。

• 默认不要写 metadata。只有存在明确版本适用边界或强环境前提时才写，通用知识、选型指南、流程方法论不要写。
• metadata.version：只用于说明当前 Skill 的知识只针对某个跨端框架的特定版本或版本区间。例如 RN 原生模块从 RN 0.74 之后官方更推荐 TurboModule，因此介绍 TurboModule 的 Skill 可以写 React Native >= 0.74。
• metadata.env：只用于说明当前 Skill 要求项目已经具备某个强配置或环境前提。例如“已启用 React Native New Architecture”“已配置 Expo CNG”。如果 Skill 不要求项目开启某个配置，不要写此项。

Upstream Skill（用户明确说明依赖其他 Skill 时才书写）

Upstream Skill 只表示当前 Skill 依赖并补充另一个 Skill。它不是普通文档、API 页面、模块路径或参考资料来源。

• 只有用户明确说明该 Skill 依赖其他 Skill 时，创建的 Skill 才应说明此项。
• 该项应填写上游 Skill 名称或 Skill bundle URL。
• 普通文档、API 页面、模块说明、框架资料应放入 references/ 或正文参考说明，不得写入 Upstream Skill。
• 请假设上游 Skill 很强大，能够控制基础流程；补充知识时反问自己缺失这些内容时上游 Skill 是否仍能正常运行。

Curated Skill 禁止修改

create-skill 不能创建、修改或校验 curated Skill。curated Skill 的模板非常严格，通常包含 > Curated from ...，例如 skills/flutter/*/SKILL.md。

• 遇到 curated Skill 时，改用 create-curated-skill。
• 不要把 curated Skill 改写成普通 repo-local Skill 模板。
• 不要删除或改写 curated Skill 的 > Curated from ...、## Source、严格 ## How to use 结构。

Skill 分类目录

普通 repo-local Skill 不直接放在 skills/ 根目录，必须先判断它属于哪个分类目录：

• React Native 专属：放在 skills/react-native/<skill-name>/。
• 语言专属：放在对应语言目录，例如 skills/dart/<skill-name>/、skills/kotlin/<skill-name>/。
• 跨端通用知识：放在 skills/share/<skill-name>/。
• 新的单独框架：在 skills/<framework>/ 下新建分类目录，再放入该 Skill。
• Flutter 官方 curated Skill 仍由 create-curated-skill 维护；不要用 create-skill 写入 skills/flutter/*。

当 init_skill.py --path skills 时必须传入 --category，避免把普通 Skill 误放到根目录。

捆绑资源（可选）

Scripts（scripts/）

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

• 何时包含：当同一段代码会被反复重写，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 收益：节省 token、结果确定，并且可以在不加载到上下文窗口的情况下执行
• 注意：Agent 可能仍需读取脚本，以便进行修补或适配特定环境

References（references/）

文档和参考资料，用于在需要时加载到上下文中，辅助 Agent 的流程和思考。

• 何时包含：当 Agent 进行跨端工作时应该参考某些文档
• 示例：书写 RN 通信桥模板的 的 references/rn_turbo.md、框架更新日志的 references/rn_update.md、产品/公司核心理念的 references/flutter_idea.md、RN Api 使用规范的 references/api_docs.md
• 使用场景：数据库 schema、API 文档、领域知识、框架政策、详细工作流指南
• 收益：让 SKILL.md 保持精简，只在 Agent 判断需要时加载
• 最佳实践：如果文件较大（超过 10k 词），在 SKILL.md 中包含 grep 搜索模式
• 避免重复：信息应只存在于 SKILL.md 或 references 文件中，不要两边都放。除非某些内容确实是 Skill 的核心，否则优先放入 references 文件；这样既能保持 SKILL.md 精简，又能避免占用上下文窗口，同时保持信息可发现。SKILL.md 只保留必要的流程说明和工作流指导；详细参考资料、schema 和示例应移入 references 文件。

Assets（assets/）

不打算加载到上下文中，而是用于 Agent 最终产物的文件。

• 何时包含：当 Skill 需要使用某些文件生成最终输出时
• 示例：品牌资产 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板 assets/frontend-template/、字体 assets/font.ttf
• 使用场景：模板、图片、图标、样板代码、字体、会被复制或修改的示例文档
• 收益：把输出资源与文档分离，让 Agent 可以使用文件而不必把它们加载到上下文中

Skill 中不应包含什么

Skill 只应包含直接支持其功能的必要文件。不要创建多余文档或辅助文件，包括：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• etc.

Skill 应只包含 AI Agent 完成当前工作所需的信息。它不应包含 Skill 创建过程、安装和测试流程、用户向文档等额外上下文。创建额外文档文件只会增加混乱和噪音。

渐进式披露设计原则

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

1. 元数据（name + description + metadata） - 始终在上下文中（约 100 词）
2. SKILL.md 正文 - Skill 触发时加载（少于 5k 词）
3. 捆绑资源 - Agent 需要时加载或执行（容量不受上下文窗口限制，因为脚本可以不读入上下文而直接执行）

渐进式披露模式

让 SKILL.md 正文只保留必要内容，并控制在 500 行以内，以减少上下文膨胀。接近这个限制时，将内容拆分到独立文件中。拆分内容时，必须在 SKILL.md 中引用这些文件，并清晰说明何时读取它们，确保 Skill 的阅读者知道这些文件存在，以及何时使用。

关键原则： 当一个 Skill 支持多个变体、框架或选项时，SKILL.md 只保留核心工作流和选择指导。把变体相关细节（模式、示例、配置）移动到独立 reference 文件。

模式 1：带 reference 的高层指南

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Agent 只在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

对于包含多个领域的 Skill，按领域组织内容，避免加载无关上下文：

bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

当用户询问销售指标时，Agent 只读取 sales.md。

类似地，对于支持多个框架或变体的 Skill，按变体组织：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

当用户选择 AWS 时，Agent 只读取 aws.md。

模式 3：条件性细节

展示基础内容，并链接到高级内容：

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Agent 只在用户需要这些功能时读取 REDLINING.md 或 OOXML.md。

重要准则：

• 避免深层嵌套 references - references 文件距离 SKILL.md 保持一层即可。所有 references 文件都应从 SKILL.md 直接链接。
• 组织较长 reference 文件 - 对超过 100 行的文件，在顶部包含目录，使 Agent 在预览时可以看到完整范围。

Skill 创建流程

Skill 创建包含以下步骤：

1. 通过具体示例理解 Skill
2. 规划可复用的 Skill 内容（scripts、references、assets）
3. 初始化 Skill（运行 init_skill.py）
4. 编辑 Skill（实现资源并编写 SKILL.md）
5. 验证 Skill（运行 quick_validate.py）
6. 基于真实使用继续迭代

除非有明确理由说明某一步不适用，否则按顺序执行这些步骤。

Skill 命名

• 只使用小写字母、数字和连字符；将用户提供的标题规范化为 hyphen-case（例如 "Plan Mode" -> plan-mode）。
• 生成名称时，名称长度应小于 64 个字符（字母、数字、连字符）。
• 优先使用简短、动词开头的短语来描述动作。
• 当按工具命名空间能提升清晰度或触发准确性时使用命名空间（例如 gh-address-comments、linear-address-issue）。
• Skill 文件夹名称必须与 Skill 名称完全一致。

Step 1：通过具体示例理解 Skill

只有当 Skill 的使用模式已经非常清楚时，才跳过此步骤。即使是在更新现有 Skill，这一步仍然有价值。

为了创建有效的 Skill，需要通过具体示例清晰理解这个 Skill 会如何被使用。这种理解可以来自用户直接提供的示例，也可以来自生成后再经用户反馈验证的示例。

例如，构建 image-editor Skill 时，相关问题包括：

• “image-editor Skill 应该支持哪些能力？编辑、旋转，还有别的吗？”
• “能给一些这个 Skill 会如何使用的示例吗？”
• “我可以想象用户会问类似 ‘Remove the red-eye from this image’ 或 ‘Rotate this image’ 的问题。你还会期待哪些用法？”
• “用户说什么时应该触发这个 Skill？”

为了避免给用户造成压力，不要在一条消息中问太多问题。从最重要的问题开始，必要时再追问，以提高效果。

当已经清楚 Skill 应支持什么功能时，结束此步骤。

Step 2：规划可复用的 Skill 内容

为了把具体示例转化为有效 Skill，需要对每个示例进行分析：

1. 思考如果从零开始完成这个示例应如何执行
2. 识别在重复执行这些工作流时，哪些 scripts、references 和 assets 会有帮助

示例：构建 pdf-editor Skill 来处理类似 “Help me rotate this PDF” 的请求时，分析结果是：

1. 旋转 PDF 每次都需要重写相同代码
2. 将 scripts/rotate_pdf.py 脚本存入 Skill 会很有帮助

示例：设计 frontend-webapp-builder Skill 来处理类似 “Build me a todo app” 或 “Build me a dashboard to track my steps” 的请求时，分析结果是：

1. 编写前端 webapp 每次都需要相同的 HTML/React 样板
2. 将包含 HTML/React 项目样板文件的 assets/hello-world/ 模板存入 Skill 会很有帮助

示例：构建 big-query Skill 来处理类似 “How many users have logged in today?” 的请求时，分析结果是：

1. 查询 BigQuery 每次都需要重新发现表 schema 和关系
2. 将记录表 schema 的 references/schema.md 文件存入 Skill 会很有帮助

为了确定 Skill 内容，需要分析每个具体示例，并形成要包含的可复用资源清单：scripts、references 和 assets。

Step 3：初始化 Skill

到这一步，就该真正创建 Skill 了。

只有当正在开发的 Skill 已经存在时，才跳过此步骤。此时继续下一步。

从零创建新 Skill 时，始终运行 init_skill.py 脚本。该脚本会生成一个标准 Skill 文件夹，包含必需的 SKILL.md，并按需创建 scripts/、references/、assets/ 资源目录。

在创建前先判断分类目录。框架或语言专属 Skill 放入对应目录；跨端通用 Skill 放入 skills/share/；新框架先创建新的 skills/<framework>/ 分类。

不要使用 init_skill.py 在 curated Skill 目录中创建 Skill，例如 skills/flutter/*。这些目录由 create-curated-skill 维护。

用法：

scripts/init_skill.py <skill-name> --path <output-directory> [--category <category>] [--resources scripts,references,assets] [--examples]

示例：

scripts/init_skill.py rn-create-app --path skills --category react-native
scripts/init_skill.py hybrid-checklist --path skills --category share --resources references
scripts/init_skill.py kotlin-api-style --path skills/kotlin --resources references

该脚本会：

• 在分类目录下创建 Skill 目录；当 --path skills 时必须使用 --category
• 生成带有正确 frontmatter 和模板占位符的 SKILL.md
• 根据

---

Content truncated.