教程概述

Planning-with-files 支持 16+ 主流 AI 编程平台，分为两类：

• 增强支持：提供 Hooks 自动化 + Skills，自动重读计划、提醒更新、验证完成
• 标准支持：实现 Agent Skills 规范，通过 npx skills add 一键安装

你将学到

• ✅ 16+ 平台的安装方法
• ✅ Plugin 与 Skill 的区别
• ✅ 如何验证安装成功
• ✅ 常见安装问题排查

支持平台一览

增强支持平台（Hooks + Skills）

标准支持平台（Agent Skills）

快速安装（推荐）

一键安装命令

# 英文版
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

# 中文版
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

# 繁体中文版
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

这个命令适用于所有支持 Agent Skills 规范的平台。

Claude Code 安装（推荐）

Claude Code 是 Planning-with-files 的首选平台，提供完整的 Plugin 和 Hooks 支持。

方法 A：Plugin Marketplace（推荐）

flowchart LR
    A[添加 Marketplace] --> B[安装 Plugin]
    B --> C[验证安装]
    C --> D[开始使用]

    style A fill:#e1f5ff
    style B fill:#e1f5ff

Step 1：添加 Marketplace

在 Claude Code 中运行：

/plugin marketplace add OthmanAdi/planning-with-files

Step 2：安装 Plugin

/plugin install planning-with-files@planning-with-files

Step 3：验证安装

开始新会话，你应该看到：

[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /plan

方法 B：手动安装

# 克隆到插件目录
mkdir -p .claude/plugins
git clone https://github.com/OthmanAdi/planning-with-files.git .claude/plugins/planning-with-files

# 加载插件
/plugin load .claude/plugins/planning-with-files

可用命令

更新 Plugin

/plugin update planning-with-files@planning-with-files

Cursor 安装

Cursor 通过 Skills + Hooks 提供完整支持。

安装步骤

Step 1：安装 Skills

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Step 2：配置 Hooks

创建或编辑 .cursor/hooks.json：

{
  "hooks": {
    "SessionStart": {
      "command": "bash .cursor/hooks/session-start.sh"
    },
    "PreToolUse": {
      "command": "bash .cursor/hooks/pre-tool-use.sh"
    },
    "PostToolUse": {
      "command": "bash .cursor/hooks/post-tool-use.sh"
    },
    "Stop": {
      "command": "bash .cursor/hooks/check-complete.sh"
    }
  }
}

Step 3：复制 Hook 脚本

# 从仓库复制 hooks 脚本
cp -r planning-with-files/.cursor/hooks .cursor/
chmod +x .cursor/hooks/*.sh

验证安装

在 Cursor Agent 聊天中输入：

我想开始一个新任务的规划

如果 AI 开始询问任务目标并建议创建 task_plan.md，说明安装成功。

GitHub Copilot 安装

Copilot 通过 Hooks 配置提供支持，包括独特的 errorOccurred Hook。

安装步骤

Step 1：安装 Skills

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Step 2：配置 Hooks

创建 .github/hooks/planning-with-files.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .github/hooks/scripts/pre-tool-use.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .github/hooks/scripts/post-tool-use.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "bash .github/hooks/scripts/check-complete.sh"
      }
    ],
    "errorOccurred": [
      {
        "type": "command",
        "command": "bash .github/hooks/scripts/on-error.sh"
      }
    ]
  }
}

errorOccurred Hook 说明

Copilot 的 errorOccurred Hook 会在工具执行失败时触发，自动记录错误到 task_plan.md 的 Errors 表格中。

Gemini CLI 安装

Gemini CLI 通过 Skills + Hooks 提供完整支持。

安装步骤

Step 1：安装 Skills

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Step 2：配置 Hooks

创建 .gemini/settings.json：

{
  "hooks": {
    "SessionStart": {
      "command": "bash .gemini/hooks/session-start.sh"
    },
    "PreToolUse": {
      "command": "bash .gemini/hooks/pre-tool-use.sh"
    },
    "PostToolUse": {
      "command": "bash .gemini/hooks/post-tool-use.sh"
    },
    "Stop": {
      "command": "bash .gemini/hooks/check-complete.sh"
    }
  }
}

Codex 安装

Codex 通过 Skills + Hooks 提供支持。

安装步骤

Step 1：安装 Skills

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Step 2：配置文件位置

将 Skills 放入 .codex/skills/ 目录：

.codex/
└── skills/
    └── planning-with-files/
        └── SKILL.md

Mastra Code 安装

Mastra Code 是较新的 AI 编程平台，提供完整的 Skills + Hooks 支持。

安装步骤

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Skills 将被放置在 .mastracode/skills/ 目录。

其他平台快速安装

Kiro

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Skills 放置在 .kiro/skills/ 目录，支持 Agent Skills 规范。

OpenClaw

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Skills 放置在 .openclaw/skills/ 目录。

Kilocode

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Skills 放置在 .kilocode/skills/ 目录。

AdaL CLI (Sylph AI)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Skills 放置在 .adal/skills/ 目录。

Pi Agent

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

Skills 放置在 .pi/skills/ 目录，支持 npm 包管理。

Continue.dev

npx skills add OthmanAdi/planning-with-files --skill planning-with-files

除了 Skills，还可以创建 .continue/prompts/planning.prompt 用于斜杠命令。

Windows 平台注意事项

PowerShell Hooks

Planning-with-files 提供了 PowerShell 版本的 Hooks 脚本：

scripts/
├── init-session.ps1
└── check-complete.ps1

配置示例（Cursor on Windows）

{
  "hooks": {
    "PreToolUse": {
      "command": "powershell -File .cursor/hooks/pre-tool-use.ps1"
    }
  }
}

路径处理

Windows 路径使用反斜杠或正斜杠：

// 两种格式都可以
"command": "bash .cursor/hooks/pre-tool-use.sh"
"command": "bash .\\cursor\\hooks\\pre-tool-use.sh"

验证安装成功

测试用例 1：基本触发

输入：

我需要分析一个代码库，帮我规划一下

预期行为：

• ❌ 直接开始分析代码 → 失败
• ✅ 询问任务目标，建议创建 task_plan.md → 成功

测试用例 2：命令调用

输入：

/plan 分析这个项目的架构

预期行为：

• ✅ 创建三个文件（task_plan.md、findings.md、progress.md）
• ✅ 开始规划阶段

测试用例 3：Hooks 验证

操作：完成一些工作后尝试停止

预期行为：

• ❌ 直接停止，即使阶段未完成 → 失败
• ✅ Stop Hook 提醒未完成的阶段 → 成功

常见问题排查

问题 1：安装后技能不触发

症状：AI 不自动创建规划文件

检查清单：

1. 确认 Skills 目录位置正确：

   # Claude Code
   ls ~/.claude/skills/planning-with-files/
   
   # Cursor
   ls .cursor/skills/planning-with-files/
   

2. 确认 SKILL.md 文件存在

3. 尝试手动触发：

   /planning-with-files:plan
   

问题 2：Hooks 不触发

症状：阶段完成不会自动更新状态

解决方案：

1. 检查 hooks 配置文件格式
2. 确认脚本有执行权限：

   chmod +x .cursor/hooks/*.sh
   

3. 检查脚本路径是否正确

问题 3：Windows 上脚本执行失败

症状：Hooks 报错

解决方案：

1. 使用 PowerShell 脚本：

   {
     "hooks": {
       "PreToolUse": {
         "command": "powershell -File .cursor/hooks/pre-tool-use.ps1"
       }
     }
   }
   

2. 或启用 WSL/Git Bash

问题 4：多版本冲突

症状：安装了多个版本的 skill

解决方案：

# 清理旧版本
rm -rf ~/.claude/skills/planning-with-files

# 重新安装
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

更新与卸载

更新

Plugin 方式：

/plugin update planning-with-files@planning-with-files

手动方式：

cd .claude/plugins/planning-with-files
git pull origin main

Skills 方式：

# 删除后重新安装
rm -rf ~/.claude/skills/planning-with-files
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

卸载

Plugin 方式：

/plugin uninstall planning-with-files@planning-with-files

手动方式：

rm -rf .claude/plugins/planning-with-files
rm -rf .claude/skills/planning-with-files

下一步

安装完成后，继续学习：

• 📖 教程 3：快速开始：第一个规划任务
• 📖 教程 4：task_plan.md 深度解析

📚 完整教程系列导航

你正在阅读本系列的 教程 2，以下是完整目录：

1. 教程 1：系列介绍与核心概念
2. 教程 2：多平台安装指南（当前）
3. 教程 3：快速开始 - 第一个规划任务
4. 教程 4：task_plan.md 深度解析
5. 教程 5：findings.md 研究管理
6. 教程 6：progress.md 会话日志
7. 教程 7：实战研究型任务
8. 教程 8：实战开发型任务
9. 教程 9：Hooks 机制深度配置
10. 教程 10：与 Superpowers 协同

系列导航：

• ← 上一篇：教程 1：系列介绍与核心概念
• → 下一篇：教程 3：快速开始：第一个规划任务

参考资源：

• 官方仓库：github.com/OthmanAdi/planning-with-files
• Agent Skills 规范：agentskills.io
• 问题反馈：GitHub Issues