文档

简体中文

English

简体中文

English

切换主题

社区版开源 Web · 0.2.2 发行文档 · 0.2.2内容核对：2026-10-18查看 Markdown

6.3 编写第一份技能 ​

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

最小格式 ​

目录中放置 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.* 等规则标识报告。

下载完整通用研究示例包，其中包含合法技能、岗位、资料与任务模板。包中列出的关联不自动授予工具权限。