构建一个 Plugin

Ghast Plugin 是声明式目录，不需要加载任意 JavaScript 入口。推荐使用 Agent Plugins 1.0.0 根清单，并把各类贡献放在清单声明或约定的目录中。

最小 Plugin

release-tools/
├── plugin.json
└── skills/
    └── release-review/
        └── SKILL.md

plugin.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-tools",
  "version": "1.0.0",
  "description": "Reusable release review workflows for Ghast.",
  "author": {
    "name": "Example Team"
  },
  "license": "MIT"
}

skills/release-review/SKILL.md
---
name: release-review
description: Review a release candidate and report scope, checks, risks, and rollback readiness.
---

# Release review

Review the requested release scope. Report what passed, failed, or remains unverified. Do not publish or push unless the user explicitly asks.

Plugin 必须至少提供一个可运行贡献：Skill、斜杠命令、MCP Server 或 Hook。只有 plugin.json 的空目录虽然能通过清单解析，但安装时会因没有可运行能力而回滚。

name 最长 64 个字符，必须以小写字母或数字开头；其余位置只能使用小写字母、数字、连字符或点。它不能以点/连字符结尾，也不能包含连续的 -- 或 ..。根目录 plugin.json 必须声明上面的 $schema。

Ghast 也能读取兼容清单位置：.ghast-plugin/plugin.json、.codex-plugin/plugin.json 和 .claude-plugin/plugin.json。新 Plugin 优先使用根目录 Agent Plugin 格式，避免为多个宿主维护重复元数据。

声明 Ghast 扩展路径

Agent Plugin 通过 extensions.ai.trapezohe.ghast 声明 Ghast 特有的贡献位置：

plugin.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-tools",
  "version": "1.0.0",
  "description": "Reusable release review workflows for Ghast.",
  "author": { "name": "Example Team" },
  "extensions": {
    "ai.trapezohe.ghast": {
      "commands": "commands",
      "mcpServers": "mcp.json",
      "hooks": "hooks.json"
    }
  }
}

声明的路径必须是 Plugin 根目录内的相对路径，不能使用绝对路径或 .. 逃出目录。Skills 默认从 skills/ 发现；每个 Skill 使用 skills/<name>/SKILL.md。

添加 Skills

每个 Skill 都必须包含有效的 YAML Front Matter：

skills/release-review/SKILL.md
---
name: release-review
description: Review a release candidate and report scope, validation, risks, and rollback readiness.
allowed-tools:
  - Glob
  - Grep
  - Read
  - Bash
---

# Release review

Follow the requested scope. Stop before publish, push, or deployment unless the user explicitly authorizes it.

Plugin 安装并启用后，这些 Skills 会出现在 Skill 库的市场来源中。用户可以逐项关闭 Skill。运行时不会加载已处于停用状态的 Plugin，但当前公开详情页不能把已启用 Plugin 切换为停用；需要停止整组贡献时，应移除可移除的 Plugin。

添加斜杠命令

把每个命令保存为 commands/*.md。文件名是命令名，正文是工作流说明；可以使用简单 Front Matter 提供标题或输入提示。

commands/release-check.md
---
description: Review the current release candidate
argument-hint: <release or branch>
allowed-tools: Glob, Grep, Read, Bash
---

Review $ARGUMENTS. Report scope, checks, blockers, and rollback readiness. Do not publish.

启用 Plugin 后，在输入区键入 / 查找命令。allowed-tools 会成为该命令运行时的严格 Tool 集，并覆盖用户原先的 Tool 选择、关闭自动 Tool 选择；它仍不能绕过“询问/完全访问”、系统权限或远端账号权限。命令应该生成可检查的任务，而不是隐藏高风险动作。

添加 MCP Server

Agent Plugin 的 mcp.json 使用独立 Schema：

mcp.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "release-api": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}

本地 stdio Server：

mcp.json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "release-local": {
      "type": "stdio",
      "command": "./bin/release-server",
      "args": ["--data", "${PLUGIN_DATA}"],
      "cwd": "${PLUGIN_DATA}"
    }
  }
}

command 只能是裸命令（如 node）或以 ./ 开头的 Plugin 内相对路径。变量展开用于 args、env 和 cwd 等路径字段：

${PLUGIN_ROOT}：已安装 Plugin 根目录；
${PLUGIN_DATA}：Ghast 为该 Plugin 准备的可写数据目录。

不要把密钥直接写进 mcp.json。OAuth 和凭证声明必须放在 plugin.json 的 extensions.ai.trapezohe.ghast.mcpServerExtensions.<server>，不能直接加入 mcp.json：

plugin.json
{
  "extensions": {
    "ai.trapezohe.ghast": {
      "mcpServerExtensions": {
        "release-api": {
          "oauthClientRequired": true,
          "oauthRequired": true,
          "credentialHeaders": {
            "Authorization": "Bearer $VAULT:release-token"
          }
        },
        "release-local": {
          "credentialEnv": {
            "API_KEY": "$VAULT:release-key"
          },
          "optionalCredentials": ["release-key"]
        }
      }
    }
  }
}

oauthClientRequired 与 oauthRequired 只适用于远程 Server。credentialHeaders 也只适用于远程连接；值必须是 $VAULT:key 或 Bearer $VAULT:key。credentialEnv 只适用于 stdio，环境变量值必须是 $VAULT:key，且不能覆盖 PLUGIN_ROOT 或 PLUGIN_DATA。optionalCredentials 只能列出同一 Server 已声明的凭证键。还应在 Plugin 详情提供隐私政策、服务条款和撤销说明。

添加生命周期 Hooks

在 extensions.ai.trapezohe.ghast.hooks 中声明一个 JSON 配置文件。Plugin Hooks 支持 SessionStart、UserPromptSubmit 和 SubagentStart，用于向会话提供额外说明或阻止不安全的流程。完整协议见Plugin 生命周期 Hooks。

Hooks 会运行本地命令，属于可执行 Plugin 内容。安装页应明确说明包含 Hooks；命令必须限制输出、设置超时，并且不能依靠输出提升 Tool 权限。

安装前本地验证

在干净目录中准备 Plugin。
选择 Plugins → 本地安装。
选择 Plugin 根目录。
确认详情中实际显示的名称、作者、版本和来源；本地 Plugin 只有提供 details.json 时才有扩展详情。
直接检查包内 Skills、命令、MCP 与 Hooks。详情页只展示 Overview、Starter Prompts、Links、Repository、Skills 和 Apps，不会列出完整命令、单个 MCP Tool 或 Hook 明细。
使用立即试用创建草稿，先运行只读小任务。
如果 Plugin 已处于停用状态，使用启用并确认贡献出现；当前公开详情页不能把已启用 Plugin 切换为停用。
如可移除，卸载后确认 Skills、命令、Hooks 和连接入口不再出现。

不要只验证“安装成功”提示。必须分别验证发现、安装或启用、连接、调用和移除；Skill 的单独开关不代表 Plugin 整体已停止。

发布目录条目

目录条目应至少让用户在安装前看到：

稳定的 Plugin ID、名称、版本和作者；
中英文用途说明；
分类和图标；
安装包地址与完整性摘要；
兼容性；
包含的 Skills、Apps 和开始示例；
官网、仓库、文档、隐私政策与服务条款。

更新安装包时同步更新版本和摘要。改变 OAuth 范围、数据流、Hooks 或高风险 Tool 时，在发布说明中显著标明，并要求用户重新检查连接与试运行。

最小 Plugin​

推荐目录​

声明 Ghast 扩展路径​

添加 Skills​

添加斜杠命令​

添加 MCP Server​

添加生命周期 Hooks​

安装前本地验证​

发布目录条目​