create-skill

Files (4)

• SKILL.md
• SKILL.md · reference/good-example/
• init_skill.py · script/
• quick_validate.py · script/

SKILL.md (first lines)

# 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 重复多次**
``` markdown
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 误放到根目录。

From Yemomo511/hybrid-agent-rail, MIT.

More from Yemomo511/hybrid-agent-rail