跳转到主要内容

​
定制 Skill

Skill 是 Trellis 0.5 的主要扩展点。原生带有的大部分工作流（brainstorm、before-dev、check、update-spec、break-loop）都以 auto-trigger skill 的形式交付。本章说明如何添加自己的 skill。

​
Command vs. Sub-agent vs. Skill

CommandSub-agentSkill
用途用户显式入口有自己角色的隔离子进程可复用的工作流模块
触发/trellis:xxx通过 Task 工具 spawn平台根据用户意图自动匹配
粒度会话边界角色级能力或阶段级
跨平台每平台一份文件每平台一份文件每平台一个文件夹（结构一致）
AI 应该基于上下文自动触发时用 skill；由用户决定时用 command；需要隔离 prompt 和约束时用 sub-agent。

​
Skill 文件格式

Skill 是包含 SKILL.md 的文件夹： 
.claude/skills/my-skill/
├── SKILL.md
└── references/         # 可选的支持文件
SKILL.md 用 YAML frontmatter，平台会对这段文本做匹配： 
---
name: my-skill
description: |
  这个 skill 应该什么时候被触发的一句话说明。平台根据这段文本决定是否 auto-trigger。
---

# My Skill

skill 被触发时 AI 要遵循的指令。

## 步骤

1. 读相关文件。
2. 执行逻辑。
3. 按以下格式汇报结果：...
Skill 在全部 13 个配置平台上都可用，位置按平台不同：
平台位置
Claude Code.claude/skills/{name}/SKILL.md
Cursor.cursor/skills/{name}/SKILL.md
OpenCode.opencode/skills/{name}/SKILL.md
Codex.codex/skills/{name}/SKILL.md（同时拷一份到 .agents/skills/ 给跨平台生态用）
Kiro.kiro/skills/{name}/SKILL.md
Gemini CLI.gemini/skills/{name}/SKILL.md
Qoder.qoder/skills/{name}/SKILL.md
CodeBuddy.codebuddy/skills/{name}/SKILL.md
Copilot.github/skills/{name}/SKILL.md
Droid.factory/skills/{name}/SKILL.md
Kilo.kilocode/skills/{name}/SKILL.md
Antigravity.agent/skills/{name}/SKILL.md
Windsurf.windsurf/skills/{name}/SKILL.md
.agents/skills/{name}/SKILL.md（agentskills.io 跨平台共享层）由 Codex 的 configurator 写入，可被 Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等读该标准的 agent 直接消费。

​
写出能稳定触发的 skill

description 字段是平台用来匹配的。把它写成「什么情况下应该触发这个 skill」的条件描述，而不是 skill 自己的身份介绍。 对比： 
# 好：描述触发条件
description: |
  用于用户刚修完 bug、想理解根因并防止再次发生的场景。运行 5 维分析。

# 差：描述 skill 身份
description: |
  break-loop skill 是分析 bug 的。
Skill body 应该：
  1. 在 skill 自己的话里再次声明触发条件，让 AI 自检是否匹配正确。
  2. 告诉 AI 动手前要读哪些文件。
  3. 给一个固定的输出格式，让每次调用的结果一致。

​
示例：一个 api-doc skill

.claude/skills/api-doc/SKILL.md： 
---
name: api-doc
description: |
  用于用户刚加 / 改了后端 API 端点并希望更新 OpenAPI 文档的场景。解析 diff，提取端点签名，写文档。
---

# api-doc

从当前 diff 自动生成 API 文档。

## 触发检查

运行前先确认 diff 包含 `src/api/` 或 `src/routes/` 下的改动；不包含就先和用户确认再继续。

## 步骤

1. `git diff --name-only HEAD` 列出改动文件。
2. 对每个改动的端点文件，提取 route、HTTP 方法、请求 schema、响应 schema。
3. 更新 `docs/openapi.yaml`。
4. 汇报新增、修改、删除的端点。

## 输出格式

```
新增端点：
  POST /api/foo
修改端点：
  PUT /api/bar（请求体变更）
删除端点：
  （无）
```

​
分享 skill

跨项目分发一个 skill：
  1. 把规范版 SKILL.md 放在 packages/cli/src/templates/common/skills/{name}/SKILL.md（想上游贡献的话），或以单独 npm 包发布。
  2. 在每个平台的 configurator 里加一步，把 skill 拷贝或适配进该平台的布局。
  3. Skill 随 Trellis 发布版本一起进化，保证 migration 一致。
外部 skill：想引入社区 skill，把文件夹拉进对应平台目录并 commit。Trellis 目前没有原生的外部 skill 安装器。