创建一个 Skill

一个可维护的 Skill 应该让另一个人只看说明就能判断：什么时候使用、需要什么输入、按什么顺序工作、如何验证，以及失败时应该停在哪里。

选择作用范围

个人 Skill

适合跨项目复用。打开 Plugins → Skills → 打开文件夹，在打开的目录中为 Skill 新建一个文件夹。

Ghast 还会发现以下用户级目录：

• ~/.claude/skills
• ~/.codex/skills
• ~/.agents/skills
• ~/.pi/agent/skills
• ${XDG_CONFIG_HOME:-~/.config}/opencode/skills
• ${HERMES_HOME:-~/.hermes}/skills

“打开文件夹”进入的是当前 Ghast Profile 隔离的 Workspace Skill 目录。外部 Agent 的全局目录由对应工具管理；同名 Skill 出现多份时，应在详情中核对来源和实际路径。

项目 Skill

适合只对一个项目成立的目录规则、命令、验收步骤或领域知识。推荐位置是 <project>/.agents/skills/<skill>/SKILL.md。Ghast 也兼容项目内的 .claude/skills、.codex/skills、.pi/skills、.opencode/skills 和 .hermes/skills；添加项目后刷新 Skill 库。

不要把客户密钥、临时发布地址或只对某次任务成立的要求写进全局 Skill。

最小目录

release-review/
└── SKILL.md

需要时再添加支持文件：

release-review/
├── SKILL.md
├── references/
│   └── checklist.md
├── scripts/
│   └── verify.sh
└── templates/
    └── report.md

SKILL.md 放触发条件和主流程。较长的参考资料、脚本和模板分开保存，并在主文件中说明何时读取或运行。不要为还不存在的需求预先搭建目录。

必需的 YAML Front Matter

文件必须以 YAML Front Matter 开头，且至少包含 name 和 description：

---
name: release-review
description: 审查发布候选改动，核对范围、验证结果与回滚准备，并输出发布结论。
allowed-tools:
  - Glob
  - Grep
  - Read
  - Bash
---

# Release review

## When to use

用户要求审查一个准备发布的本地项目或变更集时使用。

常用字段：

字段	是否必需	用途
name	是	稳定、简短的 Skill 名称。
description	是	说明何时应该选择这个 Skill；应包含任务对象和结果。
license	否	说明分发和复用许可。
compatibility	否	说明平台、应用或运行条件。
allowed-tools	否	列出流程确实需要的 Tool 名称。
always-inject	否	每次都加载；只适合极少数稳定且普遍适用的规则。

description 是自动选择的重要依据。不要写“帮助处理各种任务”这类无法区分场景的描述；应写清触发条件与交付结果。

推荐正文结构

# 名称

## When to use
明确触发条件和不适用情况。

## Inputs
列出开始前必须获得的文件、范围、账户或用户决定。

## Workflow
按顺序写动作；在高风险步骤前写清检查点。

## Verification
说明什么证据才算完成。

## Stop conditions
说明何时不得继续猜测或扩大范围。

## Output
给出最终答复或产物的格式。

正文使用命令式步骤，避免长篇解释产品概念。把“必须”和“建议”分开写；如果某一步可能发送、删除、发布、支付或覆盖数据，明确要求用户授权与最终核对。

声明 Tools

allowed-tools 只列出可复用流程真正需要的 Tool。例如只读审查不应加入 Edit 或 Write。显式加载 Skill 时，这些名称可能补入当前运行的 Tool 集；它们不会授予权限，也不会保证该 Tool 在所有模型和模式中可用。

always-inject: true 会让已启用、可信且未归档的 Skill 在普通 Skill 选择为空时仍可进入本轮候选；它不会在输入区增加启停控件。图片生成会清空全部 Skill。模型仍通过 Skill Tool 读取完整内容，allowed-tools 仍受当前模式的能力范围与权限限制。只把它用于确实需要影响每个普通任务的稳定规则。

使用 MCP Tool 时，名称可能随 Server 版本变化。不要把账号密钥写进 Skill；让用户通过 Plugin 连接或 MCP 配置完成授权。

使用脚本

脚本是可执行内容，应满足：

• 输入和输出格式明确；
• 默认不修改或删除用户数据；
• 失败时返回非零状态并保留可读错误；
• 不打印密钥、Cookie 或完整环境变量；
• 在 SKILL.md 中说明运行条件、工作目录和验证方式；
• 有平台限制时写入 compatibility 或正文。

第三方 Skill 中的脚本在启用前必须人工检查。不要依赖“来自市场”或“能被扫描到”来判断可信。

让 Ghast 发现 Skill

1. 把 SKILL.md 放在独立目录中。
2. 回到 Plugins → Skills。
3. 选择顶部的刷新。
4. 搜索 name，打开详情。
5. 核对来源、路径、完整内容和兼容性。
6. 打开在 Ghast 中启用。
7. 选择立即试用，补充一个小任务后发送。

如果解析失败，重点检查 Front Matter 的 ---、YAML 缩进，以及 name、description 是否为非空文字。

验收一个新 Skill

至少用三类任务测试：

1. 应该触发：描述与目标完全匹配，确认 Ghast 加载 Skill 并遵循输出格式。
2. 不应触发：相邻但不同的任务，确认自动模式不会滥用它。
3. 缺少输入：故意不给关键材料，确认 Skill 会停止并说明缺什么，而不是编造。

还要检查 Tool 最小化、错误可见性、敏感数据处理和停止条件。通过后再设为长期启用；always-inject 只在每个任务都确实需要时使用。

更新与版本管理

修改后刷新 Skill 库，并重新执行最小验收。改变触发范围、Tool、脚本或输出契约时，在正文中说明变化；由 Plugin 分发的 Skill 应随 Plugin 版本管理，不要直接修改安装副本。