AgentVis 官网 / 使用指南 / 技能使用指南
Skill Guide

AgentVis 技能使用指南

适用于 AgentVis 的「设置 -> 技能」、单个 Agent 的「Agent 设置 -> 技能」，以及聊天输入框中的 / 技能选择。

返回指南目录 查看快速开始 查看沙箱指南 查看 IM 指南

1. 文档指引简述

AgentVis 的技能（Skill）可以理解为给 Agent 增加一项专门能力。比如让 Agent 更擅长抓取网页、查询 GitHub、搜索论文，生成特定格式的文档、幻灯片、图表或报告，或者调用稳定脚本完成查询、转换、批处理和各类自动化任务或自定义工作流任务。

技能是 Agent 执行任务时可以使用的能力包。安装后，你可以在全局设置中启用它，也可以只给某个 Agent 绑定几个常用技能，还可以在聊天时临时输入 / 选择本次任务要使用的技能。

普通使用时，你通常只需要关心三件事：

  • 技能是否已经安装并启用。
  • 这个 Agent 是否需要固定绑定某些技能。
  • 本次聊天是否要临时指定某个技能。

2. 技能会出现在哪些地方

2.1 全局技能设置

打开 AgentVis，进入「设置」，点击左侧「技能」。这里用于管理所有已安装技能：

  • 查看技能列表。
  • 查看技能类型标签，例如 Guide 或 Script。
  • 开启或停用某个技能。
  • 进入技能详情。
  • 安装技能的所需依赖。
  • 导入本地技能文件夹。
  • 从 GitHub 技能地址安装。
  • 安装或修改技能后刷新列表。
AgentVis 全局技能设置页面，展示技能列表、启用开关、导入文件夹、刷新列表和 GitHub 安装输入框
全局「设置 -> 技能」页面：管理已安装技能、启用开关、导入本地技能包，并从 GitHub 安装技能。

2.2 单个 Agent 的技能设置

打开某个 Agent，进入「Agent 设置」，点击顶部「技能」。这里用于配置这个 Agent 的专属技能策略：

  • 开启或关闭「精准命中模式」。
  • 选择 1-5 个技能直接绑定到当前 Agent。
  • 保存后，这个 Agent 在 Planning 模式下会优先按你的绑定使用技能。
Agent 设置中的技能页面，展示精准命中模式、已选技能数量、技能选择列表和保存按钮
「Agent 设置 -> 技能」页面：为当前 Agent 开启精准命中模式，并绑定常用技能。

2.3 聊天输入框中的 / 技能选择

在聊天输入框中输入 /，AgentVis 会弹出可选技能列表。你可以选择某个技能，让 Agent 在本次任务里明确参考或调用它。

这种方式适合稳定任务。例如你平时不需要固定绑定 arxiv-search，但这次想让 Agent 使用这个skill查论文而非通过网络搜索或其他渠道，就可以在输入框里选择它。

聊天输入框输入斜杠后弹出的技能选择列表，展示技能名称、描述和指南或脚本标签
聊天输入框输入 / 后，可以为本次任务选择要使用的技能。

3.1 不确定用哪个技能

保持全局技能启用，然后直接描述任务。AgentVis 会根据你的任务内容决定是否调用相关技能。若你想知道当前安装的技能有哪些，相关技能如何使用，可以直接向Agent进行提问。

适合探索式任务、你不确定哪个技能最合适的任务，或者希望 Agent 自己判断是否需要技能的任务。

3.2 希望某个 Agent 稳定使用固定技能

进入「Agent 设置 -> 技能」，开启「精准命中模式」，选择这个 Agent 常用的 1-5 个技能，然后保存。

适合给 Agent 设定固定角色、希望它每次都带着几个稳定能力工作、避免它从全局技能中误选不相关技能。

例如：

  • 研究型 Agent：绑定 arxiv-search、web-scraper 类技能。
  • 前端设计 Agent：绑定 frontend-design、html-slides 类技能。
  • 办公助手 Agent：绑定 docx、xlsx、file-organizer 类技能。

3.3 只想本次任务使用某个技能

在聊天输入框输入 /，选择技能后再补充你的任务内容。

适合稳定使用某个技能执行确定性任务、不想改变 Agent 的长期配置，或者想明确告诉 Agent “这次就用这个能力”。

4. 安装新技能

4.1 从本地文件夹导入

  1. 打开「设置 -> 技能」。
  2. 找到「安装新技能」区域。
  3. 点击「导入文件夹」。
  4. 选择包含 SKILL.md 的技能包目录。
  5. 在弹窗中选择「直接安装」或「开始审查」。
  6. 根据安全审查结果确认是否继续安装。
    7. Agent会对技能包中所有文件扫描并审查安全隐患问题。
  7. 安装完成后点击「刷新列表」。

技能包通常至少包含一个 SKILL.md 文件。复杂技能可能还包含脚本、模板、资源文件或依赖声明。

4.2 从 GitHub 地址安装

  1. 打开「设置 -> 技能」。
  2. 在 GitHub 地址输入框中粘贴技能目录地址。
  3. 弹窗中选择「直接安装」或「开始审查」
  4. 根据安全审查结果确认是否继续安装。
  5. 点击「刷新列表」确认技能出现。

GitHub 地址通常指向仓库中的某个技能目录，例如：

https://github.com/owner/repo/tree/main/skills/skill-name

4.3 安装或修改后为什么要刷新列表

AgentVis 会扫描技能目录并注册可用技能。安装新技能、修改技能内容、手动替换技能包后，请点击「刷新列表」，让新的技能定义生效。

5. 启用、停用和查看详情

在「设置 -> 技能」中，每个技能右侧都有开关。

  • 开启：技能可以被 Agent 检索、选择或调用。
  • 停用：技能保留在本地，但不会参与使用。
  • 详情入口：查看技能说明、类型和可能的执行信息。

如果你暂时不想删除某个技能，建议先停用，而不是直接移除文件。若你移除了AgentVis内置的技能包，想进行恢复，可在安装目录下找到`skills-bundle`文件夹，找回相关技能导入点击直接安装即可。

6. Guide 技能和 Script 技能

AgentVis 当前支持两类 External Skill：Guide 和 Script。

6.1 Guide 技能

Guide 技能与市面上通用 skill 一样结构，更像一份写给 Agent 的能力说明书。它告诉 Agent：

  • 这个技能适合什么任务。
  • 遇到这类任务时应该怎么思考。
  • 可以使用哪些流程、模板、脚本或资源。

Guide 技能不会强制 Agent 只能按某一个脚本执行。Agent 会根据技能说明，然后结合当前任务自行规划。

适合写作、设计、分析、代码生成等开放任务，需要 Agent 根据上下文灵活判断的任务，以及自行定制的工作流任务。

6.2 Script 技能

Script 技能是 AgentVis 特有的执行型技能。它除了说明能力，还会声明一个明确的执行合约，包括：

  • 技能名称和说明。
  • 可以传入哪些参数。
  • 参数类型和必填项。
  • 要运行哪个脚本。
  • 是否需要网络、文件或桌面能力。

Agent 调用 Script 技能时，AgentVis 会先校验参数，再按合约运行脚本。它的体验有点像轻量级 MCP 工具：对 Agent 来说是一个稳定可调用的能力，对用户来说仍然是一种渐进式披露的设计并以技能包形式安装和管理。

适合查询 GitHub、ArXiv、API、数据库或内部系统，文件批处理、格式转换、报表生成，需要稳定参数和固定输出的任务，以及希望网络请求走 AgentVis broker 审计链路的任务。

6.3 两类技能怎么选

类型 更像什么 适合任务 用户是否需要手写代码
Guide 给 Agent 的说明书 开放式、流程型、创作型任务 通常不需要
Script 可调用的小工具 稳定输入输出、脚本执行、API 查询 通常不需要，可交给 Agent 创建

如果你只是使用 AgentVis，不需要手写 SKILL.md。你可以直接让 Agent 帮你创建技能，例如：

帮我创建一个技能：输入 GitHub 仓库地址后，自动读取 README、最近 release 和 open issues，并生成摘要。

AgentVis 内置的 skill-creator 会引导 Agent 按 AgentVis 的技能规范创建技能。对于需要稳定脚本调用的场景，它也会优先考虑 Script 模式。

7. 精准命中模式

「精准命中模式」用于给某个 Agent 固定绑定少量技能。开启后，你选择的技能会直接进入这个 Agent 的任务上下文。

建议在这些情况下开启：

  • 这个 Agent 有明确职责或工作流程。
  • 你希望它稳定使用某几个技能。
  • 全局技能很多，自动检索容易带入无关技能。

不建议在这些情况下开启：

  • 你希望 Agent 自由探索全局技能。
  • 这个 Agent 经常处理完全不同类型的任务。
  • 你还不确定哪些技能最适合它。

注意：精准命中模式只影响当前 Agent，主要在 Planning 模式下生效。开启后，Agent 将无法使用全局中开启的其他技能，建议只绑定你确实想让它使用的技能

8. 技能与安全

技能可能只是说明文档，也可能包含可执行脚本。安装第三方技能时，请优先从可信来源获取，并认真阅读安全审查结果。

建议：

  • 不确定来源的技能，不要直接用于重要工作区。
  • 第一次运行第三方脚本技能时，可以把 Agent 的沙箱权限切到「离线隔离」或「受控联网」。
  • 涉及 API Key、Token、Cookie、账号凭据的技能，只使用你信任的技能包。
  • 如果安全审查提示高风险，不要只因为技能名字看起来有用就继续安装。

AgentVis 会在安装和运行阶段提供安全审查、沙箱权限、网络审计和敏感信息脱敏，但这些机制不能替代你对技能来源的判断。

9. 常见问题排查

9.1 新安装的技能没有出现在列表中

  1. 检查技能目录中是否包含 SKILL.md。
  2. 检查 SKILL.md 是否遵循格式规范。
  3. 确认是否点击了「刷新列表」。
  4. 检查技能名称是否和已有技能冲突。
  5. 如果是 GitHub 安装，确认地址指向具体技能目录。
  6. 如果安装过程中有安全审查或依赖安装失败，先处理对应提示。

9.2 Agent 没有使用我想要的技能

  1. 确认技能是否在「设置 -> 技能」中启用。
  2. 确认当前 Agent 是否开启了「精准命中模式」。
  3. 如果开启了精准命中模式，检查目标技能是否已被选中。
  4. 如果只是本次想用，确认是否在输入框中通过 / 选择了技能。
  5. 检查任务描述是否足够明确，是否与技能描述相关。

9.3 Script 技能运行失败

常见原因包括参数缺失或格式不正确、Python / Node 运行时或依赖未准备完成、当前沙箱权限不允许联网或文件访问、技能脚本内部报错、目标服务需要凭据但凭据未配置或已失效。

可以查看聊天中的工具调用结果，或进入「设置 -> 安全审计」查看是否有阻断、诊断或 broker 相关记录。

9.4 技能能否访问网络

取决于技能类型、技能声明和当前 Agent 的沙箱权限。

  • Guide 技能通常跟随当前 Agent 的沙箱权限。
  • Script 技能可以声明更明确的网络策略。
  • 需要强审计的 Script 技能可能使用 broker-only 路径，由 AgentVis 代发 HTTP(S) 请求并记录审计。
  • 离线隔离模式下，技能默认不能联网。

9.5 技能能否控制桌面或浏览器

取决于技能能力和沙箱权限。

  • 普通桌面控制通常需要「本机审计」模式。
  • 「受控联网」模式下，AgentVis 默认只对专用浏览器自动化能力开窄口，不等于允许任意桌面控制。
  • 「离线隔离」模式会阻断桌面控制、截图、热键和外部 GUI 启动等能力。

10. 推荐配置清单

日常使用前可以快速确认：

  • 需要的技能已安装。
  • 技能在「设置 -> 技能」中处于启用状态。
  • 安装或修改技能后已经点击「刷新列表」。
  • 如果是固定用途 Agent，已在「Agent 设置 -> 技能」中绑定常用技能。
  • 如果只是临时任务，已在聊天输入框通过 / 选择技能。
  • 第三方技能已阅读安全审查结果。
  • 不可信脚本或高风险任务已考虑搭配合适沙箱权限。