手动安装 superpowers 插件到 Claude Code 的方案

分析问题

用户需要在 Claude Code 中手动安装一个名为 "superpowers" 的插件，该插件托管在 GitHub 上 (https://github.com/obra/superpowers)。通过分析 /home/tang/.claude 目录的结构，我已经了解了 Claude Code 的插件系统工作原理。

插件系统架构分析

Claude Code 的插件系统存储在 /home/tang/.claude/plugins/ 目录下，其结构如下：

• cache/: 存储已安装插件的实际代码
• marketplaces/: 存储插件市场信息
• installed_plugins.json: 记录已安装插件的元数据
• known_marketplaces.json: 已知插件市场配置

细化方案

方案一：通过 GitHub 直接克隆安装（推荐）

步骤 1：准备插件存放目录

# 创建用于存储手动安装插件的目录结构
mkdir -p /home/tang/.claude/plugins/cache/manual

步骤 2：克隆 superpowers 项目

# 克隆项目到本地插件目录
cd /home/tang/.claude/plugins/cache/manual
git clone https://github.com/obra/superpowers.git

# 进入项目目录
cd superpowers

步骤 3：检查并创建插件配置

# 检查项目结构
ls -la

# 如果项目没有 .claude-plugin 目录，创建一个
if [ ! -d ".claude-plugin" ]; then
    mkdir -p .claude-plugin

    # 创建插件配置文件 plugin.json
    cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "superpowers",
  "description": "Manual installation of superpowers plugin",
  "author": {
    "name": "obra"
  }
}
EOF
fi

步骤 4：获取 git 提交 SHA

# 获取当前提交的 SHA
GIT_SHA=$(git rev-parse --short HEAD)
echo "当前提交 SHA: ${GIT_SHA}"

步骤 5：创建插件版本目录

# 在手动插件目录下创建以提交 SHA 命名的版本目录
mkdir -p /home/tang/.claude/plugins/cache/manual/superpowers/${GIT_SHA}

# 复制插件文件到版本目录
cp -r /home/tang/.claude/plugins/cache/manual/superpowers/* /home/tang/.claude/plugins/cache/manual/superpowers/${GIT_SHA}/

步骤 6：更新 installed_plugins.json

# 更新已安装插件列表
cat > /home/tang/.claude/plugins/installed_plugins.json << 'EOF'
{
  "version": 2,
  "plugins": {
    "superpowers@manual": [
      {
        "scope": "global",
        "installPath": "/home/tang/.claude/plugins/cache/manual/superpowers/${GIT_SHA}",
        "version": "${GIT_SHA}",
        "installedAt": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
        "lastUpdated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
        "gitCommitSha": "${GIT_SHA}",
        "projectPath": null
      }
    ]
  }
}
EOF

# 注意：需要将 ${GIT_SHA} 替换为实际的提交 SHA

方案二：通过复制到项目目录（项目级安装）

如果只需要在特定项目中使用该插件，可以将其复制到项目的 .claude/ 目录：

# 进入项目目录
cd /home/tang/project

# 创建 .claude/skills/ 目录
mkdir -p .claude/skills/superpowers

# 克隆项目到技能目录
git clone https://github.com/obra/superpowers.git .claude/skills/superpowers

# 检查是否需要创建插件配置
cd .claude/skills/superpowers
if [ ! -d ".claude-plugin" ]; then
    mkdir -p .claude-plugin
    cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "superpowers",
  "description": "Project-level installation of superpowers plugin",
  "author": {
    "name": "obra"
  }
}
EOF
fi

验证方案

安装后验证

1. 重启 Claude Code 或刷新插件列表
2. 运行 /plugin 命令检查插件是否已安装
3. 尝试使用插件提供的功能

故障排除

如果插件未正确加载：

1. 检查 /home/tang/.claude/plugins/installed_plugins.json 中的路径是否正确
2. 确保插件目录结构包含 .claude-plugin/plugin.json 文件
3. 检查插件是否包含有效的技能定义（SKILL.md 文件）
4. 查看 Claude Code 的日志文件以获取错误信息

最佳实践

• 定期更新插件以获取最新功能
• 维护 plugins 目录的结构，避免混乱
• 使用 git 管理插件代码，以便于更新和版本控制
• 对于项目级插件，考虑添加到版本控制中

---

注意：上述方案中的 ${GIT_SHA} 需要在执行时替换为实际的值。可以通过 git rev-parse --short HEAD 命令获取。