Skills 插件¶

Skills 是 Synapse 的可扩展插件系统，位于项目 skills/ 目录下。每个 Skill 是一个包含 SKILL.md 的目录，Agent 在需要时自动加载。

Skills 目录结构¶

skills/
├── cua-driver/
│   └── SKILL.md
├── file-cleanup/
│   └── SKILL.md
├── project-session-reader/
│   └── SKILL.md
├── session-cache-analysis/
│   └── SKILL.md
└── session-crash-repair/
    └── SKILL.md

SKILL.md 格式¶

每个 SKILL.md 使用 YAML frontmatter + Markdown 正文：

---
name: session-cache-analysis
description: Analyze the prompt cache hit rate of a Synapse session (thread).
license: Apache-2.0
compatibility: Requires a synapse source checkout with uv and Python 3.12+.
allowed_tools: execute, read_file, write_file, search_files, find_files, search_session, read_session
---

# Session Cache Hit-Rate Analysis

## 数据来源
...

Frontmatter 字段¶

字段	说明
`name`	Skill 名称
`description`	简短描述（Agent 据此判断是否适用）
`license`	许可证
`compatibility`	兼容性要求
`allowed_tools`	允许使用的工具列表（逗号分隔）

内置 Skills¶

Synapse 自带五个 Skills：

Skill	说明
`cua-driver`	通过 cua-driver 的 MCP 工具（`cua_` 前缀）操作本机 Windows 真实桌面：枚举应用与窗口、读无障碍树与截图、按元素索引或坐标点击/输入/滚动/拖拽，并验证动作是否真的生效（需已安装 cua-driver 并在 `~/.synapse/mcp.json` 启用 cua 服务器）
`file-cleanup`	扫描并清理磁盘空间：定位大目录与可清理内容（包管理器缓存、浏览器缓存、IDE 索引、updater 安装包、容器镜像、构建产物、日志等），按「可立即清理」与「需用户确认」两类执行并验证释放量
`project-session-reader`	读取或搜索指定项目（workspace 目录）`.synapse/` 下的会话：列出、全文搜索、按 thread_id 读取并分页
`session-cache-analysis`	分析会话的 prompt 缓存命中率，区分增量 miss 与全量逐出并定位根因
`session-crash-repair`	检测并修复异常退出后 checkpoint 不一致的会话（悬挂工具调用、挂起图任务、过期转录投影）

如何编写自定义 Skill¶

在 skills/ 下创建目录，如 skills/my-skill/
创建 skills/my-skill/SKILL.md，填入 frontmatter 和正文
正文使用 Markdown，Agent 会在匹配时完整读取

示例：自定义工具 Skill¶

---
name: docker-ops
description: Docker container management: build, run, inspect, clean up.
license: MIT
compatibility: Requires Docker CLI installed and accessible from shell.
allowed_tools: execute
---

# Docker Operations Skill

## 构建镜像

在包含 Dockerfile 的目录下：
```bash
docker build -t <name>:<tag> .

运行容器¶

docker run -d --name <name> -p 8080:80 <image>

## 配置

| 变量 | 默认值 | 说明 |
|---|---|---|
| `skills_paths` | `["skills"]` | Skills 目录路径列表 |

可通过环境变量或 `Settings` 配置多个 Skills 路径：

```bash
# 支持多个逗号分隔路径
export AGENT_SKILLS_PATHS="skills,./shared-skills"

工作原理¶

Agent 启动时扫描 skills_paths 下的所有 SKILL.md 文件
解析 frontmatter 提取元信息，构建 Skill 目录
当用户问题匹配某个 Skill 的 description 时，Agent 自动加载对应 SKILL.md 全文
Skill 内容作为系统提示的一部分注入，指导 Agent 行为

注意事项¶

Skill 仅用于指导行为，不是沙箱 — allowed_tools 列表是声明性的
Skill 正文中的命令由 Agent 自主决定是否执行
不要把密钥写入 SKILL.md