技能管理
技能（Skill）是 Nexent 为智能体扩展能力的核心机制。每个技能将多个工具与使用文档打包为一个可复用的能力单元，可以像搭积木一样为智能体赋予复杂的工作能力。
目录
- 技能与工具的关系：理解技能的核心概念
- 技能使用指南：如何在智能体开发中使用技能
- 技能管理：创建、编辑、安装外部技能
- 技能上传指南：SKILL.md 格式、ZIP 结构、特殊标签与书写规范
- NL-to-Skill：通过自然语言描述自动生成技能
- 官方技能一览：预置技能及其能力说明
技能与工具的关系
在 Nexent 中，工具（Tool） 与 技能（Skill） 是两个不同层次的概念，理解它们的区别有助于更好地为智能体配置能力。
工具是智能体可调用的单个原子操作。为智能体启用工具时，LLM 的每次思考都会在工具列表中搜索——这意味着即使某个工具本次对话完全不需要，LLM 仍然会消耗上下文额度去"看到"它。
技能则通过 SKILL.md 将多个工具的能力组合为一个完整的工作流，并附带参数配置与使用文档。LLM 不需要预先"看到"所有工具，而是根据用户的实际需求，自行判断是否激活某个技能。激活后，系统才会加载对应的工具集——从而有效节省 Token 消耗。
| 维度 | 工具 | 技能 |
|---|---|---|
| 粒度 | 单个原子操作 | 多个工具 + 配置 + 文档的组合 |
| Token 消耗 | 每次对话都占用上下文 | 仅在激活时才加载 |
| 参数 | 固定参数 schema | 可自定义参数模板 |
| 分发 | 代码级 | ZIP 包分发，即插即用 |
技能使用指南
为智能体配置技能
- 打开 智能体开发 页面
- 在"选择智能体的工具"页签中，找到 技能（Skills） 分组
- 点击技能名称即可选中，再次点击取消选择
- 保存智能体配置
技能管理
查看已安装的技能
在"选择智能体的工具"技能分组中，系统会展示所有已安装的技能列表，包括：
- 官方技能
- 自定义技能
创建自定义技能
Nexent 支持两种方式创建自定义技能：上传技能包文件，或通过自然语言描述自动生成。
方式一：上传 SKILL.md 或 ZIP
- 进入技能配置界面
- 点击"上传技能"按钮
- 选择
SKILL.md文件（单文件）或.zip压缩包（完整技能包） - 系统自动解析并创建技能
方式二：NL-to-Skill 自然语言创建
在技能管理页面，点击"NL 创建技能"按钮即可进入。具体用法详见下方 NL-to-Skill 专区。
技能上传指南
技能包结构
技能包可以是单个文件，也可以是包含多个文件的 ZIP 包：
skill-name/
├── SKILL.md # 技能定义文件（必需）
├── config/
│ ├── config.yaml # 参数默认值
│ └── schema.yaml # 参数类型与说明
├── scripts/
│ └── *.py # Python 脚本
├── examples.md # 使用示例
└── assets/ # 静态资源SKILL.md 格式详解
SKILL.md 是技能的核心文件，分为 YAML 元数据区和正文两部分。
YAML 元数据（必需）
文件顶部必须有 YAML frontmatter，格式如下：
---
name: skill-name
description: |
一段描述，说明这个技能是做什么的、什么时候该用它。
建议用第三人称书写。
tags:
- tag1
- tag2
---| 字段 | 必填 | 说明 | 示例 |
|---|---|---|---|
name | 是 | 技能名称，全英文、小写、单词间用连字符 | github-repo-analyzer |
description | 是 | 技能功能描述，建议 1-3 句话，包含使用场景 | 这个技能用于分析 GitHub 仓库并提取关键指标 |
tags | 否 | 技能标签列表，便于分类检索 | ["code", "github", "analysis"] |
正文
元数据下方可以写 Markdown 正文，包含技能的使用说明、最佳实践、示例代码等。
两种技能类型
根据用途，技能分为两类，书写方式有所不同：
工具类技能：用于暴露工具能力。正文应包含工具的参数说明、调用示例、返回格式、错误处理等。
智能体类技能：用于教智能体执行复杂任务。正文应包含工作流程、领域知识、边界条件、最佳实践等。
config/schema.yaml：定义参数表单
如果技能需要用户填写参数，可以创建 config/schema.yaml 文件。系统会根据此文件在前端自动生成参数配置表单。
param_name:
type: string | number | boolean | array | object
required: true | false
default: <默认值>
description: "参数的英文说明"
description_zh: "参数的中文说明"支持的类型：string、number、boolean、array、object
完整示例：
query:
type: string
required: true
description: "Search query string"
description_zh: "搜索关键词"
default: ""
top_k:
type: number
required: false
description: "Number of results to return"
description_zh: "返回结果数量"
default: 3
enable_rerank:
type: boolean
required: false
description: "Enable result reranking"
description_zh: "是否启用结果重排序"
default: falseconfig/config.yaml：设置参数默认值
如果希望某些参数有默认值，可以创建 config/config.yaml：
# Initial workspace path
init_path: "/mnt/nexent"
# Maximum number of results
top_k: 5特殊标签
在 SKILL.md 正文中，可以使用以下特殊标签：
<reference>：按需加载示例文件
使用 <reference> 标签引用外部文件，该文件仅在需要时才被加载，不会增加 SKILL.md 的主文件大小。
## 示例参考
<reference path="examples.md" /><use_script>：声明捆绑的脚本
如果技能包中包含 Python 或 Shell 脚本，需要在 SKILL.md 中声明：
<use_script path="scripts/analyze.py" /><code>：展示可执行代码示例
使用 <code> 标签包裹可执行的代码示例（通常为 Python 代码）：
<code>
result = run_skill_script(
"code-reviewer",
"scripts/analyze.py",
{"--target": "/path/to/file.py", "--verbose": True}
)
print(result)
</code>辅助函数
在智能体类技能的正文和示例中，可以使用以下函数：
run_skill_script(skill_name, script_path, params)：执行技能包中的脚本
# 执行 Python 脚本
result = run_skill_script(
"code-reviewer",
"scripts/analyze.py",
{"--target": "/path/to/file.py"}
)
# 执行 Shell 脚本
result = run_skill_script(
"database-migration",
"scripts/migrate.sh",
{"--direction": "up", "--steps": 1}
)read_skill_md(skill_name, files)：读取技能包中的文件内容
# 默认只读取 SKILL.md（如果存在引用文件，不会自动包含）
content = read_skill_md("my-skill")
# 显式指定要读取的文件
full_content = read_skill_md("my-skill", [
"SKILL.md",
"reference/api-reference.md"
])书写规范与最佳实践
SKILL.md 书写规范：
描述要具体：说明技能在什么场景下使用，而不是仅仅描述功能
- ✓ "当用户需要分析 GitHub 仓库的流行度指标时使用"
- ✗ "GitHub 搜索功能"
避免时间敏感信息：不要包含具体日期、版本号等会过期的内容
保持简洁：SKILL.md 正文建议控制在 500 行以内。复杂内容用
<reference>按需加载路径格式：始终使用正斜杠
/，即使在 Windows 下也如此- ✓
src/services/payment_service.py - ✗
src\services\payment_service.py
- ✓
参数命名一致：全文统一使用相同的术语和命名风格
包含边界条件：说明技能的适用范围和限制
参数描述最佳实践：
# ✓ 好：明确说明用途和格式
query:
type: string
required: true
description: "GitHub repository owner/name or full URL"
description_zh: "GitHub 仓库的 owner/name 格式或完整 URL"
# ✗ 差：过于模糊
query:
type: string
required: true
description: "Search query"
description_zh: "查询"代码示例最佳实践：
- 每个工具至少提供 2 个不同场景的示例
- 示例中包含常见参数组合
- 示例展示成功调用和常见错误处理
从现有技能学习
系统内置了多个完整技能的参考示例，您可以在 test_skill_examples/official-skills/ 目录下找到它们：
| 技能名 | 参考价值 |
|---|---|
create-file-directory | 工具类技能的标准写法，包含完整参数表、调用示例、错误处理表 |
search-knowledge-base | 搜索类技能的参数配置，包含 schema.yaml 和 config.yaml 的完整示例 |
analyze-image | 多模态工具的示例，包含 <code> 调用格式 |
code_review_expert | 智能体类技能的参考，包含捆绑脚本和 <use_script> 标签用法 |
常见问题
Q: 上传 ZIP 包时报错"缺少 SKILL.md"
确保 ZIP 包根目录下包含 SKILL.md 文件，而不是将其放在子文件夹中。
Q: 技能描述不生效
技能描述应写在 YAML frontmatter 的 description 字段中，而非正文的 Markdown 部分。正文内容不会被解析为技能描述。
NL-to-Skill
NL-to-Skill 是 Nexent 提供的一项智能创建功能。您只需要用自然语言描述一个技能的需求，系统就能自动生成完整的技能包，包括技能定义、参数配置、甚至配套的脚本代码。整个生成过程实时可见，就像有一个 AI 助手在帮您写代码一样。
简单来说：
您说"我想要一个能搜索 GitHub 仓库并提取 Star 数的技能"，系统就自动为您生成一个完整可用的技能。
快速上手
第一步：描述您的需求
在输入框中，用自然语言描述您想要的技能。描述越清晰，生成效果越好。
正例：
- "创建一个技能，可以根据关键词搜索 GitHub 仓库并返回 Star 数、描述和链接"
- "创建一个读取 Excel 文件、统计各列数据并生成图表的技能"
- "创建一个技能，能从邮件中提取订单号、金额和日期，汇总成表格"
反例：
- "帮我做一个聊天技能"（太模糊）
- "搜索工具"（缺少具体能力描述）
第二步：查看生成过程
点击"生成"后，页面会实时展示 AI 的思考和编写过程：
- 看到 AI 在分析您的需求
- 看到它正在编写技能定义文件
- 看到它在规划参数结构
这个过程就像看 AI 现场写代码，您可以随时点击"停止"中断。
第三步：预览并保存
生成完成后，系统会展示技能的完整内容：
- 技能名称和描述
- 参数列表（每个参数是什么、是否必填）
- 使用示例
仔细检查预览内容：
- 如需调整，点击"编辑"微调
- 如符合预期，点击"保存"将技能添加到您的技能库
写作技巧
如何写好技能描述
1. 明确输入输出
告诉系统这个技能需要什么信息、会返回什么结果。
✓ "输入一个 GitHub 仓库地址，返回仓库名称、Star 数、Fork 数和最新更新时间"
✗ "搜索 GitHub"（太模糊）2. 说明使用场景
让 AI 理解在什么情况下会用到这个技能。
✓ "用于快速查询开源项目的流行程度，帮助做技术选型决策"
✗ "查数据"（没有场景）3. 描述边界条件
如果有特殊的处理逻辑或限制，一并说明。
✓ "如果仓库不存在，返回友好提示而不是报错"
✓ "图片 URL 无效时跳过该图片并记录日志"4. 显式要求生成示例
如果技能使用场景复杂，且对边缘场景响应准确率要求较高，则可以在要求中明确提出生成更详细的示例。
✓ "生成全面且详细的使用示例"适用场景举例
| 场景 | 描述示例 |
|---|---|
| 数据采集 | "输入关键词，在知乎上搜索相关问答并提取最高赞回答的摘要" |
| 文件处理 | "上传一个 CSV 文件，自动统计各列数据并生成折线图" |
| API 封装 | "创建一个调用天气 API 并返回未来三天预报的技能" |
| 多工具组合 | "输入商品链接，自动比价（调用多个电商搜索）并返回最低价链接" |
| 数据清洗 | "读取一段混乱的文本，提取其中的邮箱、手机号、日期并格式化输出" |
生成过程中可以做什么
实时预览
生成过程中，技能内容会逐步显示在预览区域：
SKILL.md内容：技能定义、描述、标签examples.md：技能使用示例scripts/*.py：工具脚本（复杂模式下）
随时停止
如果生成方向偏离预期：
- 点击"停止"按钮，AI 立即停止
- 已有生成结果会保留，您可以查看或放弃
多次尝试
如果第一次生成结果不理想：
- 直接补充需求细节，在原有基础上直接修改
- 或者在预览中手动调整
- 不满意当前生成的技能，希望重新再来时，您可以点击右上角的"垃圾桶"图标清空所有技能内容
使用限制与注意事项
模型能力影响质量
NL-to-Skill 使用您租户配置的 LLM 模型来生成技能。模型的能力直接决定生成质量：
- 聪明的模型能准确理解需求，生成结构清晰、易于理解的技能
- 较弱的模型可能生成不完整或有误导性的内容，影响智能体的效率与准确率
如果生成结果不理想，可以尝试：
- 简化需求描述
- 切换到更聪明、更强大的模型
- 分步骤创建（先做简单版本，再手动扩展）
Token 消耗
复杂技能生成会消耗更多 Token：
- 简单模式：通常消耗较少，适合快速验证
- 复杂模式：消耗较多，适合正式创建完整技能
建议先用简单模式测试想法，确认可行后再用复杂模式正式创建。
并非所有需求都能实现
NL-to-Skill 擅长生成以下类型的技能：
- 单一工具的包装（如封装一个搜索能力）
- 多工具的简单串联（如搜 → 读 → 总结）
- 常见数据处理流程（如文件格式转换、数据提取）
以下类型的技能可能超出能力范围：
- 需要调用未接入的外部 API
- 涉及复杂的状态管理或并发逻辑
- 需要访问平台未开放的底层接口
遇到无法实现的需求时，系统会给出提示，您可以考虑手动创建或联系技术支持。
技能修改
在 NL-to-Skill 界面可以选中已经存在的技能。选中技能后，该技能信息将自动加载。您可以在左侧对话框中使用自然语言尝试对该技能进行更新。
如果您创建的技能名与已有技能重名，Nexent 将自动从技能创建模式切换为技能更新模式。所有内容将覆盖更新至原有技能。
安全与最佳实践
- 知识库访问控制：导入包含知识库工具的技能时，实际检索范围受当前用户权限限制
- 公网搜索：Tavily / Linkup / Exa 等公网搜索需先在平台安全配置中填写对应 API Key
- 路径安全：技能包内文件操作仅限技能目录范围内，无法访问系统任意路径