finding-skill-opportunities

寻找技能机会

概述

技能机会是指一种反复出现、涉及多个步骤且需要判断的流程，并且人们不断手动重复执行。两类相互独立的证据可以揭示这些流程所在之处：

• 代码仓库——Git 历史记录和现有自动化。反复出现的提交类型、总是一起变更的文件、发布／迁移关键词、未完成的 Makefile 目标和操作手册文档。
• 会话——本地 Claude Code 记录。人们实际提出的需求、运行的工具序列，以及他们处理过的文件。

这两类证据各有盲区，因此默认同时使用。Git 只能看到最终提交的工作，所以如果某个流程每周都在一个无人提交代码的代码仓库里手动执行，Git 就无法发现它。会话能看到需求，却看不到长期趋势，而且只能覆盖这台机器上的记录。

此技能会通过内置脚本，以确定性的方式扫描两类证据，因此你不必逐一检查数千条提交或会话，然后运用判断力，将原始信号整理成按优先级排列且有证据支撑的技能候选项。

**核心原则：**让脚本找出重复性；由你决定哪些重复流程值得做成技能。

适用场景

• “我们应该为这个代码仓库编写哪些技能？”
• 审查代码库，找出可自动化或值得编写成技能的工作流
• 开始接触陌生代码仓库时，了解其中反复执行的流程
• 编写技能之前，依据真实证据而非猜测来确定方向

**不适用：**编写技能本身（选定候选项后，请使用 superpowers:writing-skills），或没有重复性的单次任务。

输入

输入	默认值	设置方式
代码仓库	当前目录	每个脚本都使用 --repo <path>
回溯天数	30	两个挖掘脚本都使用 --days N。更长的时间窗口能发现较慢的流程（如季度发布）；更短的窗口能反映团队当前的工作。
来源	两者	git = 仅代码仓库证据；sessions = 仅会话记录；both = 执行全部扫描并交叉验证
每个部分的行数	20	--top N

从用户的请求中获取这些信息；不要追问默认值。仅当代码仓库的历史记录无关或不存在时，才选择 sessions；当无法获取会话记录时（例如在别人的机器上，或刚克隆的代码仓库），选择 git。始终在报告中说明所用的时间窗口和来源——若不知道检查了什么，候选项列表就意义不大。

工作流

所有脚本均为只读且结果确定。根据所选来源运行相应脚本，然后综合分析。下方脚本路径相对于此技能自身目录。请从该基准目录运行脚本，而不是从正在扫描的仓库运行。

1. 挖掘 git 历史（来源为 git 或 both）：

   bash scripts/git-signals.sh --repo <path> --days 30 --top 20
   # or an absolute cutoff / free-form date: --since "1 year ago"
   

2. 盘点现有工作流的编码形式（来源为 git 或 both；最容易着手的内容——这些步骤已经存在）：

   bash scripts/scan-workflows.sh --repo <path>
   

3. 挖掘会话记录（来源为 sessions 或 both）：

   uv run python scripts/session-signals.py --repo <path> --days 30 --top 20
   # widen beyond this repo's sessions: --scope all
   

   读取 ~/.claude/projects/*/*.jsonl。如果会话的工作目录是该仓库，或者会话编辑过仓库中的文件，就算该会话与仓库有关——人们经常在保管库或工作区根目录中启动 Claude，却在处理另一个仓库；摘要会区分匹配方式（matched by cwd 与 by files edited），以便查看是哪种情况。使用 --scope all 可完全忽略仓库归属。

   在此用户的机器上，通过 uv run python 调用 Python（裸 python 会命中 Windows Store 占位程序）；该脚本只使用标准库，因此在其他任何地方都可运行 python3 …。

   **隐私：**会话记录包含用户自己的提示词，也可能引用客户资料。脚本只会读取记录，但其输出可能包含提示词片段——如果报告将要共享或提交，请使用 --no-examples。

4. 交叉引用并综合分析。 如果某个信号出现在多个输出中，就说明信号较强——提交说明中的发布关键词、package.json 中的 release 脚本，以及 CHANGELOG 的共同变更簇，都描述了同一套发布流程。会话中的热门文件使用相对于仓库的路径，因此可直接与 git 热门文件列表对应。

   分歧本身也是一项发现：在会话中占比高、却未出现在 git 中的内容，说明工作从未进入提交（通常最值得整理成技能）；在 git 中占比高、却未出现在会话中的内容，可能已自动化，或是在 Claude 之外完成的。

5. 根据下方标准对候选项排序并撰写报告（参见“输出”）。

6. 将每个选定的候选项交给 superpowers:writing-skills，以编写实际的 SKILL.md。此技能负责发现机会，而不是编写技能。

信号解读

每个排序后的部分都代表特定含义，并且不同来源的含义各不相同。查看输出后，阅读一次 references/signal-interpretation.md——该文件会将每个脚本的各个部分对应到其暗示的机会类型，并指出哪些部分仅反映数量，哪些会直接列出候选项。

什么是好的技能候选项

根据以下标准为每个候选项排序。优秀的候选项大多符合这些标准：

• 反复出现——重复发生（信号可以证明这一点），而非只发生一次。
• 多步骤——步骤足够多，顺序和完整性很重要。
• 容易出错或遗忘——共同变更对以及“别忘了还要……”这类惯例很有价值。
• 需要判断——如果某个流程完全机械化，且已有脚本能端到端完成，则可能不需要技能（应改为指向该脚本）。
• 可复用／可泛化——适用于整个项目，而非单个修复。
• 尚未成为技能——先检查现有技能部分。

剔除以下候选项：一次性事项、已完全自动化且无需判断的事项，或最好留在 CLAUDE.md 中的纯项目知识。

输出

生成一份按强度从高到低排序的报告。每个候选项应包含：

### <candidate skill name (verb-first, e.g. "cutting-a-release")>
Evidence:   <which signals, with counts, each tagged by source — e.g.
            "git: 52 'release' subjects, CHANGELOG.md+package.json co-change x62;
            sessions: 9 'release ...' request clusters, Bash->gh->Bash x14">
Procedure:  <the repeated steps, as far as the evidence reveals them>
Why a skill: <which criteria it hits>
Next step:  hand to superpowers:writing-skills

报告开头注明范围行：挖掘的来源、回溯时间范围和分析量（提交和／或会话数量）。

最后简要列出已考虑但未采纳的信号，以便审计（例如：“锁文件频繁变更——属于机械操作，无需技能”）。

常见错误

• 为完全机械化的任务推荐技能。 如果脚本无需做出任何决策就能完成任务，请推荐脚本，而不是技能。
• 忽略共同变更对。 这是信号最强的部分——它们揭示了人们容易忘记的步骤。
• 重复现有技能。 务必先阅读 scan-workflows.sh 的现有技能部分。
• 只相信一个信号。 只有多个来源相互印证，才能建立信心。
• 把狭窄时间窗口的结果说成全貌。 会话仅涵盖这台机器上的记录，Git 仅涵盖已提交的工作；应明确说明这两项限制，而不要暗示覆盖全面。
• 泄露提示词片段。 任何要离开这台机器的报告都应使用 --no-examples。
• 在此处编写技能。 此技能仅负责输出排序后的候选列表；编写工作由 superpowers:writing-skills 负责。

脚本

• scripts/git-signals.sh — 确定性分析 Git 历史（前缀、关键词、热点文件、共同变更对、繁忙目录）。参数：--repo、--days、--since、--top。运行 --help 查看详情。
• scripts/scan-workflows.sh — 清点 Makefile、package.json 脚本、任务运行器、CI、scripts/、运行手册文档和现有技能。参数：--repo。运行 --help 查看详情。
• scripts/session-signals.py — 确定性分析会话记录（漏斗、请求聚类、关键词、工具序列 n 元语法、热点文件、共同编辑对、使用过的技能、阻碍因素）。参数：--repo、--days、--since、--top、--scope、--transcripts-dir、--no-examples。运行 --help 查看详情。

这三个脚本默认使用当前目录，并输出排序后的结果，不包含实时时间戳。因此，在相同时间窗口且输入未变的情况下重复运行，输出将逐字节一致。

如果脚本无法在此处运行（缺少 bash、没有 Python、没有记录目录或使用了不同的操作系统）：不要放弃任务——运行可用的数据源，说明跳过了哪个数据源及其原因，并尽可能使用此环境中的工具还原结果。