技能管理

什么是技能(Skills)？

技能(Skills)是包含指令、脚本和资源的文件夹，智能体可以动态加载它们来提升在专门任务上的性能。技能教会智能体如何以可重复的方式完成特定任务，无论是按照公司的品牌指南创建文档、使用组织的特定工作流程分析数据，还是自动化个人任务。

Agent Skills 规范作为开放标准发布于 agentskills.io，Nuwax AgentOS 已完全适配 Skills。

技能类型

1. 官方技能（支持Anthropic提出的技能规范）

由官方创建和维护的技能，例如针对 Excel、Word、PowerPoint 和 PDF 文件的增强文档创建。官方技能对所有用户开放，你可以在官方网站模板广场下载，然后导入到你的 NuwaxOS 中。

2. 自定义技能

由您或您的组织为专门的工作流程和特定领域任务创建的技能。以下是使用自定义技能可以实现的一些工作流程：

• 将品牌样式指南应用于文档和演示文稿
• 按照公司电子邮件模板生成通信内容
• 使用公司特定的格式构建会议纪要
• 按照团队约定在公司工具（JIRA、Asana、Linear）中创建任务
• 执行公司特定的数据分析工作流程
• 自动化个人工作流程

3. 组织配置技能

对于团队或各类组织，您可以使用 Nuwax 来统一管理和分发技能：

• 在所有员工中一致地分发批准的工作流程
• 确保团队使用标准化的程序和最佳实践
• 部署新功能而无需个人单独上传

技能的主要优势

• 特定任务性能提升：技能为文档创建、数据分析和需要补充智能体通用知识的特定领域工作提供专业能力。

• 组织知识捕获：将您公司的工作流程、最佳实践和机构知识打包，供智能体在整个团队中一致地使用。

• 易于定制：任何人都可以通过在 Markdown 中编写指令来创建技能——简单的技能不需要编码，尽管您可以为自定义技能附加可执行脚本以实现更高级的功能。

• 组织的集中管理：使用 Nuwax 可以在全组织范围内配置技能，确保跨团队的一致工作流程，而无需每个用户单独设置。

技能与其他功能的对比

技能 vs MCP（模型上下文协议）

MCP 可以连接到外部服务和数据源。技能提供程序性知识——关于如何完成特定任务或工作流程的指令。您可以同时使用两者：MCP 连接为智能体提供对工具的访问，而技能教会智能体如何有效地使用这些工具。

创建你的第一个技能

让我们创建一个简单的技能，教智能体用可视化图表和类比来解释代码。

步骤 1：创建技能

在你的工作空间技能管理中创建一个新技能：

选择创建技能

步骤 2：编写 SKILL.md

每个技能都需要一个 SKILL.md 文件。文件以 --- 标记之间的 YAML 元数据开头，必须包含 name 和 description，后面是智能体在技能激活时遵循的 Markdown 指令。

在你创建的技能中编辑 SKILL.md 文件，其余目录选择性使用即可。

---
name: explaining-code
description: 用可视化图表和类比解释代码。在解释代码如何工作、教授代码库知识或用户询问"这是如何工作的"时使用
---

# 代码解释技能

当解释代码时，始终包含：

1. **以类比开始**：将代码与日常生活中的事物进行比较
2. **绘制图表**：使用 ASCII 艺术展示流程、结构或关系
3. **逐步讲解**：解释每一步发生了什么
4. **强调陷阱**：常见的错误或误解是什么？

保持对话式的解释风格。对于复杂概念，使用多个类比。

当你编辑好你的技能后，点击右上角的发布按钮，可以发布分享到你的团队空间，其他成员也可以在自己的智能体中引用该技能。

步骤 3：验证技能

让我们创建一个通用型的智能体来验证技能。

在智能体中添加技能

在弹出框中选择刚刚添加的技能

在对话框中输入：

有哪些可用的技能？

你应该在列表中看到 explaining-code 及其描述。

步骤 4：测试技能

上传一个代码文件并向智能体提出与技能描述匹配的问题：

这段代码是如何工作的？

智能体应该请求使用 explaining-code 技能，然后在其解释中包含类比和 ASCII 图表。

完整内容输出效果

技能的详细工作原理

技能是模型调用的：智能体根据你的请求决定使用哪些技能。你不需要显式调用技能。当你的请求匹配技能的描述时，智能体会自动应用相关技能。

工作流程

1. 发现阶段

启动时，智能体只加载每个可用技能的名称和描述。这样可以保持启动快速，同时给智能体足够的上下文来了解每个技能何时可能相关。

2. 激活阶段

当你的请求匹配技能的描述时，智能体会请求使用该技能。在完整的 SKILL.md 加载到上下文之前，你会看到一个确认提示。

3. 执行阶段

智能体遵循技能的指令，根据需要加载引用的文件或运行绑定的脚本。

配置技能

SKILL.md 文件结构

SKILL.md 文件是技能中唯一必需的文件。它有两个部分：顶部的 YAML 元数据（--- 标记之间的部分），以及告诉智能体如何使用技能的 Markdown 指令。

---
name: your-skill-name
description: 该技能的功能以及何时使用的简要描述
---

# 你的技能名称

## 指令
为智能体提供清晰、分步骤的指导。

## 示例
展示使用此技能的具体示例。

可用的元数据字段

你可以在 YAML frontmatter 中使用以下字段：

字段	必需	描述
name	是	技能名称。只能使用小写字母、数字和连字符（最多 64 个字符）。应与目录名匹配。
description	是	技能的功能以及何时使用（最多 1024 个字符）。智能体使用此字段来决定何时应用该技能。

添加支持文件（渐进式披露）

技能与智能体的上下文窗口共享对话历史、其他技能和你的请求。为了保持上下文专注，使用渐进式披露：将基本信息放在 SKILL.md 中，将详细参考资料放在单独的文件中，智能体只在需要时读取。

这种方法允许你捆绑全面的文档、示例和脚本，而不会预先消耗上下文。智能体仅在任务需要时加载额外的文件。

保持 SKILL.md 在 500 行以内以获得最佳性能。如果内容超过此限制，将详细参考资料拆分为单独的文件。

多文件技能结构示例

以下示例展示了一个技能，在单独的文件中有详细文档和智能体可以执行但不需要读取的工具脚本：

my-skill/
├── SKILL.md (必需 - 概述和导航)
├── reference.md (详细的 API 文档 - 按需加载)
├── examples.md (使用示例 - 按需加载)
└── scripts/
    └── helper.py (工具脚本 - 被执行，不被加载)

SKILL.md 文件引用这些支持文件，以便智能体知道它们的存在：

## 概述

[基本指令]

## 其他资源

- 有关完整的 API 详情，请参阅 [reference.md](reference.md)
- 有关使用示例，请参阅 [examples.md](examples.md)

## 工具脚本

要验证输入文件，运行助手脚本。它检查必填字段并返回任何验证错误：
```bash
python scripts/helper.py input.txt

### 限制工具访问

使用 `allowed-tools` frontmatter 字段来限制技能激活时智能体可以使用的工具。你可以将工具指定为逗号分隔的字符串或 YAML 列表：

```yaml
---
name: reading-files-safely
description: 在不进行更改的情况下读取文件。当你需要只读文件访问时使用。
allowed-tools: Read, Grep, Glob
---

或使用 YAML 样式的列表以获得更好的可读性：

---
name: reading-files-safely
description: 在不进行更改的情况下读取文件。当你需要只读文件访问时使用。
allowed-tools:
  - Read
  - Grep
  - Glob
---

当此技能激活时，智能体只能使用指定的工具（Read、Grep、Glob）而无需请求许可。这对于以下情况很有用：

• 不应修改文件的只读技能
• 有限范围的技能：例如，仅数据分析，不写入文件
• 安全敏感的工作流程，你想限制功能

如果省略 allowed-tools，技能不会限制工具。智能体使用其标准权限模型，可能会请求你批准工具使用。

---

技能和子代理

技能和子代理可以通过两种方式协同工作：

给子代理访问技能的权限

子代理不会自动继承主对话的技能。要给自定义子代理访问特定技能的权限，在子代理的 skills 字段中列出它们：

---
name: code-reviewer
description: 审查代码的质量和最佳实践
skills: pr-review, security-check
---

列出的技能会在子代理启动时加载到其上下文中。如果省略 skills 字段，则不会为该子代理预加载任何技能。

示例

简单技能（单文件）

一个最小的技能只需要一个带有 frontmatter 和指令的 SKILL.md 文件。此示例帮助智能体通过检查暂存的更改来生成提交消息：

commit-helper/
└── SKILL.md

---
name: generating-commit-messages
description: 从 git diff 生成清晰的提交消息。在编写提交消息或审查暂存的更改时使用。
---

# 生成提交消息

## 指令

1. 运行 `git diff --staged` 查看更改
2. 我会建议一个包含以下内容的提交消息：
   - 50 字符以内的摘要
   - 详细描述
   - 受影响的组件

## 最佳实践

- 使用现在时
- 解释是什么和为什么，而不是如何

使用多个文件

对于复杂的技能，使用渐进式披露来保持主 SKILL.md 专注，同时在支持文件中提供详细文档。此 PDF 处理技能包括参考文档、工具脚本，并使用 allowed-tools 限制智能体使用特定工具：

pdf-processing/
├── SKILL.md              # 概述和快速入门
├── FORMS.md              # 表单字段映射和填充指令
├── REFERENCE.md          # pypdf 和 pdfplumber 的 API 详情
└── scripts/
    ├── fill_form.py      # 填充表单字段的工具
    └── validate.py       # 检查 PDF 的必填字段

SKILL.md：

---
name: pdf-processing
description: 提取文本、填充表单、合并 PDF。在使用 PDF 文件、表单或文档提取时使用。需要 pypdf 和 pdfplumber 包。
allowed-tools: Read, Bash(python:*)
---

# PDF 处理

## 快速入门

提取文本：
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()

要求

必须在你环境中安装这些包（智能体会自动安装）：

pip install pypdf pdfplumber

故障排除

技能未触发

描述字段是智能体决定是否使用你的技能的方式。像"帮助处理文档"这样的模糊描述没有给智能体足够的信息将你的技能与相关请求匹配。

一个好的描述回答两个问题：

1. 这个技能做什么？ 列出具体功能。
2. 智能体应该何时使用它？ 包含用户会提到的触发术语。

description: 从 PDF 文件中提取文本和表格、填充表单、合并文档。在使用 PDF 文件或用户提及 PDF、表单或文档提取时使用。

这个描述有效，因为它命名了特定操作（提取、填充、合并）并包含用户会说的关键词（PDF、表单、文档提取）。

技能未加载

检查 YAML 语法。 frontmatter 中的无效 YAML 会阻止技能加载。frontmatter 必须在第 1 行以 --- 开始（前面没有空行），在 Markdown 内容之前以 --- 结束，并使用空格进行缩进（而不是制表符）。

多个技能冲突

如果智能体使用了错误的技能或在相似的技能之间似乎混淆，描述可能太相似了。通过使用特定的触发术语使每个描述独特。

例如，不要在两个技能的描述中都有"数据分析"，而是区分它们：一个用于"Excel 文件和 CRM 导出中的销售数据"，另一个用于"日志文件和系统指标"。你的触发术语越具体，智能体就越容易将正确的技能与你的请求匹配。