mirror of
https://github.com/zhayujie/chatgpt-on-wechat.git
synced 2026-07-19 04:37:28 +08:00
docs: make English the default docs language and fix link paths
This commit is contained in:
zhayujie
58
docs/zh/skills/create.mdx
Normal file
58
docs/zh/skills/create.mdx
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 创造技能
|
||||
description: 通过对话创建自定义技能
|
||||
---
|
||||
|
||||
CowAgent 内置了 Skill Creator，可以通过自然语言对话快速创建、安装或更新技能。
|
||||
|
||||
## 使用方式
|
||||
|
||||
直接在对话中描述你想要的技能，Agent 会自动完成创建：
|
||||
|
||||
- 将工作流程固化为技能："帮我把这个部署流程创建为一个技能"
|
||||
- 对接第三方 API："根据这个接口文档创建一个技能"
|
||||
- 安装远程技能："帮我安装 xxx 技能"
|
||||
|
||||
## 创建流程
|
||||
|
||||
1. 告诉 Agent 你想创建的技能功能
|
||||
2. Agent 自动生成 `SKILL.md` 说明文件和运行脚本
|
||||
3. 技能保存到工作空间的 `~/cow/skills/` 目录
|
||||
4. 后续对话中 Agent 会自动识别并使用该技能
|
||||
|
||||
<Frame>
|
||||
<img src="https://cdn.link-ai.tech/doc/20260202202247.png" width="800" />
|
||||
</Frame>
|
||||
|
||||
## SKILL.md 格式
|
||||
|
||||
创建的技能遵循标准的 SKILL.md 格式：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: Brief description of the skill
|
||||
metadata:
|
||||
emoji: 🔧
|
||||
requires:
|
||||
bins: ["curl"]
|
||||
env: ["MY_API_KEY"]
|
||||
primaryEnv: "MY_API_KEY"
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Detailed instructions...
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `name` | 技能名称，需与目录名一致 |
|
||||
| `description` | 技能描述，Agent 据此决定是否调用 |
|
||||
| `metadata.requires.bins` | 依赖的系统命令 |
|
||||
| `metadata.requires.env` | 依赖的环境变量 |
|
||||
| `metadata.always` | 是否始终加载（默认 false） |
|
||||
|
||||
<Tip>
|
||||
详细开发文档可参考 [Skill Creator 说明](https://github.com/zhayujie/CowAgent/blob/master/skills/skill-creator/SKILL.md)。
|
||||
</Tip>
|
||||
65
docs/zh/skills/hub.mdx
Normal file
65
docs/zh/skills/hub.mdx
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: 技能广场
|
||||
description: 浏览、搜索和安装 AI Agent 技能
|
||||
---
|
||||
|
||||
[Cow Skill Hub](https://skills.cowagent.ai/) 是开源的 AI Agent 技能广场，汇集了官方推荐、社区贡献和第三方平台（GitHub、ClawHub 等）的技能。
|
||||
|
||||
开源仓库：[github.com/zhayujie/cow-skill-hub](https://github.com/zhayujie/cow-skill-hub)
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260401110103.png" width="800" />
|
||||
|
||||
## 功能
|
||||
|
||||
- **浏览技能**：按类别（推荐 / 社区 / 第三方）和标签筛选
|
||||
- **搜索技能**：按名称或描述搜索
|
||||
- **查看详情**：查看技能文档、文件内容、安装命令和依赖的环境变量
|
||||
- **一键安装**：复制安装命令即可在 CowAgent 中使用
|
||||
|
||||
## 安装技能
|
||||
|
||||
在对话中或终端中执行安装命令：
|
||||
|
||||
<CodeGroup>
|
||||
```text 对话
|
||||
/skill install <name>
|
||||
```
|
||||
|
||||
```bash 终端
|
||||
cow skill install <name>
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
也可以在对话中浏览技能广场：
|
||||
|
||||
```text
|
||||
/skill list --remote
|
||||
/skill search <关键词>
|
||||
```
|
||||
|
||||
除了在列表中展示的精选技能，还可以通过 **CLI命令 + Skill Hub** 安装各种第三方技能（**GitHub、ClawHub、LinkAI、URL** 等）参考 [安装技能](/zh/skills/install)。
|
||||
|
||||
## 贡献技能
|
||||
|
||||
欢迎向技能广场提交你的技能：
|
||||
|
||||
1. 访问 [skills.cowagent.ai/submit](https://skills.cowagent.ai/submit)
|
||||
2. 使用 GitHub 或 Google 账号登录
|
||||
3. 上传包含 `SKILL.md` 的文件夹或 zip 包
|
||||
4. 自动解析技能名称、显示名称和描述，可按需修改
|
||||
5. 提交后将经过安全检查和审核后发布
|
||||
|
||||
<img src="https://cdn.link-ai.tech/doc/20260401111904.png" width="800" />
|
||||
|
||||
技能文件结构：
|
||||
|
||||
```
|
||||
your-skill/
|
||||
├── SKILL.md # 必须，放在根目录
|
||||
├── scripts/ # 可选，运行脚本
|
||||
└── resources/ # 可选，其他资源
|
||||
```
|
||||
|
||||
<Tip>
|
||||
技能基于 `SKILL.md` 文件构建，你也可以在技能详情页下载 SKILL.md，用于任何支持自定义指令的 Agent（如 OpenClaw、Cursor、Claude Code 等）。
|
||||
</Tip>
|
||||
98
docs/zh/skills/image-generation.mdx
Normal file
98
docs/zh/skills/image-generation.mdx
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: image-generation - 图像生成
|
||||
description: 文生图 / 图生图 / 多图融合，支持多家厂商自动路由与回退
|
||||
---
|
||||
|
||||
通用的图像生成与编辑技能，支持 OpenAI、Gemini、Seedream（火山方舟）、Qwen（百炼）、MiniMax、LinkAI 共六家厂商。配好任意一家的 Key 即可使用，配多家可享受自动回退。
|
||||
|
||||
## 支持的模型
|
||||
|
||||
| 厂商 | 模型 / 别名 | 特点 |
|
||||
| --- | --- | --- |
|
||||
| OpenAI | `gpt-image-2`、`gpt-image-1` | 通用文生图，高质量，支持 `quality` 控制画质 |
|
||||
| Gemini Nano Banana | `nano-banana-2`、`nano-banana-pro`、`nano-banana` | 对应 `gemini-3.1-flash`、`gemini-3-pro`、`gemini-2.5-flash` 的图像版本 |
|
||||
| Seedream（火山方舟） | `seedream-5.0-lite`、`seedream-4.5` | 原生 2K–4K，最多 14 张图融合 |
|
||||
| Qwen（百炼） | `qwen-image-2.0`、`qwen-image-2.0-pro` | 擅长中文排版和图文融合 |
|
||||
| MiniMax | `image-01` | 简单快速 |
|
||||
| LinkAI | 任意模型 | 统一网关，作为兜底 |
|
||||
|
||||
## 模型选择
|
||||
|
||||
默认走「自动路由 + 失败回退」：
|
||||
|
||||
1. 按 `OpenAI → Gemini → Seedream → Qwen → MiniMax → LinkAI` 顺序选第一个已配置的厂商
|
||||
2. 遇到 401、模型未开通、网络异常等错误时，自动切到下一家
|
||||
3. 用户在对话里指定模型时（如「用 seedream 画一只猫」），对应厂商会被提到最前优先尝试
|
||||
|
||||
如需固定使用某个模型：
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": {
|
||||
"image-generation": {
|
||||
"model": "seedream-5.0-lite"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 配置 API Key
|
||||
|
||||
<Tip>
|
||||
推荐通过 [Web 控制台](/zh/channels/web) 的「模型管理」页面配置，配好的对话模型 Key 会被图像生成技能自动复用，无需重复配置。也可手动编辑配置文件或在对话中通过 `env_config` 工具临时设置。
|
||||
</Tip>
|
||||
|
||||
凭证统一复用主模型厂商的 Key：
|
||||
|
||||
| 字段 | 对应厂商 |
|
||||
| --- | --- |
|
||||
| `openai_api_key` | OpenAI |
|
||||
| `gemini_api_key` | Gemini |
|
||||
| `ark_api_key` | 火山方舟（Seedream） |
|
||||
| `dashscope_api_key` | 阿里百炼（Qwen） |
|
||||
| `minimax_api_key` | MiniMax |
|
||||
| `linkai_api_key` | LinkAI |
|
||||
|
||||
|
||||
## 开启和关闭
|
||||
|
||||
技能会根据 API Key 自动调整状态：
|
||||
|
||||
- **已配置 Key**：Agent 收到画图请求时直接调用
|
||||
- **未配置 Key**：技能仍会出现在上下文中（标记为「需要配置」），Agent 会引导用户去配 Key
|
||||
|
||||
如需手动控制：
|
||||
|
||||
```text
|
||||
/skill disable image-generation # 关闭
|
||||
/skill enable image-generation # 重新开启
|
||||
```
|
||||
|
||||
终端等价命令：`cow skill disable image-generation` / `cow skill enable image-generation`。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认 | 说明 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `prompt` | string | 是 | — | 图像描述 |
|
||||
| `image_url` | string / list | 否 | null | 编辑用的输入图，本地路径或 URL；传列表为多图融合 |
|
||||
| `quality` | string | 否 | auto | `low` / `medium` / `high`，仅部分厂商支持 |
|
||||
| `size` | string | 否 | auto | `512` / `1K` / `2K` / `3K` / `4K`，或像素值如 `1024x1024` |
|
||||
| `aspect_ratio` | string | 否 | null | `1:1` / `3:2` / `2:3` / `16:9` / `9:16` / `21:9`；Gemini 还支持 `1:4` / `4:1` / `1:8` / `8:1` |
|
||||
|
||||
<Warning>
|
||||
**质量越高、分辨率越大，耗时和成本越高。** 日常对话用默认（`auto`）或 `quality=low` + `size=1K` 即可，约 20 秒出图；做海报或明确要高清时再上 `high` + `2K/4K`，可能需要 1–5 分钟。
|
||||
</Warning>
|
||||
|
||||
## 常见用法
|
||||
|
||||
- **文生图**：根据描述生成插画、海报、图标、头像、分镜图等
|
||||
- **图生图**：在已有图片上改风格、换元素、加装饰、加文字等
|
||||
- **多图融合**：把多张参考图合成一张（换装、角色合影等）
|
||||
|
||||
<Note>
|
||||
- bash 超时建议设 600 秒：单厂商 HTTP 超时 300 秒，脚本可能依次尝试多家
|
||||
- 输入图片自动压缩到 4MB 以内、最长边不超过 4096px
|
||||
- Gemini / Seedream / Qwen / MiniMax 不支持 `quality` 参数
|
||||
- Seedream 默认出 2K 图；`seedream-5.0-lite` 支持到 3K，`seedream-4.5` 支持到 4K
|
||||
</Note>
|
||||
65
docs/zh/skills/index.mdx
Normal file
65
docs/zh/skills/index.mdx
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: 技能概览
|
||||
description: CowAgent 技能系统介绍
|
||||
---
|
||||
|
||||
技能（Skill）为 Agent 提供无限的扩展性。每个 Skill 由说明文件（`SKILL.md`）、运行脚本（可选）、资源（可选）组成，描述如何完成特定类型的任务。
|
||||
|
||||
Skill 与 Tool 的区别：Tool 是由代码实现的原子操作（如读写文件、执行命令），Skill 则是基于说明文件的高级工作流，可以组合调用多个 Tool 来完成复杂任务。
|
||||
|
||||
## 获取技能
|
||||
|
||||
CowAgent 提供多种方式获取技能：
|
||||
|
||||
- [Cow 技能广场](https://skills.cowagent.ai/) — 在线浏览所有可用技能，或通过 `/skill list --remote` 在对话中浏览和安装
|
||||
- **GitHub** — 直接从 GitHub 仓库安装，支持批量安装
|
||||
- **ClawHub** — 通过 `/skill install clawhub:名称` 安装 ClawHub 上的技能 (4w+个)
|
||||
- **LinkA** — 通过 `/skill install linkai:编码` 安装 LinkAI 上的公开资源和创建的知识库/数据库/工作流/插件等资源
|
||||
- **URL** — 从 zip 压缩包或 SKILL.md 链接安装
|
||||
- **对话创建** — 通过自然语言对话让 Agent 自动创建技能
|
||||
|
||||
详细安装方式参考 [安装技能](/zh/skills/install) 和 [技能管理命令](/zh/cli/skill)。也可以通过对话 [创建技能](/zh/skills/create)，或向 [Skill Hub](https://skills.cowagent.ai/submit) 贡献你的技能。
|
||||
|
||||
## 技能加载优先级
|
||||
|
||||
1. **工作空间技能**（最高）：`~/cow/skills/`
|
||||
2. **项目内置技能**（最低）：`skills/`
|
||||
|
||||
同名技能按优先级覆盖。
|
||||
|
||||
## 技能文件结构
|
||||
|
||||
```
|
||||
skills/
|
||||
├── my-skill/
|
||||
│ ├── SKILL.md # Skill description (frontmatter + instructions)
|
||||
│ ├── scripts/ # Execution scripts (optional)
|
||||
│ └── resources/ # Additional resources (optional)
|
||||
```
|
||||
|
||||
### SKILL.md 格式
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: Brief description of the skill
|
||||
metadata:
|
||||
emoji: 🔧
|
||||
requires:
|
||||
bins: ["curl"]
|
||||
env: ["MY_API_KEY"]
|
||||
primaryEnv: "MY_API_KEY"
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
Detailed instructions...
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `name` | 技能名称，需与目录名一致 |
|
||||
| `description` | 技能描述，Agent 据此决定是否调用 |
|
||||
| `metadata.requires.bins` | 依赖的系统命令 |
|
||||
| `metadata.requires.env` | 依赖的环境变量 |
|
||||
| `metadata.always` | 是否始终加载（默认 false） |
|
||||
66
docs/zh/skills/install.mdx
Normal file
66
docs/zh/skills/install.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 安装技能
|
||||
description: 通过命令一键安装来自多种来源的技能
|
||||
---
|
||||
|
||||
CowAgent 支持通过统一的 `install` 命令安装来自 [Cow 技能广场](https://skills.cowagent.ai/)、GitHub、ClawHub、LinkAI 以及任意 URL 上的技能。在对话中使用 `/skill install`，在终端中使用 `cow skill install`。
|
||||
|
||||
## 从Cow技能广场安装
|
||||
|
||||
访问 [skills.cowagent.ai](https://skills.cowagent.ai/) 浏览所有可用技能，找到想要的技能后直接安装，例如：
|
||||
|
||||
```text
|
||||
/skill list --remote
|
||||
/skill install pptx
|
||||
```
|
||||
|
||||
## 从 GitHub 安装
|
||||
|
||||
> Github上的所有技能都可以直接安装，支持仓库级批量安装和指定子目录安装，例如：
|
||||
|
||||
```text
|
||||
/skill install larksuite/cli
|
||||
/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im
|
||||
```
|
||||
|
||||
## 从 ClawHub 安装
|
||||
|
||||
[ClawHub](https://clawhub.ai/) 上的所有技能 (4w+个) 都可以一键安装，例如：
|
||||
|
||||
|
||||
```text
|
||||
/skill install clawhub:<name>
|
||||
```
|
||||
|
||||
## 从 LinkAI 安装
|
||||
|
||||
[LinkAI](https://link-ai.tech/console) 上的所有公开资源 (1w+个应用/工作流/插件) ，以及自己创建的资源 (应用/工作流/知识库/数据库/插件) 都可以通过命令一键安装：
|
||||
|
||||
```text
|
||||
/skill install linkai:<code>
|
||||
```
|
||||
|
||||
> LinkAI平台上创建的所有应用、工作流、知识库、数据库、插件都有唯一的code，可在[控制台](https://link-ai.tech/console)各资源页面中进行获取并填写到命令中
|
||||
|
||||
## 从 URL 安装
|
||||
|
||||
支持 zip 压缩包和 SKILL.md 文件链接：
|
||||
|
||||
```text
|
||||
/skill install https://cdn.link-ai.tech/skills/pptx.zip
|
||||
/skill install https://example.com/path/to/SKILL.md
|
||||
```
|
||||
|
||||
## 管理技能
|
||||
|
||||
```text
|
||||
/skill list # 查看已安装技能
|
||||
/skill info pptx # 查看技能详情
|
||||
/skill enable pptx # 启用技能
|
||||
/skill disable pptx # 禁用技能
|
||||
/skill uninstall pptx # 卸载技能
|
||||
```
|
||||
|
||||
<Tip>
|
||||
以上所有命令在终端中使用时，将 `/skill` 替换为 `cow skill` 即可。完整命令说明参考 [技能管理命令](/zh/cli/skill)。
|
||||
</Tip>
|
||||
112
docs/zh/skills/knowledge-wiki.mdx
Normal file
112
docs/zh/skills/knowledge-wiki.mdx
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: knowledge-wiki - 知识库
|
||||
description: 维护本地结构化知识库，自动归档、分类和交叉引用
|
||||
---
|
||||
|
||||
帮你把对话中产生的资料、灵感和零散笔记整理成结构化的本地知识库，自动维护索引和页面之间的交叉引用。
|
||||
|
||||
`knowledge-wiki` 在工作空间下维护一个 `knowledge/` 目录，相当于 Agent 的「外脑」。技能设置了 `always: true`，会**常驻上下文**，不需要任何外部依赖。
|
||||
|
||||
## 什么时候会触发
|
||||
|
||||
- 你分享了一篇文章、一份文档或一个 URL，想要沉淀下来
|
||||
- 聊天过程中聊出了值得长期保留的结论
|
||||
- 你想查一下之前积累过的知识
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
knowledge/
|
||||
├── index.md # 全局索引（必须维护）
|
||||
├── log.md # 操作日志（只追加）
|
||||
└── <category>/ # 分类子目录（按内容自由分组）
|
||||
└── <slug>.md # 知识页（文件名用小写加中划线）
|
||||
```
|
||||
|
||||
## 三个核心操作
|
||||
|
||||
### 1. 收录（Ingest）
|
||||
|
||||
你分享了一段资料时，Agent 会：
|
||||
|
||||
1. 读懂原文，提取关键信息
|
||||
2. 按内容决定放到哪个分类下——先看 `index.md` 里有没有合适的分类，没有就新建一个
|
||||
3. 生成知识页 `knowledge/<category>/<slug>.md`
|
||||
4. 更新索引 `index.md` 和日志 `log.md`
|
||||
|
||||
### 2. 综合（Synthesize）
|
||||
|
||||
聊天中产生了新的结论或洞见时：
|
||||
|
||||
1. 在合适的分类下创建新知识页
|
||||
2. 给相关的已有页面加上互相指向的链接
|
||||
3. 更新索引和日志
|
||||
|
||||
### 3. 查询（Query）
|
||||
|
||||
你问到以前积累的知识时：
|
||||
|
||||
1. 先从 `index.md` 里找可能相关的页面
|
||||
2. 用 `read` 工具打开具体页面
|
||||
3. 需要时再用 `memory_search` 补充检索
|
||||
4. 回答里会带上知识页的链接，方便你点过去看原文
|
||||
|
||||
## 知识页怎么写
|
||||
|
||||
```markdown
|
||||
# 页面标题
|
||||
|
||||
> Source: <来源 URL 或简要说明>
|
||||
|
||||
正文内容。页面之间用相对路径链接：
|
||||
[相关页](../category/related-page.md)
|
||||
|
||||
## 要点
|
||||
|
||||
- ...
|
||||
|
||||
## 相关页面
|
||||
|
||||
- [页面 A](../category/page-a.md) — 为什么相关
|
||||
```
|
||||
|
||||
<Note>
|
||||
- `> Source:` 用来记录这条知识的来源。有明确来源时一定要写
|
||||
- 交叉引用很重要：创建或更新某页时，记得也去关联页面里补上反向链接
|
||||
- **只链接已经存在的页面**。如果某个概念值得单独成页，先建好再加链接
|
||||
</Note>
|
||||
|
||||
## 索引格式
|
||||
|
||||
`knowledge/index.md` 采用扁平列表，按分类分组，每个知识页占一行：
|
||||
|
||||
```markdown
|
||||
# Knowledge Index
|
||||
|
||||
## 分类 A
|
||||
- [页面标题](category-a/page-slug.md) — 一句话摘要
|
||||
|
||||
## 分类 B
|
||||
- [页面标题](category-b/page-slug.md) — 一句话摘要
|
||||
```
|
||||
|
||||
不用表格，不加 emoji。分类怎么起名、怎么组织都可以灵活调整。
|
||||
|
||||
## 日志格式
|
||||
|
||||
`knowledge/log.md` 只追加、不修改，最新的写在最下面：
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD] ingest | 页面标题
|
||||
## [YYYY-MM-DD] synthesize | 页面标题
|
||||
```
|
||||
|
||||
## 写作约定
|
||||
|
||||
- **文件名**用小写加中划线，比如 `machine-learning.md`
|
||||
- **一页只讲一件事**，需要关联的内容通过链接串起来
|
||||
- **有了就更新，不要重复建页**
|
||||
- **每次改完都要更新索引** `knowledge/index.md`
|
||||
- **写精华别抄全文**，抓住要点就行
|
||||
- **对话里引用知识页时用完整路径**，比如 `[标题](knowledge/<category>/<slug>.md)`。页面之间互相链接才用相对路径
|
||||
- **基于知识页回答问题时附上链接**，方便深入查阅
|
||||
180
docs/zh/skills/skill-creator.mdx
Normal file
180
docs/zh/skills/skill-creator.mdx
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: skill-creator - 技能创建
|
||||
description: 创建、安装、更新技能，规范 SKILL.md 写法与目录结构
|
||||
---
|
||||
|
||||
`skill-creator` 是一个「元技能」，专门用来帮助 Agent 创建、安装和更新其他技能，确保所有技能的 `SKILL.md` 写法和目录结构保持一致。
|
||||
|
||||
## 什么时候会触发
|
||||
|
||||
- 用户想从 URL 或远程仓库安装一个技能
|
||||
- 用户想从头创建一个全新的技能
|
||||
- 需要升级或重构已有技能
|
||||
|
||||
## 技能是什么
|
||||
|
||||
简单来说，技能就是一份「可复用的说明书」加上可选的脚本和资源。它给 Agent 注入了某个领域的专业知识，让 Agent 在遇到对应任务时能像专家一样处理。
|
||||
|
||||
一个技能通常包含以下内容：
|
||||
|
||||
1. **专项工作流** — 某类任务的完整步骤
|
||||
2. **工具用法** — 怎么调某种 API 或处理某种文件
|
||||
3. **领域知识** — 团队约定、业务规则、数据结构之类
|
||||
4. **附带资源** — 脚本、参考文档、模板等
|
||||
|
||||
<Note>
|
||||
**核心原则：能省则省**。只写 Agent 自己想不到的内容，每加一行都要问自己：值不值得占这些 token？
|
||||
</Note>
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # 必需：技能定义
|
||||
│ ├── YAML frontmatter（必填 name / description）
|
||||
│ └── Markdown 正文（说明 + 示例）
|
||||
└── 可选资源
|
||||
├── scripts/ # 可执行脚本（Python / Bash 等）
|
||||
├── references/ # 内容较多的参考文档，Agent 按需读取
|
||||
└── assets/ # 模板、图标等，会直接用在输出里
|
||||
```
|
||||
|
||||
## SKILL.md 规范定义
|
||||
|
||||
SKILL.md 文件头部的 `frontmatter` 字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `name` | 技能名，小写加中划线，必须和目录名一致 |
|
||||
| `description` | **最关键的字段**。写清楚「这个技能干什么」和「什么情况下该用它」，Agent 看到这段来决定要不要调它。注意：所有触发相关的描述都放在这里，不要写到正文里 |
|
||||
| `metadata.cowagent.requires.bins` | 系统里必须装了哪些命令行工具 |
|
||||
| `metadata.cowagent.requires.env` | 需要哪些环境变量（全部满足才行） |
|
||||
| `metadata.cowagent.requires.anyEnv` | 多个 API Key 满足一个就行 |
|
||||
| `metadata.cowagent.requires.anyBins` | 多个工具满足一个就行 |
|
||||
| `metadata.cowagent.always` | 设为 `true` 会始终加载，不检查依赖 |
|
||||
| `metadata.cowagent.emoji` | 展示用的 emoji（可选） |
|
||||
| `metadata.cowagent.os` | 限定系统，如 `["darwin", "linux"]` |
|
||||
|
||||
<Note>
|
||||
`category` 字段不需要手写，系统会自动设成 `skill`。
|
||||
</Note>
|
||||
|
||||
声明 API Key 依赖有两种写法：
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
cowagent:
|
||||
requires:
|
||||
env: ["MYAPI_KEY"] # 必须有
|
||||
```
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
cowagent:
|
||||
requires:
|
||||
anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"] # 有一个就行
|
||||
```
|
||||
|
||||
**技能会自动按依赖启禁用**：环境变量齐了就自动启用，缺了就自动禁用，不需要手动 `/skill enable`。
|
||||
|
||||
## 资源目录怎么用
|
||||
|
||||
| 目录 | 放什么 | 不要放 |
|
||||
| --- | --- | --- |
|
||||
| `scripts/` | 需要反复执行的代码，或需要确定性结果的脚本 | 纯演示用的代码片段 |
|
||||
| `references/` | **超过 500 行**、SKILL.md 实在塞不下的大文档（比如完整的数据库 Schema） | 普通 API 文档、示例、教程 |
|
||||
| `assets/` | 会出现在最终产物里的文件（模板、图标、样板代码等） | 说明性文档 |
|
||||
|
||||
<Warning>
|
||||
**原则上所有内容都写在 `SKILL.md` 里**，只有确实放不下才拆到资源目录。
|
||||
|
||||
不要给技能加 `README.md`、`CHANGELOG.md`、`INSTALLATION_GUIDE.md` 之类的文件——全部放进 `SKILL.md`。资源目录里只放真正要跑的脚本或真正要用的素材。
|
||||
</Warning>
|
||||
|
||||
## 安装外部技能
|
||||
|
||||
安装后最终落在 `<workspace>/skills/<name>/` 目录。
|
||||
|
||||
| 来源 | 怎么装 |
|
||||
| --- | --- |
|
||||
| URL（单文件） | curl / web_fetch 直接拉 |
|
||||
| URL（zip 包） | 下载解压 |
|
||||
| 本地 SKILL.md | 直接读 |
|
||||
| 本地 zip 包 | 解压 |
|
||||
|
||||
安装步骤：
|
||||
|
||||
1. 找到 `SKILL.md`（可能在包的根目录或某个子目录里）
|
||||
2. 从 frontmatter 里读出 `name`
|
||||
3. 把**整个技能目录**（包括 `SKILL.md`、`scripts/`、`assets/` 等）复制到 `<workspace>/skills/<name>/`
|
||||
4. 如果包里有 `INSTALL.md` 之类的安装脚本，照着跑一遍，但最终结果仍然要落在 `<workspace>/skills/<name>/` 下
|
||||
|
||||
## 从头创建技能
|
||||
|
||||
推荐按这个顺序来：
|
||||
|
||||
1. **搞清楚需求** — 让用户举几个具体的使用场景，一次别问太多
|
||||
2. **想好结构** — 这个技能需要脚本吗？需要参考文档吗？需要模板素材吗？
|
||||
3. **生成骨架** — 用初始化脚本：
|
||||
|
||||
```bash
|
||||
scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
|
||||
```
|
||||
|
||||
4. **填充内容** — 写好 SKILL.md、补上脚本和资源。脚本写完一定要实际跑一遍
|
||||
5. **格式校验**（可选）：
|
||||
|
||||
```bash
|
||||
scripts/quick_validate.py <workspace>/skills/<skill-name>
|
||||
```
|
||||
|
||||
6. **迭代完善** — 实际用起来之后根据反馈持续改进
|
||||
|
||||
## 命名规则
|
||||
|
||||
- 只用小写字母、数字和中划线。用户给的名字需要做标准化处理，比如 `Plan Mode` → `plan-mode`
|
||||
- 长度别超过 64 个字符
|
||||
- 尽量短、用动词开头、一看就知道干什么
|
||||
- 必要时用工具名做前缀，比如 `gh-address-comments`、`linear-address-issue`
|
||||
- 目录名和 `name` 字段必须完全一致
|
||||
|
||||
## 三级加载机制
|
||||
|
||||
技能不会一次性全部塞进上下文，而是分三级按需加载：
|
||||
|
||||
1. **元信息**（`name` + `description`）— 常驻上下文，约 100 词。Agent 靠它判断「要不要用这个技能」
|
||||
2. **SKILL.md 正文** — 确定要用了才加载，建议控制在 500 行以内
|
||||
3. **资源文件** — Agent 需要的时候再读
|
||||
|
||||
如果一个技能涉及多个变体（比如多云厂商部署），建议这样组织：
|
||||
|
||||
```
|
||||
cloud-deploy/
|
||||
├── SKILL.md # 主流程和厂商选择逻辑
|
||||
└── references/
|
||||
├── aws.md
|
||||
├── gcp.md
|
||||
└── azure.md
|
||||
```
|
||||
|
||||
用户选了 AWS，Agent 只需要读 `aws.md`，不用把三家的文档全加载进来。
|
||||
|
||||
## 常见设计模式
|
||||
|
||||
**步骤式**：按编号列出操作步骤和对应脚本。
|
||||
|
||||
```markdown
|
||||
1. 分析表单结构（运行 analyze_form.py）
|
||||
2. 生成字段映射（编辑 fields.json）
|
||||
3. 自动填充表单（运行 fill_form.py）
|
||||
```
|
||||
|
||||
**分支式**：根据用户意图走不同流程。
|
||||
|
||||
```markdown
|
||||
1. 判断操作类型：
|
||||
**新建内容？** → 走「创建流程」
|
||||
**编辑已有内容？** → 走「编辑流程」
|
||||
```
|
||||
|
||||
**模板式**：输出格式有严格要求时，在 SKILL.md 里直接给一个样板，让 Agent 照着写。
|
||||
Reference in New Issue
Block a user