技能

技能（Skill）是一种能力封装机制，用于将专业知识（如编码经验、常见问题、解决方案等）组织为可复用的模块。技能本质上是由指令、脚本和资源构成的集合，智能体可按需动态加载这些专业化的“技能包”，从而提升特定任务的执行能力与执行效率。

表1 技能与其他功能的对比
对比维度	技能（Skill）	MCP Server
定义	用于描述如何完成特定任务。	提供外部工具的调用能力。
加载方式	按需加载，减少上下文占用。	不参与推理过程，按需调用外部接口。
使用场景	封装测试流程、开发任务、复杂业务逻辑等。例如：执行UI自动化测试。	连接外部系统，执行具体操作。例如：控制浏览器操作。
关键区别	解决“如何完成任务”，是流程指导。	提供“调用工具的能力”，是执行能力。

技能的目录结构

技能是一个包含必需的SKILL.md文件和其他可选的捆绑资源的结构化目录，打包完成特定任务所需的知识和工具。

skill-name/
├── SKILL.md (必填)
│   ├── YAML frontmatter 元数据 (必填)
│   │   ├── name: (必填)
│   │   └── description: (必填)
│   └── Markdown 指令 (必填)
└── Bundled Resources/ 捆绑资源 (选填)
    ├── scripts/      - 可执行代码 (Python/Bash 等)
    ├── references/   - 旨在根据需要加载到上下文中的文档
    └── assets/       - 输出中使用的文件 (模板、图标、字体等)

表2 技能参数说明
参数名称	说明
skill-name	整个技能的根目录，skill-name需要替换成实际的技能名称（比如data-analysis-skill）。技能名称由小写字母、数字和连字符（-）组成，开头和结尾不能是连字符，且连字符不可连续使用，长度1~64字符。
SKILL.md	SKILL.md文件名不可修改。它是技能的核心描述文件，相当于技能的“说明书”，必须包含以下两部分： YAML frontmatter元数据：放在SKILL.md文件的最顶部，以“---”首尾包裹，是AI可解析的结构化信息。包含name和description两个字段。 name：技能名称，由小写字母、数字和连字符（-）组成，开头和结尾不能是连字符，且连字符不可连续使用，长度1~64字符。name必须与skill-name保持一致。 description：技能描述，长度不超过1024字符。该字段对码道Agent Space识别技能的使用场景至关重要，需清晰描述技能功能及适用触发条件。 Markdown指令：YAML元数据下方的Markdown内容，用于详细说明技能的使用方法、参数、示例和依赖等。
Bundled Resources（可选）	存放技能配套资源的目录，非必填，但能让技能更完整。 scripts/：存放技能的可执行脚本，例如Python脚本、Shell脚本等，实现确定性操作。 references/：存放技能依赖的参考文档，例如API文档、领域知识、公司政策等，是给智能体的知识库，这些文档会在技能执行时按需加载到上下文。 assets/：存放资源文件，例如字体资源、公司Logo、PPT模板等，直接在智能体生成的输出中使用，不需要被加载到上下文窗口。

编写SKILL.md

创建一个带有YAML frontmatter和Markdown内容的SKILL.md文件，样例如下：

---
name: safe-file-reader
description: Read files without making changes. Use when you need read-only files access.
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions

1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern

添加支持文件

在SKILL.md同级目录下创建其他文件，样例如下：

my-skill/
├── SKILL.md
├── reference.md
├── examples.md
├── scripts/
│   └── helper.py
└── templates/
    └── template.txt

在SKILL.md中写明引用这些支持文件，样例如下：

For advanced usage, see [reference.md](reference.md).

Run the helper script:
```bash
python scripts/helper.py input.txt
```

创建个人级技能

在码道Agent Space中仅支持创建个人级技能。个人级技能针对当前用户下的所有项目生效，存储在本地“~/.codeartsdoer/skills”目录下。除直接创建技能外，您还可通过导入现有文件来快速集成技能。

根据您的使用习惯和偏好设定个人级技能，码道Agent Space将始终遵循这些技能，在所有项目中为您提供更贴合个人风格的输出。个人级技能创建后立刻生效，何时使用由智能体决定。

单击码道Agent Space页面右上角的设置图标，进入设置页面。
在左侧导航栏选择“技能”，进入个人级页面。
在“个人级”页签中，单击技能后的，进入创建技能页面。

参考表3，设置个人级技能参数。

图1 创建个人级技能
点击放大

表3 个人级技能参数说明
参数	说明
Skill名称	新建个人级技能的名称。命名规则：由小写字母、数字和连字符（-）组成，开头和结尾不能是连字符，且连字符不可连续使用，长度1~64字符。
Skill描述	技能的描述信息，长度不超过1024字符。
指令	技能的指令，用于详细说明技能的使用方法、参数、示例和依赖等。长度不超过50000字符。

单击“确定”，完成技能的创建。

在“个人级”页签中，可查看到新创建的个人级技能。个人级技能创建完成后，默认为开启状态，存放路径为“本地的~/.codeartsdoer/skills”。

图2 查看技能

将已获取的本地技能包导入到码道Agent Space中，即可便捷地调用和使用相关功能。

导入前，请对照技能的目录结构及编写SKILL.md中内容，验证技能包是否符合标准。例如，每个技能文件夹的根目录均须包含对应的SKILL.md文件，此文件中须包含YAML格式的技能名称与描述等。如果技能包不符合规范，请调整后再导入，否则可能会导入失败。

单击码道Agent Space页面右上角的设置图标，进入设置页面。
在左侧导航栏选择“技能”，进入个人级页面。
在“个人级”页签中，单击技能后的“ > 导入”。
在“上传”对话框中，选择本地的技能zip包，单击“确定”。

每次仅支持上传一个zip包，包内可存放多个技能文件夹，且包的总大小不能超过5M。

导入成功后，技能名称将显示在技能列表中。

例如：如需一次性导入“docx”和“pptx”两类技能至码道Agent Space，可将两类技能文件夹放入同一个zip包中，再上传该zip包，即可实现批量上传功能。

图3 批量上传多个技能

使用技能

参考开启码道Agent Space操作，进入码道Agent Space。
通过以下任一方式激活技能。
- 通过输入技能名称调用技能。在聊天窗口的输入框中，输入相关内容（包含技能名），单击发送图标。
  图4 通过名称调用技能
- 通过“/”命令调用技能。通过“/”命令调用技能前，需确保该技能处于“启用”状态。输入框中一次最多支持选择20个技能。
  在聊天窗口的输入框中，输入“/”，在弹出的菜单中选择“/summarize-skill”，输入相关内容，然后单击发送图标。
  
  图5 通过“/”调用技能
查看技能调用结果。

图6 技能调用结果

管理技能

表4 管理技能
操作	具体步骤
启用或禁用技能	在码道Agent Space设置页面的“技能 > 个人级”页签中，可通过开关启用或禁用技能。
批量启用或禁用技能	在码道Agent Space设置页面的“技能 > 个人级”页签中，单击右上角的“ > 批量操作”。勾选目标技能，单击右上角的“开启”或“关闭”，批量启用或禁用技能。
查看技能	在码道Agent Space设置页面的“技能 > 个人级”页签中，将鼠标悬浮在目标技能上，单击，即可查看技能详情。
编辑技能	在码道Agent Space设置页面的“技能 > 个人级”页签中，将鼠标悬浮在目标技能上，单击，即可对技能进行修改。
删除技能	在码道Agent Space设置页面的“技能 > 个人级”页签中，将鼠标悬浮在目标技能上，单击，即可删除技能。目标技能从技能列表中移除，表示技能删除成功。注意：技能删除后，使用该技能的智能体将受到影响，且删除的技能不可恢复，请谨慎操作。