--- title: 技能 description: "通过可复用的知识包扩展 Verdent 的能力，应对专业化工作流与领域专长" --- Verdent **Skills（技能）** 是可复用的知识包，用于扩展智能体的专长。每个技能包含面向特定领域的提示词、脚本、参考资料和最佳实践。只需按名称调用某个技能，智能体便会加载相应的上下文并遵循预定义的工作流。 --- ## 什么是技能？ ### 核心概念 **技能** 是存储在文件夹中的结构化知识包。每个技能都包含一个 `SKILL.md` 文件，用于定义其名称、描述和详细提示词。当你在对话中调用某个技能时，Verdent 会读取该文件并将其内容注入智能体的上下文。 ### 技能与子智能体、MCP 的区别 | 维度 | 技能 | 子智能体 | MCP | |-----------|--------|-----------|-----| | **触发方式** | 通过 `@skill` 或提及手动调用 | 由主智能体自动派生 | 自动调用或显式调用 | | **执行方式** | 扩展主对话的上下文 | 作为独立子任务运行，上下文相互隔离 | 通过 JSON-RPC 2.0 调用外部工具 | | **用途** | 领域指导（例如"如何编写测试"） | 独立操作（例如"运行代码审查"） | 访问外部数据/工具（例如数据库查询） | | **生命周期** | 一次性上下文注入 | 完成子任务后返回结果 | 会话期间持续运行的服务进程 | | **实现方式** | Markdown 文件 + 可选脚本 | 内置智能体逻辑 | 可执行的服务进程 | 简而言之：**技能提供知识与工作流指导**，**子智能体执行独立任务**，**MCP 连接外部工具与数据源**。 --- ## 如何使用技能 ### 调用技能 你可以通过两种方式调用技能： **1. 在对话中提及技能名称** ``` Use the skill-creator skill to help me create a new Skill ``` **2. 使用 @ 提及语法** ``` @skill-creator help me create a Skill for API documentation generation ``` 当某个技能被触发时： 1. 智能体调用 `skill` 工具读取该技能的 `SKILL.md` 文件 2. 文件内容被注入当前对话上下文 3. 智能体按照该技能的指导继续工作 ### 浏览可用技能 通过设置访问技能面板： 1. 打开 **Settings** 菜单 2. 选择 **Skills** 选项卡 3. 浏览已安装的技能以及技能商店中的可用技能 你也可以在输入框中输入 `@` 触发自动补全，快速选择一个可用技能。 --- ## 内置技能 Verdent 内置了一组涵盖常见工作流的技能： | 技能 | 描述 | |-------|-------------| | **docx** | 读取、创建或编辑 Word 文档（`.docx`），并进行格式忠实的可视化检查 | | **find-skills** | 发现并安装技能——当你询问"我该如何做某事？"或寻找新能力时使用 | | **frontend-design** | 创建独特、达到生产级标准且设计质量出色的前端界面 | | **pdf** | 读取、创建或审阅 PDF 文件，支持可视化渲染与内容提取 | | **pptx** | 读取、创建或编辑 PowerPoint 演示文稿（`.pptx`） | | **skill-creator** | 用于创建并迭代自定义技能的引导式工作流 | | **xlsx** | 读取、分析、可视化并智能编辑 Excel 表格 | **技能商店** 中还有更多技能。打开 **Settings → Skills → Store** 即可浏览并安装更多技能。 --- ## 创建自定义技能 你可以创建自定义技能，将团队的领域专长或项目特定的工作流封装起来。 ### 技能目录结构 一个标准的技能文件夹结构如下： ``` my-custom-skill/ ├── SKILL.md # Required: Skill definition file ├── agents/ │ └── verdent.yaml # Optional: UI configuration (icons, display name) ├── scripts/ # Optional: helper scripts └── references/ # Optional: reference docs or examples ``` ### SKILL.md 格式 `SKILL.md` 是核心技能文件，包含 YAML frontmatter 和 Markdown 正文： ```markdown --- name: my-custom-skill description: A concise description shown in the Skill list metadata: version: "1.0.0" author: "Your Name" license: "MIT" --- # Detailed Instructions This is the detailed prompt content the Agent reads. ## Workflow 1. Step one 2. Step two 3. ... ## Best Practices - Practice suggestion 1 - Practice suggestion 2 ``` **Frontmatter 字段要求：** - `name`（必填）：必须与文件夹名称一致。仅允许小写字母、数字和连字符（`a-z0-9-`）。长度为 1–64 个字符。不允许连续连字符，也不允许以连字符开头或结尾。 - `description`（必填）：简短描述，最多 1024 个字符。 - `metadata`（可选）：版本、作者、许可证等元信息。 ### 安装自定义技能 **方法 1：通过设置导入** 1. 打开 **Settings → Skills** 2. 点击 **Import Skill** 3. 选择技能文件夹（或 `.zip` / `.skill` 压缩包） 4. Verdent 会校验 `SKILL.md` 并将其安装到 `~/.verdent/skills/` **方法 2：手动复制** ```bash cp -r my-custom-skill ~/.verdent/skills/ ``` 重启 Verdent 或刷新技能列表后，该技能即可使用。 **方法 3：项目级技能** 将技能放入你的项目目录中： ```bash cp -r my-custom-skill /path/to/your/project/.verdent/skills/ ``` 项目级技能仅在该项目内可见，并且优先于同名的全局技能。 --- ## 技能作用域 Verdent 支持三种级别的技能作用域： | 级别 | 位置 | 可见范围 | |-------|----------|------------| | **全局** | `~/.verdent/skills/` | 所有项目和工作区 | | **项目** | `/.verdent/skills/` | 仅当前项目的工作区 | **优先级规则：** 当多个作用域存在同名技能时： - 项目级覆盖全局级 --- ## 技能商店 Verdent 提供 **技能商店**，用于浏览并安装社区与官方技能。 ### 浏览技能商店 1. 打开 **Settings → Skills** 2. 切换到 **Store** 选项卡 3. 浏览可用技能或使用搜索框 ### 从商店安装 1. 在商店中找到所需的技能 2. 点击 **Install** 3. 该技能会被自动下载并安装到 `~/.verdent/skills/` **安全校验：** 从商店安装的技能会经过 SHA256 校验和验证，以确保文件完整性与安全性。 --- ## 实用示例 ### 示例 1：使用 `skill-creator` 创建新技能 ``` @skill-creator help me create a Skill for guiding the team on writing Go unit tests ``` 智能体将会： 1. 读取 `skill-creator` 技能内容 2. 引导你填写技能名称、描述和核心提示词 3. 生成标准的 `SKILL.md` 4. 建议安装路径和验证步骤 ### 示例 2：使用 `spreadsheet` 分析数据 ``` @spreadsheet read sales-2025.xlsx from the project root, analyze Q1 sales trends, and generate a chart ``` 智能体将会： 1. 加载 `spreadsheet` 技能 2. 使用 `pandas` 和 `openpyxl` 读取 Excel 文件 3. 分析数据并生成可视化图表 4. 保存结果或在对话中展示 ### 示例 3：使用 `gh-fix-ci` 修复 CI ``` @gh-fix-ci my PR #123 GitHub Actions tests are failing, help me debug ``` 智能体将会： 1. 使用 `gh` CLI 获取 PR #123 的 CI 日志 2. 分析失败原因（例如测试用例错误、依赖问题） 3. 提出修复方案 4. 在你批准后修改代码并推送修复 --- ## 常见问题 当技能被调用时，智能体会读取 `SKILL.md` 文件，这会计入 token 用量，因此会消耗积分。不过，技能本身不会发起额外的 API 调用。 可以。将技能安装到 `~/.verdent/skills/`（全局作用域），它便会在所有项目中可用。 在 **Settings → Skills** 中，右键点击该技能并选择 **Delete**。标记为 `undeletable` 的内置技能无法删除，并会在下次启动时重新安装。 可以。Verdent 会自动检测 `~/.cursor/skills`、`~/.claude/skills` 和 `~/.codex/skills` 中的技能，并提示你导入。点击 **Settings → Skills** 中的 **Import from External Sources** 即可。 - **项目规则（Project Rule）**：始终生效的指令，会自动注入到每次对话中 - **技能（Skill）**：按需加载的知识包，仅在被调用时注入 通用编码规范用规则；特定领域工作流用技能。 从技能商店安装的技能会在后台自动检查更新。手动安装的技能则需要重新导入（覆盖旧版本）来更新。 --- ## 进阶用法 ### 在技能中嵌入脚本 在技能中添加一个 `scripts/` 目录，并在 `SKILL.md` 中引用这些脚本： ```markdown ## Data Processing Script Run the following command to process data: \`\`\`bash python scripts/process_data.py --input data.csv --output results.json \`\`\` ``` 智能体会读取该指令并按需执行脚本。 ### 引用文档 将 API 文档、规范或示例代码存放在 `references/` 目录中，并在 `SKILL.md` 中链接它们： ```markdown ## Reference Documentation See [references/api-spec.md](references/api-spec.md) for the detailed API specification. ``` 智能体可以根据技能的指令读取这些参考文件。 --- ## 最佳实践 **保持技能聚焦。** 每个技能应针对单一领域或工作流。避免创建"包揽一切"的技能——而应将其拆分为更小、更专业的技能。 **使用清晰的命名。** 技能名称应简洁且具有描述性，例如 `api-doc-generator`，而非 `my-skill-1`。 **提供示例和参考。** 在 `SKILL.md` 中包含具体示例和参考链接，帮助智能体更好地理解预期输出。 **维护版本号。** 使用 `metadata.version` 字段来跟踪更新与兼容性。 **分享前先测试。** 在向团队推广或发布到技能商店之前，先在测试项目中验证你的技能。 --- ## 另请参阅 子智能体的工作原理及管理方式 通过 MCP 连接外部工具与服务 配置始终生效的项目规则与用户规则 使用内置审查器审查代码变更