# Skill 开发

一个 Skill 就是一个目录：`SKILL.md` 告诉 AI 何时、如何调用；`.bat` 启动器 + Python 模块实现能力。绑定到工作流后，其 `description` 会注入对话供 AI 按需调用。Skill 在用户的桌面客户端内运行，因此可以操作本机文件、调用本地程序、访问内网。

> 推荐路径：在桌面客户端聊天中对 AI 说「帮我创建一个 skill」，内置的 `skill-manager` 技能会完成脚手架、绑定与发布。以下规范供手写与排障参考。

## 1. 目录结构

```
my-skill/
├── SKILL.md            # frontmatter: name / description / command
├── my-skill.bat        # 统一启动器（自动测速选镜像 + uv sync）
├── pyproject.toml
└── my_skill/__init__.py
```

### SKILL.md frontmatter

```markdown
---
name: my-skill
description: 具备 [能力1、能力2、能力3] 能力。当用户需求与 [关键词1、关键词2、英文别名…] 相关时调用此 skill。
command: my-skill
---
```

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| name | 是 | 字母开头，允许字母 / 数字 / `-` / `_` |
| description | 是 | AI 只凭 description 决定是否调用该 skill（不读正文），召回质量完全取决于它 |
| command | 否 | 终端命令名，默认与 name 相同 |

## 2. description 编写规范（最重要）

`description` 是**唯一**决定 AI 是否会加载该 skill 的字段。AI 在每次对话开始时只看到所有 skill 的 description，不会读 SKILL.md 正文，因此 description 写不好等于 skill 永远不会被调用。

### 强制模板（双段式中文）

```
具备 [能力1、能力2、能力3] 能力。当用户需求与 [关键词1、关键词2、英文别名1、英文别名2…] 相关时调用此 skill。
```

两段缺一不可：
- **前半句「能力」**：3-5 个动词性能力词，告诉 AI 这个 skill 能做什么
- **后半句「触发关键词」**：5-10 个用户可能用到的同义词、场景词、英文别名，这是召回的核心

### 关键词覆盖原则

写关键词时假装自己是用户，列举所有可能的表达方式：
- 中文同义词：用户说「创建技能」还是「新建 skill」还是「加一个工具」？都列上
- 英文别名 / 缩写：docx、pdf、Cloudflare、MCP、scaffold —— 用户夹中英文表达时也要能命中
- 场景词：用户描述场景而非名词时（如「我想自动点击网页」对应浏览器自动化 skill），把场景动作也写进去

### 强约束前置

如果该 skill 有「必须用我而不是 X 工具」的硬规则，直接写进 description 末尾，例如：`注意：办公文档与 PDF 必须用此 skill，禁用 read_file。` 理由：AI 召回 skill 时只看 description，硬规则前置才能阻止 AI 在不加载本 skill 的情况下错用其他工具。

### 反面 vs 正面

❌ 功能描述式，关键词稀疏，纯英文：

```
description: Scaffold a new Python-based skill. Generates SKILL.md and pyproject.toml.
```

✅ 能力 + 关键词双段，中英覆盖：

```
description: 具备 Skill 脚手架、规范校验、市场发布能力。当用户需求与新建 skill、注册 skill、上架 skill、skill 市场等相关时调用此 skill。
```

## 3. SKILL.md 正文编写原则

SKILL.md 是 AI 执行 skill 时的唯一指令来源。核心理念：**只写 AI 不知道的**。AI 本身具备广泛的编程和工具知识，SKILL.md 不是教程，而是差异化指令。

必须写（AI 无法推断）：
- 命令格式和参数：精确的 CLI 接口（命令名、参数名、必选 / 可选）
- 环境特殊性：依赖的环境变量、运行前提条件
- 关键约束 / 陷阱：容易出错的边界情况、必须遵守的顺序、格式限制
- 与其他 skill 的协作：何时该调用其他 skill、数据如何传递
- 特殊工作流：执行步骤非直觉时明确写出

不要写（AI 已经知道）：通用编程概念、标准工具用法（git / uv / pip 常规操作）、显而易见的事情、冗长的测试步骤、过度详细的示例。

好的 SKILL.md：50-100 行以内，扫一眼就能用，不重复 frontmatter 已说过的内容。

## 4. skill-manager 命令

在桌面客户端环境中运行（`skill-manager.bat` 是内置技能的启动器）。

```bash
skill-manager.bat create --name <name> --description <desc> [--command <cmd>] [--sync] [--no-bind]
skill-manager.bat pack <skill_dir> [-o <output.zip>]
skill-manager.bat upload <zip_path>
skill-manager.bat publish <skill_dir> [-o <output.zip>]   # pack + upload
skill-manager.bat list                                    # 查询市场已有技能
skill-manager.bat bind-flow <name>                        # 绑定到当前工作流（SKILL.md 变更后重跑以刷新 hash）
skill-manager.bat unbind-flow <name>
```

- `create`：生成骨架，并默认自动绑定到当前工作流（写入 flow 的 skills 白名单；不绑定则聊天中不会注入该 skill）。`--sync` 创建后立即测速选源并 `uv sync`；`--no-bind` 跳过绑定
- `bind-flow` / `unbind-flow`：绑定条目格式 `{name, hash}`，hash 为 SKILL.md 的 SHA-256；SKILL.md 变更后需重跑 bind-flow 刷新（幂等）
- `pack`：打包为 zip（自动排除 `.venv` / `__pycache__` / `.git`），zip 内以 skill name 为一级根目录
- `upload`：上传 zip 到市场 `POST {MARKET_API_BASE}/skills/upload`（multipart `file` 字段）
- `publish` / `upload` 必须先获得用户明确确认，AI 不得自动发布

### 典型流程

create（默认自动绑定当前工作流）→ 编辑 `<module>/__init__.py` 实现 → 打磨 SKILL.md → 重跑 `bind-flow` 刷新 hash → 测试通过后 `publish` 上架市场。

### 生成的 .bat 与「测速选源」

`create` 生成的 `<command>.bat` 调用 `_shared/uv-bootstrap.bat` 统一启动器。用户首次运行时并发探测 5 个 PyPI 镜像（pypi / 清华 / 阿里 / 腾讯 / 中科大），≤3 秒选最快，注入 `UV_DEFAULT_INDEX` 后 `uv sync`，结果缓存 7 天；`.venv` 健康时完全跳过。

.bat 里有一个测速代表包名，默认 `pip`。若 skill 有 ≥20MB 的大二进制依赖（pymupdf / torch / pillow / opencv-python…），把它改成该大包名，测速更可靠。不要把 .bat 改回裸 `uv run`——国内用户首装大依赖会卡死数十分钟。

## 5. 注入的环境变量

客户端运行 Skill / MCP 工具时自动注入以下变量，代码中直接读取，勿硬编码地址或凭证。

| 变量 | 说明 |
| --- | --- |
| MARKET_API_BASE | 技能 / MCP 市场 API 地址 |
| CIRCLE_AUTH_TOKEN | 认证 token，作为 `Authorization: Bearer` 附加 |
| FLOW_API_URL | flow_app 后端 API 地址 |
| CIRCLE_FLOW_ID / CIRCLE_USER_ID | 当前工作流 / 用户标识，绑定操作依赖它们 |
| CIRCLE_CONFIG_DIR | 客户端配置根目录（`mcps/` 等子目录所在），也用于派生 deep link scheme（目录名含 cn → `circow-desktop-cn`，含 global → `circow-desktop-global`） |

## 6. 分发

两条分发通道，二选一或并用：

1. 市场分发：`skill-manager.bat publish` 上架官方市场，用户在客户端内一键安装
2. 链接分发：把 `install-skill` deep link（务必带 SHA-256 hash）放到你的官网或安装器里，用户点击即装。见 [deep-link.md](https://circow.cn/docs/deep-link.md)