using-git-worktrees

using-git-worktrees 技能概览

using-git-worktrees 技能是做什么的

using-git-worktrees 技能会帮助代理在开始新任务时创建一个独立的 Git worktree，而不是复用你当前的 checkout。它真正解决的问题不只是“执行一下 git worktree add”，而是先选对目录、确认本地 worktree 文件夹已被安全忽略，并避免污染主工作区。

谁适合安装

这个技能尤其适合经常遇到以下场景的人：

• 开启新功能开发时，希望当前改动保持原样不被碰到
• 需要并行查看或实现多个分支
• 想让 AI 驱动的编码流程更安全，降低来回切分支的风险
• 需要一套可重复的方法，在不同项目里创建隔离工作区

如果你经常对助手说“在单独分支里开始这个任务”或“别动我当前这棵工作树”，那 using-git-worktrees 会非常合适。

它要完成的核心任务

用户真正关心的结果只有一个：以尽量少的初始化失误，在隔离工作区中开始实现。using-git-worktrees 技能之所以有用，是因为它在创建前加入了一套判断流程：

• 如果项目里已经有 worktree 目录，优先沿用
• 如果 CLAUDE.md 里写明了仓库偏好，则遵循该约定
• 如果没有安全默认值，就先询问用户
• 如果要在项目内创建 worktree，会先验证 ignore 行为

因此它比那种一上来就直接执行 shell 命令的通用 prompt 更可靠。

它和普通 prompt 的区别在哪里

普通 prompt 可能懂 Git worktree 的概念，但仍然会漏掉仓库特定的配置细节。这个技能为代理提供了明确的执行顺序和安全检查，尤其是在目录放置和 .gitignore 处理上更严格。这正是 using-git-worktrees for Git Workflows 的主要差异点：减少初始化阶段的猜测，而不是多讲 Git 理论。

哪些情况下不适合用这个技能

以下情况建议跳过 using-git-worktrees：

• 你始终只在单分支、单目录里工作
• 你的环境不允许额外创建工作目录
• 你只是想快速切个分支，不需要隔离执行
• 团队已经有一套固定 wrapper script，完整替代了这里的判断逻辑

这些情况下，直接用 shell 命令或团队内部流程往往更快。

如何使用 using-git-worktrees 技能

安装 using-git-worktrees 的上下文

从 obra/superpowers 技能集合安装：

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

安装完成后，当你准备开始一项不应复用当前 checkout 的工作时，就可以调用它。

用户实际会如何触发这个技能

仓库里明确要求代理在开始时声明自己正在使用该技能。实际使用时，你的请求最好把“需要隔离工作区”表达清楚，例如：

• “Use using-git-worktrees and set up an isolated workspace for this feature.”
• “Before implementing, create a worktree for branch feature/auth-refresh.”
• “Use the using-git-worktrees skill so my current changes stay untouched.”

这样更容易让代理按技能执行，而不是临场自由发挥。

这个技能需要什么输入

为了得到更好的结果，建议提供：

• 目标分支名
• 这是新分支还是已有分支
• 你更偏好项目内还是全局 worktree 存储
• 仓库级约束，比如“必须位于 project root 下”

最少但有用的输入：

• 分支名或任务名
• 允许创建 worktree

更理想的输入：

• 分支名
• 期望的目录策略
• 当前 checkout 是否有未提交改动
• 建好之后接下来要做什么，比如“然后开始实现”

内置的目录选择逻辑

using-git-worktrees skill 最有价值的部分，其实就在目录选择流程。它会按以下优先级处理：

1. 如果 .worktrees 已存在，就使用它
2. 否则如果 worktrees 已存在，就使用它
3. 否则检查 CLAUDE.md 是否记录了偏好
4. 如果仍没有结果，就询问用户从以下两者中选择：
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

这很重要，因为如果每次会话都临时发明一个新位置，worktree 很快就会变得难以维护、四处蔓延。

在项目内创建前的安全检查

一个关键的落地细节是：如果 worktree 要建在仓库内部，这个技能会先确认目标目录已经被忽略，再执行创建。这样可以避免误把 worktree 文件夹纳入版本控制，或者让 git status 输出变得杂乱。

相比随手写的用法，这是个很实在的优势。如果你的团队打算在项目内放 worktree，那么在依赖这套流程之前，最好先确保 .worktrees/ 或 worktrees/ 已经被 Git 忽略。

更强的 using-git-worktrees 提示词写法

弱提示词：

• “Start working on OAuth cleanup.”

更强的提示词：

• “Use using-git-worktrees to create an isolated workspace for new branch feature/oauth-cleanup. Prefer .worktrees/ if safe and ignored. After setup, begin implementation without touching my current checkout.”

为什么这样更好：

• 明确点名技能
• 给出目标分支
• 说明目录偏好
• 告诉代理建好之后下一步做什么

创建之后建议怎么走流程

一个实用的 using-git-worktrees usage 流程是：

1. 先让代理使用这个技能
2. 确认 worktree 位置和分支名
3. 让代理把工作切换到新工作区
4. 之后再开始改代码、跑测试或制定实现方案

如果你当前 checkout 里已经有未提交改动，这套顺序尤其有用。

仓库里优先要读哪些文件

这里真正有信息量的源文件只有一个：SKILL.md。

重点看它的这些内容：

• 目录优先级的精确顺序
• 没有偏好时，应该如何向用户发问
• ignore 校验的要求
• 告知代理需要先声明技能使用的触发措辞

这个技能本身很轻量，所以实际决定要不要采用，关键就看这套逻辑是否符合你们团队的 Git workflow。

在依赖它之前需要知道的实际限制

这个技能的边界很明确，也就是它没有提供以下能力：

• wrapper scripts
• 自动化辅助工具
• 分支命名约束
• 过期 worktree 的清理流程
• 针对不同平台的 fallback

所以 using-git-worktrees install 带来的是“如何做判断”的指导，而不是一整套 worktree 管理系统。如果你需要完整的生命周期自动化，最好再配合自己的 shell 工具链使用。

using-git-worktrees 技能 FAQ

using-git-worktrees 适合新手吗？

适合，但前提是这个新手已经理解基本的 branch 概念，并且想要一个更安全的“不要碰我当前工作区”流程。它不是 Git 教程，而是一个结构化的初始化技能。完全零基础的用户，可能仍然需要先弄懂什么是 worktree，以及它和 clone 的区别。

它比普通 prompt 更擅长解决什么问题？

普通 prompt 经常跳过最麻烦的部分：worktree 应该建在哪，以及项目内目录是否已被安全忽略。技能里编码好的 using-git-worktrees guide 能减少这类初始化失误，也让代理行为更一致。

必须使用项目内 worktree 才能用它吗？

不需要。如果本地没有现成目录，且仓库里也没有记录偏好，这个技能可以引导你改用全局位置。所以即使你不希望仓库里出现额外文件夹，它仍然可用。

using-git-worktrees 能用于已有分支吗？

可以。把已有分支 checkout 到独立工作区时，这套流程依然有价值。它的核心价值是“隔离”，不只是“创建分支”。

什么时候不该用 using-git-worktrees？

以下情况不建议使用：

• 你只是在当前分支上做一个很小的修改
• 团队禁止使用未受管控的 worktree 位置
• 你们已经有一套确定性的内部工具来处理目录和 ignore 规则
• 仓库存在这个技能不了解的特殊 Git 约束

它能替代 Git 知识吗？

不能。using-git-worktrees skill 能提升调用方式和初始化纪律，但在分支命名、rebase、清理、合并策略这些事情上，你仍然需要基本的 Git 判断力。

如何改进 using-git-worktrees 技能的使用效果

明确给出分支和目录意图

提升效果最明显的做法，是同时告诉代理目标分支和期望的目录策略。例如：

“Use using-git-worktrees for branch fix/cache-invalidation. If .worktrees/ exists and is ignored, use it; otherwise ask before using a global location.”

这样能消除最常见的歧义来源。

在 CLAUDE.md 中写清楚偏好

因为这个技能会检查 CLAUDE.md，所以你可以提前把这些信息写进去，改善后续结果：

• 首选的 worktree 目录
• 是否允许项目内 worktree
• 分支或文件夹的命名规范

这样一来，原本每次都要由用户重复说明的内容，就会变成仓库级策略。

提前配置本地目录的 ignore 规则

如果你的团队希望把 .worktrees/ 或 worktrees/ 放在项目内，最好提前加好 ignore 规则。这样 using-git-worktrees for Git Workflows 这条路径会顺畅很多，因为安全校验可以直接通过，而不会在任务进行到一半时被迫停下来讨论。

留意常见失败模式

主要失败模式其实很可预测：

• 代理把 worktree 建到了未批准的位置
• 本地 worktree 文件夹没有被忽略
• 因为需求描述太含糊，分支名被错误推断
• 在隔离完成之前，就已经在原 checkout 里开始实现

这些问题大多来自提示词信息不完整，而不是技能本身出错。

开始编码前先要求确认

一个简单但有效的改进提示词是：

• “Use using-git-worktrees, then report the final path and branch before making edits.”

这样可以更早发现问题，尤其适用于目录层级很多、嵌套复杂或策略比较特殊的仓库。

第一次跑完后继续迭代

如果第一次输出基本可用，但还不够理想，建议优化使用模式，而不是推倒重来：

• 固定你偏好的目录位置
• 在 CLAUDE.md 里补充说明
• 在提示词里统一分支命名方式
• 明确要求修改前先确认

这样能让 using-git-worktrees usage 随时间变得更可预测，也能减少重复的初始化摩擦。