---
title: 编写第一份技能
description: 用 SKILL.md 定义可执行、可复核的方法。
lastVerified: 2026-10-18
---

# 6.4 编写第一份技能

技能是方法说明，不是工具权限或模型权重。先选择一项范围明确、能够检查结果的工作。

## 最小格式

目录中放置 `SKILL.md`，使用 UTF-8：

```markdown
---
name: research-brief
description: 根据已授权资料生成带来源的研究简报，区分事实、推断和待核实项。
---

# 研究简报

1. 写明问题、读者和截止时间。
2. 每条事实附来源；没有依据则标记待核实。
3. 单独列推断、分歧与不确定性。
4. 给出结论和核验清单，不执行对外发送。
```

`name` 使用小写英文字母、数字和单个连字符分隔，例如 `research-brief`。不要用中文、空格、下划线或文件名代替技能标识；名称必须与导入时填写的技能身份一致。界面显示标题可以使用中文。

## 导入并验证

在 **市场** 或 **应用** 右上角点 **+ > 导入技能**，选择包含 `SKILL.md` 的单个技能目录。名称和标识会从 `SKILL.md` 读出；需要修改时展开 **名称与版本**，填写资源标识 `research-brief`、名称“研究简报”、锁定版本 `1.0.0`。点 **保存技能内容** 后，在资源页核对说明与正文。

导入后打开技能详情，按状态完成安装或启用。先暂停研究员工，再修改配置并关联该技能，完成后恢复在岗。回到能力页检查状态；导入目录、安装到运行环境与岗位关联是不同步骤。

为员工提供一段虚构资料并要求使用技能。检查输出是否真的区分事实与推断、是否保留来源，以及是否没有擅自调用外部工具。

## 更新与失败

更新技能时提高版本，并检查引用它的任务模板是否仍锁定旧版本。若导入被拒绝，先检查 frontmatter、身份一致性、目录边界和编码。

## 外部仓库技能的许可文件

市场维护者收录 GitHub 技能时，需要锁定仓库提交，以及每个文件的 SHA-256 摘要、Git blob 摘要和字节数。SHA-256 由生成器按研究缓存中锁定的字节计算；Git blob 只用于在 GitHub 树中定位。添加和安装时逐文件下载后核对，任一不符都会拒绝。许可文件位于仓库根目录或技能的祖先目录时，不能因只下载技能子目录而漏掉它。

新增的目录协议在 `upstream.files` 中用 `repositoryPath` 指明许可原路径，`path` 必须为 `licenses/upstream/<repositoryPath>`；同时将安装路径列入 `license.files`。例如仓库根 `LICENSE` 安装为 `licenses/upstream/LICENSE`，与技能自己的 `LICENSE` 分开保留。根目录或祖先目录的 `NOTICE` 也按同样方式锁定，不改写文件内容。

该映射仅支持 LICENSE、LICENCE、NOTICE、COPYING 及其 `.txt`、`.md`、`.rst` 文件，以及 `THIRD_PARTY_NOTICES.md`；不接受其他技能、脚本、链接或任意 URL。目录中的文件路径不能包含 C1 控制字符、行分隔符或双向文字控制符。更换原路径、提交、摘要或大小会改变确认卡上的校验值，需要重新核对。生成器缺少锁定的许可文件时拒绝生成；已有资源不会自动升级。此能力包含在 alpha.7 中；具体资源仍须在市场源仓审核并固定版本后收录。

## 二次开发资源

资源文件相对原版有任何改动（修复、删减、适配、新增文件、优化或本地化）时，以市场保存的文件上架：资源用 `delivery: "install"`，带锁定出处 `upstream` 与修改清单 `derivation`。`delivery: "upstream"` 的原版资源只用于未改动的原版：所列文件按锁定摘要逐文件从原始来源拉取，它的 `modifications` 只用来说明未收录哪些文件。改过任何字节的资源都不能写成原版资源。

`derivation` 有两个字段：`unchangedFiles` 列出与原版逐字节一致的文件，资源文件里它们的摘要必须等于 `upstream.files` 中锁定的 `sha256`；`changes` 是 1–200 条修改。每条修改包括：

- `id`：资源内唯一的编号，例如 `CSB-M01`。
- `type`：七类之一。一条修改同时符合多类时取靠前的一类：`security`（安全修复）、`fixed`（修复）、`removed`（移除）、`adapted`（适配）、`added`（新增）、`improved`（优化）、`localized`（本地化）。
- `path`：资源文件里的文件路径；删除整个原版文件时写原版文件路径。小节或行号放在可选的 `section`。
- `upstream`：`<owner>/<repo>@<40 位提交>:<仓库内路径>`，必须指向本资源锁定的同一仓库、同一提交里的某个原版文件；原版没有的新文件写 `null`。
- `summary` 与 `reason`：中英文各一份，每种语言不超过 1000 字，会在市场里展示。

有 `derivation` 时 `modifications` 必须为空，`upstream.files` 每项都要带 `sha256`。资源文件里除 `unchangedFiles` 和根目录 `MODIFICATIONS.md` 外，每个文件都要被至少一条修改的 `path` 引用；原版里没有随附的文件都要有一条 `removed` 修改。许可文件不例外：原样随附就写进 `unchangedFiles`。文件路径只差大小写的会被拒收（不区分大小写的文件系统上会互相覆盖）。原版仓库根目录的许可文件用 `repositoryPath` 指明，放到资源根目录的 `LICENSE` 或 `LICENSE.txt`。

资源根目录放 `MODIFICATIONS.md`，写明每条修改的编号与完整技术说明。每个改过或新增的文件，前 4 KiB 内要出现 `MODIFICATIONS.md` 字样，例如在 `SKILL.md` 正文开头写一行“Modified by Teloa; see MODIFICATIONS.md”。这满足 Apache-2.0 第 4(b) 条对被修改文件带显著修改声明的要求，对其他许可同样适用。

我方修改的验证记录放在市场仓 `reviews/derivatives/<id>@<version>.json`：

```json
{"format":"teloa.derivative-review/v1","entryId":"openai.security-best-practices","version":"1.0.0","reviewedAt":"2026-09-28","reviewer":"Teloa",
 "changeChecks":[{"changeId":"CSB-M01","method":"test","result":"pass","evidence":"……"}]}
```

每条修改恰有一条检查，`result` 只能是 `pass`；`method` 为 `test`、`reproduction`、`source-check` 或 `review`，`security` 与 `fixed` 不能只用 `review`；`evidence` 不超过 1000 字。验证记录是审查证据，不进目录资源，也不在界面展示。

用到 `derivation`、安装型资源原版文件的 `sha256` 或 `repositoryPath`、原版资源的安装量来源 `origin.installsSource` 之一的资源，`compatibility.teloa` 的下界必须不低于 `0.2.0-alpha.7`，这些资源只进新版索引。原版资源写了非 ClawHub 的安装量时必须给出来源（`url` 为公开的 https 地址，`scope` 为 `resource` 或 `plugin`，`countedAt` 即抓取日期）；没有安装量时不写来源。市场仓校验器 `node tools/validate.mjs` 逐项核对以上规则，问题以 `derivative.*` 等规则标识报告。

[下载完整通用研究示例包](https://docs.teloa.ai/v/0.2.4/examples/general-research.zip)，其中包含合法技能、岗位、资料与任务模板。包中列出的关联不自动授予工具权限。