CODEAGENT / SKILLS

Skill 开发指南

Skill 是可以复用的任务说明。它告诉 Agent 何时采用一个流程，以及怎样交付可检查的结果。

创建你的第一个 Skill

创建 review-workflow/SKILL.md，保存为 UTF-8 文本。下载示例后可以直接从“技能”页导入文件。

SKILL.md

---
manifestVersion: 1
name: review-workflow
description: 当用户需要检查代码修改、查找回归风险或审查实现时使用。
tools: []
permissions: []
---

# 代码审查流程

1. 确认用户要审查的范围；使用当前任务已允许的读取工具了解修改与相关代码。
2. 优先检查错误处理、边界条件与调用方，并给出文件位置和触发条件。
3. 说明已经验证的内容与尚未验证的内容；需要写入或执行命令时遵守当前任务的权限。

如果当前任务没有所需工具，说明缺少什么，不要编造检查结果。

下载这个示例

示例没有申请额外权限。工作流程使用当前任务已经允许的工具，不会自行授予读取、写入或执行权限。

Front matter 字段

文件开头使用一对 --- 包围元数据；推荐采用下面的简单字段和 JSON 字符串数组。当前解析器只支持受限的平面 YAML，不支持嵌套对象和多行 YAML 字符串。

字段	含义与限制
`manifestVersion`	可选；当前版本为 `1`。
`name`	使用 front matter 时必填，最多 120 字符。
`description`	可选，最多 2,000 字符；写清触发场景。
`tools`	可选，最多 32 个工具名称；使用 `["tool_name"]` 或 YAML 列表。工具仍须在当前任务中可用。
`permissions`	可选，使用支持的权限名称数组；声明不等于授权。
`license`、`compatibility`、`allowed-tools`	可读取的兼容元数据；`allowed-tools` 不会转换为 CodeAgent 的执行工具白名单，也不会授予权限。

未列出的 front matter 字段会被拒绝。无 front matter 的普通 Markdown 仍可读取，工具和权限声明为空。

目录与资源

项目内的 Skill 目录

.codeagent/
  skills/
    review-workflow/
      SKILL.md
      references/
        checklist.md

也可以从桌面端导入包含根级 SKILL.md 的文件夹。补充资源可以放在文件夹中，并在指令里写清用途；它们不会因为随包导入而自动执行。单个 SKILL.md 最大 64 KiB，指令正文最多 40,000 字符。

文件夹导入最多 128 个常规文件、总计 8 MiB、8 层子目录，不接受符号链接；ZIP 包请先解压再导入。项目最多发现 64 个外部 Skill。

写清触发条件与交付标准

description 写“什么时候用”，正文写“如何做”，避免只写角色口号。
为关键步骤写输入、检查方法和结果格式；把较长材料放入 references。
工具名称应来自目标环境；不要把其他产品的专有工具名当作通用能力。
遇到缺少工具、凭据或权限时说明缺项；不要把 Skill 当作新的授权来源。

内置 Skill 已随客户端提供，不需要重复导入。外部 Skill 需要审查并启用后才加入任务上下文。

导入失败时检查什么

现象	处理方法
Unsupported Skill field	删除或转换不支持的元数据字段。
unsupported YAML syntax	把嵌套或多行字段改成简单的一行文本；数组采用 JSON 字符串数组或 YAML 列表。
missing its closing delimiter	补齐 front matter 的结束 `---`。
导入成功但没有使用	检查是否已启用、任务是否符合描述、项目是否正确，以及当前任务的工具权限。
内容修改后需要再次审查	确认变更内容后重新审查并启用，这是内容摘要校验的正常行为。