SuperPowers 技能自动触发的核心，在于为不同 AI 编码代理平台（Claude Code 和 Cursor）正确配置各自的插件清单文件，并通过 SessionStart 钩子在会话开始时执行初始化脚本。本文基于仓库源码，详解两大平台的插件元数据结构与钩子定义，并重点剖析其跨平台兼容设计：一个能在 Windows CMD 和 Unix bash 中同时有效执行的 polyglot 包装器脚本，解决了 .sh 脚本无法在 Windows 下直接运行的难题。

Claude Code、Cursor 与 Hooks：SuperPowers 插件清单和跨平台 SessionStart 设计

要让 SuperPowers 的核心工作流——从 using-superpowers 技能发现，到头脑风暴、编写计划，再到子代理驱动开发和测试驱动开发——在你的 AI 编码代理启动时自动生效，关键在于插件配置和初始化钩子。本文将拆解 .claude-plugin 和 .cursor-plugin 两份关键清单文件，并深入其 SessionStart 钩子的实现，特别是它如何用一份脚本兼容 Windows、macOS 和 Linux。

一、平台插件清单：元数据与路径映射

插件清单是平台识别和加载 SuperPowers 的“身份证”。不同平台有不同的配置要求。

1. Claude Code：`.claude-plugin/plugin.json`

Claude Code 的配置相对标准化，核心是 plugin.json：

{
  "name": "superpowers",
  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "5.1.0",
  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
}

这份清单定义了插件的名称、版本和关键词，是安装和识别的基础。同目录下的 marketplace.json 则定义了市场源：

{
  "plugins": [
    {
      "name": "superpowers",
      "version": "5.1.0",
      "source": "./"
    }
  ]
}

“source”: “./” 表明插件内容来自本地目录。用户可以通过官方市场或 SuperPowers 开发市场安装它。

2. Cursor：`.cursor-plugin/plugin.json`

Cursor 的清单结构更复杂，明确指定了技能、代理和钩子的路径：

{
  "name": "superpowers",
  "version": "5.1.0",
  "skills": "./skills/",
  "agents": "./agents/",
  "commands": "./commands/",
  "hooks": "./hooks/hooks-cursor.json"
}

关键点在最后四个字段：

skills：指向存放所有 SKILL.md 技能文档的目录。
hooks：这是触发机制的核心，它指向一个独立的钩子配置文件 hooks-cursor.json。Cursor 启动时会读取此文件并执行其中定义的命令。

二、SessionStart 钩子：技能加载的触发点

两个平台都需要在会话开始时执行命令，以触发 SuperPowers 的技能发现流程。钩子的定义方式因平台而异。

1. Claude Code 的钩子：`hooks/hooks.json`

Claude Code 的钩子配置位于 hooks/hooks.json：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

matcher: "startup|clear|compact"：这意味着钩子会在 Claude Code 启动（startup）、清除上下文（clear）或压缩上下文（compact） 时触发。这确保了无论代理以何种方式进入“新会话”状态，都会尝试加载 SuperPowers。
command：执行的并非一个直接的 .sh 脚本，而是一个跨平台的 polyglot 包装器 run-hook.cmd，并传递参数 session-start。

2. Cursor 的钩子：`hooks/hooks-cursor.json`

Cursor 的钩子配置独立存在：

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "./hooks/run-hook.cmd session-start"
      }
    ]
  }
}

注意字段名是小驼峰 sessionStart。它同样指向了 polyglot 包装器 run-hook.cmd。

三、跨平台设计：Polyglot 包装器的原理与实现

钩子脚本需要在用户的系统 Shell 中执行，而 Windows 默认是 CMD.exe，macOS/Linux 是 bash。直接调用 .sh 脚本在 Windows 下会失败。SuperPowers 的解决方案是创建一个 “多语言”包装器 run-hook.cmd，它能同时被 CMD 和 bash 正确解析。

其代码结构如下（参考 docs/windows/polyglot-hooks.md）：

: << 'CMDBLOCK'
@echo off
set "SCRIPT_DIR=%~dp0"
set "SCRIPT_NAME=%~1"
"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
exit /b
CMDBLOCK

# Unix shell runs from here
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SCRIPT_NAME="$1"
shift
"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

工作流程解析：

在 Windows CMD 中：

: << 'CMDBLOCK'：CMD 将 : 看作标签定义，<< 被忽略。
@echo off：关闭命令回显。
关键命令：调用 Git for Windows 提供的 bash.exe。-l 参数以登录模式启动 bash，确保环境变量（如 PATH）正确加载。cygpath -u 将 Windows 路径（如 C:\path）转换为 Unix 格式（/c/path）。
exit /b：CMD 执行到此处退出，不再解释后面的 bash 代码。

在 Unix/macOS bash 中：

: << 'CMDBLOCK'：: 是空操作，<< 'CMDBLOCK' 开始一个 Here Document，将 CMDBLOCK 之前的所有内容（即 Windows CMD 部分）吞没。
执行从 # Unix shell runs from here 注释之后的 bash 脚本逻辑，直接调用传入的参数（如 session-start）对应的脚本。

这样，一个 run-hook.cmd 文件无需修改即可在不同系统上被正确执行。对于 Cursor，其 session-start 命令也指向这个包装器，依赖相同的跨平台原理。

四、操作与验证指南

1. 安装与触发

Claude Code：根据 README，可使用以下命令安装：
```
/plugin install superpowers@claude-plugins-official
```
或从 SuperPowers 市场安装。安装后，任何新会话的开始（启动、清屏、压缩）都会自动触发 SessionStart 钩子，代理将开始发现并加载相关技能。
Cursor：在 Cursor Agent 聊天中使用 /add-plugin superpowers 或在市场中搜索安装。安装后，在新会话开始时，Cursor 会执行 .cursor-plugin/plugin.json 中 hooks 字段指定的命令。

2. 验证钩子是否生效

最直接的验证方法是观察代理行为。一个已成功加载 SuperPowers 的 Claude Code 代理，在接到开发任务（如“我们做个 React 待办列表”）时，不会立即开始编码，而是会首先尝试使用 brainstorming 技能与你澄清需求、形成设计。如果代理直接进入了传统编码模式，很可能意味着钩子未成功执行。

3. Windows 环境下常见问题排查

基于 docs/windows/polyglot-hooks.md：

“bash is not recognized”：run-hook.cmd 中 bash.exe 的路径默认为 C:\Program Files\Git\bin\bash.exe。如果你的 Git 安装在其他位置，需要修改此路径。
“cygpath: command not found”：确保调用 bash 时使用了 -l 参数，使其作为登录 shell 启动以加载完整的 PATH。
脚本被文本编辑器打开：检查 hooks.json 或 hooks-cursor.json 中的 command 字段，确保它指向的是 .cmd 包装器，而不是直接的 .sh 文件。

4. 贡献钩子时的注意事项

根据 CLAUDE.md 的严格约束，SuperPowers 核心仓库的 PR 拒绝率极高。如果你计划贡献钩子或技能相关更改，必须：

遵循 writing-skills 技能进行开发和测试。
解决真实存在的问题，而非理论推测。
确保更改适用于所有支持的编码代理，而非特定项目。
PR 必须填写完整模板，并经过人类严格审查。

FAQ

Q: SuperPowers 在 Windows 的 CMD 和 PowerShell 下都能工作吗？ A: 通过 hooks.json 指向 polyglot 包装器 run-hook.cmd 的设计，可以在 CMD 下正常工作。PowerShell 通常也会调用系统的默认钩子执行机制，兼容性较好。核心是确保 Git for Windows 已安装，并且 run-hook.cmd 中的 bash.exe 路径正确。

Q: 为什么在 Cursor 中安装了插件，但技能没有自动触发？ A: 请检查 .cursor-plugin/plugin.json 中的 hooks 字段是否正确指向了 hooks-cursor.json，并确保该文件中的 sessionStart 命令对应的 run-hook.cmd 脚本存在且可执行。同时，确认 Cursor 平台本身的钩子加载机制已正常工作。

Q: 我可以修改钩子，只在特定项目下触发 SuperPowers 吗？ A: CLAUDE.md 明确指出，项目特定或个人配置的钩子不属于核心，应作为单独的插件发布。因此，不建议修改核心钩子来实现项目级控制，这可能导致你的 PR 被拒绝。

Claude Code、Cursor 与 Hooks：SuperPowers 插件清单和跨平台 SessionStart 设计 #

一、平台插件清单：元数据与路径映射 #

1. Claude Code：.claude-plugin/plugin.json #

2. Cursor：.cursor-plugin/plugin.json #

二、SessionStart 钩子：技能加载的触发点 #

1. Claude Code 的钩子：hooks/hooks.json #

2. Cursor 的钩子：hooks/hooks-cursor.json #

三、跨平台设计：Polyglot 包装器的原理与实现 #

四、操作与验证指南 #

1. 安装与触发 #

2. 验证钩子是否生效 #

3. Windows 环境下常见问题排查 #

4. 贡献钩子时的注意事项 #

FAQ #