管理 Skill
一个 Skill 是为 Agent 编写的能力说明和使用指南。本指南讲述如何安装、管理和在任务中使用 Skill。
什么是 Skill？
Skill 不是工具本身，而是关于工具的文档和最佳实践。它包含：
- 能力描述：这个 Skill 能做什么
- 使用指南：Agent 何时应该用到它、如何最有效地使用
- 参考资料：API 文档、示例代码、常见错误及解决方案
例如，“Docker 操作” Skill 告诉 Agent 如何：
- 构建镜像、运行容器、查看日志
- 处理常见的 Docker 错误
- 遵循 Dockerfile 最佳实践
创建任务时，你选择一个 Profile，Agent 会自动获得该 Profile 关联的所有 Skill。
Skill 目录结构
每个 Skill 是一个目录，具有标准化的结构：
skills/
docker-ops/ # Skill ID（目录名）
SKILL.md # Skill 元数据 + 内容
references/ # 可选的参考资料目录
api.md # 参考文档
examples.md
SKILL.md 文件格式
SKILL.md 包含 YAML frontmatter 和 Markdown 正文：
---
name: docker-ops
description: Guide to Docker image, container, and network management
license: MIT
metadata:
disabled: false
contentOverrideMode: replace
---
## Overview
This Skill guides agents how to use Docker for common tasks...
## Core concepts
- **Image**: Read-only template containing application and dependencies
- **Container**: Running instance of an image
## Usage guide
### Build images
...
Frontmatter 字段
| 字段 | 必填 | 说明 |
|---|---|---|
name | 是 | 显示名称 |
description | 否 | 简短描述 |
license | 否 | 许可证 |
metadata.disabled | 否 | 禁用此 Skill；值为 false（默认）或 true |
metadata.inclusion | 否 | 包含策略：auto（默认）— 自动包含，可被更高优先级层覆盖；mandatory — 强制包含，不可移除；explicit — 仅在 Profile 中显式引用时生效 |
metadata.overridable | 否 | 高优先级配置层是否可覆盖此资源（默认未设置——允许覆盖）。显式设为 false 时，高优先级层的同名条目会被忽略 |
metadata.contentOverrideMode | 否 | 多层同 ID Skill 的合并策略，见下文 |
contentOverrideMode 说明：
replace（默认）：使用最高优先级层的内容，忽略低优先级层merge：按优先级链式回退（高优先级层中不存在时回退到低优先级层）
安装 Skill
Skill 可以来自三个来源：
1. 内置 Skill
Sink 内置了一些常用 Skill。这些 Skill 无需额外安装即可自动使用。
2. 从官方仓库同步
从 ~/.agents/skills/ 目录同步预先下载的 Skill：
sink skill sync
此命令会：
- 扫描
~/.agents/skills/下的所有 Skill 目录 - 在你的 Sink 配置目录下的
skills/子目录中创建指向~/.agents/skills/的符号链接
前置条件：你需要事先将 Skill 文件夹下载到 ~/.agents/skills/。
3. 手动添加 Skill
直接在你的配置目录中创建 Skill 文件夹：
用户层安装
将 Skill 放在用户级配置目录：
mkdir -p ~/.sink/skills/my-custom-skill
cat > ~/.sink/skills/my-custom-skill/SKILL.md << 'SKILL'
---
name: my-custom-skill
description: Custom tutorial
metadata:
disabled: false
---
## Overview
This is a custom Skill I wrote for agents...
SKILL
该 Skill 将对所有工作区可用。
工作区层安装
将 Skill 放在工作区配置目录，仅对该工作区生效：
mkdir -p /path/to/my-project/sink/skills/project-specific-skill
cat > /path/to/my-project/sink/skills/project-specific-skill/SKILL.md << 'SKILL'
---
name: project-specific-skill
description: Available only in this project
metadata:
disabled: false
---
## Project background
Describe project-specific practices and conventions in this Skill...
SKILL
4. 添加参考资料
在 Skill 目录中创建 references/ 子目录来存放附加文档：
mkdir -p ~/.sink/skills/docker-ops/references
cat > ~/.sink/skills/docker-ops/references/api.md << 'REF'
# Docker API Reference
## Common commands
- `docker build` - Build image
- `docker run` - Run container
...
REF
查看已安装的 Skill
列出当前可用的所有 Skill：
sink skill list
输出将显示：
- Skill ID（目录名）
- 显示名称（来自 frontmatter）
- 描述
- 来源（builtin / user / workspace）
- 启用状态
在 Profile 中关联 Skill
Skill 通过 Profile 关联到 Agent。一旦创建任务，Agent 会自动获得该 Profile 关联的所有 Skill。
编辑 Profile
打开 Profile 文件（Markdown 格式）并在 frontmatter 中指定 Skill：
---
name: code-reviewer
description: Code quality analysis and review
runtime: claude-code
skills:
- web-search
- code-analysis
- test-runner
mcpServers:
- filesystem
---
You are an experienced code reviewer specializing in software quality...
Skills 字段
skills 字段支持两种写法：
简单列表（白名单）：
skills:
- web-search
- docker-ops
只有列表中的 Skill 可用。
选择器写法（include/exclude）：
skills:
include:
- web-search
- docker-ops
exclude:
- experimental-skill
或仅排除：
skills:
exclude:
- experimental-skill
禁用 Skill
临时禁用
修改 Skill 的 frontmatter，将 metadata.disabled 设为 true：
---
name: web-search
metadata:
disabled: true
---
禁用后，该 Skill 将从所有 Profile 的可用 Skill 列表中移除。
从特定 Profile 中排除
如果不想全局禁用，而只想从某些 Profile 中排除：
在 Profile 的 skills 字段中使用 exclude：
skills:
exclude:
- web-search
最佳实践
编写清晰的 Skill
- 标题明确：Skill 名称应直观反映其用途
name: error-fixing-and-debugging - 包含具体示例：好的 Skill 包含代码示例和常见错误
## Common errors ### Error: Connection refused **Cause**: Service not started **Solution**: Run `docker run -d my-service` - 组织参考资料：复杂的 Skill 应在
references/目录中分类存放文档
共享与版本管理
- 将 Skill 存储在版本控制中（Git）
- 使用语义化版本（如
v1.0.0）标记发行版 - 在 Profile 中显式记录依赖的 Skill 版本（如需要）
Skill 与 MCP Server 的区别
- Skill = 指南和最佳实践文档
- MCP Server = 实际的工具和能力实现
Agent 依赖 MCP Server 执行操作，依赖 Skill 理解”何时使用”和”如何用好”。两者互补。
故障排除
Skill 未显示在 Profile 中
检查清单：
- Skill 是否被禁用？
# 检查 SKILL.md 中的 metadata.disabled - Skill ID 是否正确？
sink skill list # 查看实际 Skill ID - Profile 中的 Skill 引用是否拼写正确？
skills: - correct-skill-id # 必须与 skill list 输出一致
多层 Skill 冲突
如果你在用户层和工作区层都定义了同 ID 的 Skill，并且看到了意外的内容，检查：
# 查看有效配置（已合并）
cat <workspace>/.sink/.settings.snapshot.json
# 查看原始文件
cat ~/.sink/skills/my-skill/SKILL.md
cat <workspace>/.sink/skills/my-skill/SKILL.md
优先级是工作区 > 用户 > 内置。
下一步
- 了解如何 管理 Profile，将 Skill 关联到 Agent
- 查看 配置 MCP Server，为 Agent 添加实际工具
- 创建第一个 任务，让 Agent 使用你配置的 Skill