finding-skill-opportunities

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Finding Skill Opportunities

寻找Skill开发机会

Overview

概述

A skill opportunity is a recurring, multi-step procedure that involves judgment and keeps getting repeated by hand. Git history and a codebase's existing automation are the evidence: the procedures a team performs over and over leave fingerprints — repeated commit types, files that always change together, release/migration keywords, half-written Makefile targets and runbook docs.

This skill scans those fingerprints deterministically (via the bundled scripts) so you don't eyeball thousands of commits, then applies judgment to turn the raw signals into a ranked list of skill candidates with evidence.

Core principle: Let the scripts find the repetition; you decide which repetitions are worth a skill.

Skill开发机会指的是需要判断力、且被反复手动执行的重复性多步骤流程。Git历史记录和代码库中的现有自动化流程是判断依据：团队反复执行的流程会留下痕迹——重复的提交类型、总是一起变更的文件、发布/迁移相关关键词、未完成的Makefile目标以及运行手册文档。

本工具会通过内置脚本确定性地扫描这些痕迹，让你无需手动查看数千条提交记录，之后再通过人工判断将原始信号转化为带有依据的Skill候选列表并排序。

核心原则： 让脚本找出重复模式；由你决定哪些重复流程值得做成Skill。

When to Use

使用场景

"What skills should we write for this repo?"
Auditing a codebase for automatable or skill-worthy workflows
Onboarding to an unfamiliar repo and wanting to know its recurring rituals
Before writing skills, to ground them in real evidence instead of guesses

Not for: writing the skill itself (use

superpowers:writing-skills

once you've picked a candidate) or one-off tasks with no repetition.

"我们应该为这个仓库编写哪些Skill？"
审计代码库中可自动化或适合做成Skill的工作流
接手不熟悉的仓库，想要了解其重复执行的常规流程
在编写Skill之前，基于真实依据而非猜测来确定方向

不适用场景： 编写Skill本身（选定候选后使用

superpowers:writing-skills

），或无重复性的一次性任务。

Workflow

工作流程

Run the two scripts, then synthesize. Both are read-only and deterministic.

Mine git history for repetition signals:

bash

bash "${CLAUDE_SKILL_DIR}/scripts/git-signals.sh" --repo <path> --top 20
# optionally scope recent work: --since "1 year ago"

Inventory existing workflow encodings (these are the lowest-hanging fruit — the steps already exist):
bash
```
bash "${CLAUDE_SKILL_DIR}/scripts/scan-workflows.sh" --repo <path>
```
Cross-reference and synthesize. A signal is strong when it shows up in both outputs — e.g. release keywords in commit subjects AND a
```
release
```
package.json script AND a
```
CHANGELOG
```
/manifest co-change cluster all describe one release procedure.
Rank candidates against the criteria below and write the report (see Output).
Hand each chosen candidate to
superpowers:writing-skills
to author the actual SKILL.md. This skill finds opportunities; it does not write the skills.

运行两个脚本，然后综合分析。两个脚本均为只读且具有确定性。

挖掘Git历史记录以获取重复信号：

bash

bash "${CLAUDE_SKILL_DIR}/scripts/git-signals.sh" --repo <path> --top 20
# 可选择性限定近期工作：--since "1 year ago"

盘点现有工作流编码（这些是最容易实现的目标——步骤已存在）：
bash
```
bash "${CLAUDE_SKILL_DIR}/scripts/scan-workflows.sh" --repo <path>
```
交叉参考并综合分析。当一个信号同时出现在两个输出结果中时，其可信度更高——例如，提交主题中的发布关键词、package.json中的
```
release
```
脚本、以及CHANGELOG/清单文件的协同变更集群，都指向同一个发布流程。
根据以下标准对候选进行排序并撰写报告（见输出部分）。
**将选定的每个候选交给
```
superpowers:writing-skills
```
**以编写实际的SKILL.md。本工具仅负责寻找机会，不负责编写Skill。

Signal Interpretation

信号解读

What each script section tends to mean:

Signal (from `git-signals.sh` )	Likely skill opportunity
High-frequency commit prefix (e.g. many `chore:` , `release:` )	A routine procedure tied to that type
Recurring keywords (release, deploy, migrate, bump, regenerate, rotate, seed, backfill)	The named chore is done repeatedly by hand
Hot files (changed in many commits)	A repeated editing ritual centered on that file
Co-changed pairs (files that move together)	A "change A, remember to also change B" procedure — high-value, easy to forget steps
Busiest directories	Where the team's repeated work concentrates

Signal (from `scan-workflows.sh` )	Likely skill opportunity
Makefile targets / package.json scripts / task-runner recipes	Commands a skill can wrap with context and judgment
CI workflow jobs	Procedures currently only encoded for machines — a human/agent equivalent may be missing
`scripts/` and `bin/` entries	Existing automation that a skill can orchestrate
"How to" / runbook doc sections	Procedural knowledge already written in prose, ready to become a skill
Existing skills	Do NOT propose these — gaps, not duplicates, are the goal

各脚本部分的含义：

信号（来自 `git-signals.sh` ）	对应的Skill开发机会
高频提交前缀（例如大量 `chore:` 、 `release:` ）	与该类型相关的常规流程
重复关键词（release、deploy、migrate、bump、regenerate、rotate、seed、backfill）	命名的日常任务被反复手动执行
高频变更文件（在多次提交中被修改）	围绕该文件的重复编辑流程
协同变更文件对（总是一起变更的文件）	"修改A时，记得也要修改B"的流程——这类步骤价值高且容易被遗忘
最繁忙的目录	团队重复工作的集中区域

信号（来自 `scan-workflows.sh` ）	对应的Skill开发机会
Makefile目标 / package.json脚本 / 任务运行器配方	Skill可封装带有上下文和判断逻辑的命令
CI工作流任务	当前仅为机器编码的流程——可能缺少适合人类/Agent的等效流程
`scripts/` 和 `bin/` 目录下的脚本	Skill可编排的现有自动化流程
"操作指南" / 运行手册文档章节	已以书面形式存在的流程知识，可直接转化为Skill
现有Skill	请勿重复提议——目标是填补空白，而非重复建设

What Makes a Good Skill Candidate

优质Skill候选的评判标准

Rank each candidate by these. A strong candidate hits most of them:

Recurring — happens repeatedly (the signals prove this), not once.
Multi-step — enough steps that order and completeness matter.
Error-prone / forgettable — co-change pairs and "don't forget to also…" rituals are gold.
Involves judgment — if it's purely mechanical and a script already does it end-to-end, it may not need a skill (point to the script instead).
Reusable / generalizable — applies across the project, not a single fix.
Not already a skill — check the existing-skills section first.

Drop candidates that are: one-offs, already fully automated with no judgment, or purely project-trivia better left in a CLAUDE.md.

根据以下标准对每个候选进行排序。优质候选通常符合大部分标准：

重复性——反复发生（信号可证明），而非一次性事件。
多步骤——步骤足够多，顺序和完整性很重要。
易出错/易遗忘——协同变更文件对以及"别忘了还要……"的流程是绝佳候选。
需要判断力——如果是纯机械性操作且已有脚本端到端完成，则可能不需要Skill（直接推荐脚本即可）。
可复用/可推广——适用于整个项目，而非单一修复。
尚未成为Skill——先查看现有Skill部分。

剔除以下候选：一次性任务、已完全自动化且无需判断的任务、或更适合放在CLAUDE.md中的纯项目琐事。

Output

输出结果

Produce a ranked report, strongest first. For each candidate:

undefined

生成一份按优先级排序的报告，优先级最高的候选排在最前面。每个候选的格式如下：

undefined

<candidate skill name (verb-first, e.g. "cutting-a-release")>

<候选Skill名称（动词开头，例如"cutting-a-release")>

Evidence: <which signals, with counts — e.g. "52 'release' subjects; CHANGELOG.md+package.json co-change x62; package.json

release

script"> 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


End with a short list of signals you considered and **rejected**, so the audit is auditable (e.g. "lockfile churn — mechanical, no skill needed").

依据： <相关信号及数量——例如"52条含'release'的提交主题；CHANGELOG.md与package.json协同变更62次；package.json中的

release

脚本"> 流程： <根据依据还原的重复步骤> 为何适合做成Skill： <符合哪些评判标准> 下一步：交给superpowers:writing-skills处理


报告末尾列出你考虑过但**拒绝**的信号，以便审计可追溯（例如"锁文件变更——纯机械操作，无需Skill"）。

Common Mistakes

常见错误

Proposing skills for fully-mechanical tasks. If a script already does it with no decisions, recommend the script, not a skill.
Ignoring co-change pairs. They're the highest-signal section — they reveal the steps humans forget.
Duplicating existing skills. Always read the existing-skills section of
```
scan-workflows.sh
```
first.
Trusting one signal. Confidence comes from corroboration across both scripts.
Writing the skill here. This skill stops at a ranked candidate list; authoring is
```
superpowers:writing-skills
```
.

为纯机械性任务提议Skill。如果已有脚本可完成且无需决策，推荐使用脚本而非Skill。
忽略协同变更文件对。这是信号最强的部分——它们揭示了人类容易遗忘的步骤。
重复现有Skill。务必先阅读
```
scan-workflows.sh
```
输出中的现有Skill部分。
仅依赖单一信号。可信度来自两个脚本输出的相互印证。
在此处编写Skill。本工具的任务止于生成排序后的候选列表；Skill编写由
```
superpowers:writing-skills
```
负责。

Scripts

脚本说明

```
scripts/git-signals.sh
```
— deterministic git-history analysis (prefixes, keywords, hot files, co-change pairs, busy dirs).
```
--repo
```
,
```
--since
```
,
```
--top
```
. Run
```
--help
```
for details.
```
scripts/scan-workflows.sh
```
— inventories Makefiles, package.json scripts, task runners, CI,
```
scripts/
```
, runbook docs, and existing skills.
```
--repo
```
. Run
```
--help
```
for details.

Both default to the current directory and emit sorted, timestamp-free output, so reruns on unchanged history are byte-identical.

If a script can't run here (missing

bash

/a tool, or a different OS): don't abandon the task — the scripts only automate ordinary git/text commands, so reproduce the same steps directly with whatever tools this environment has.

```
scripts/git-signals.sh
```
——确定性Git历史分析（前缀、关键词、高频变更文件、协同变更文件对、繁忙目录）。支持
```
--repo
```
、
```
--since
```
、
```
--top
```
参数。运行
```
--help
```
查看详细说明。
```
scripts/scan-workflows.sh
```
——盘点Makefile、package.json脚本、任务运行器、CI流程、
```
scripts/
```
目录、运行手册文档以及现有Skill。支持
```
--repo
```
参数。运行
```
--help
```
查看详细说明。

两个脚本默认使用当前目录，并输出排序后的无时间戳结果，因此在历史记录未变更时，重复运行的输出完全一致。

如果脚本无法在此环境运行（缺少

bash

或相关工具，或操作系统不同）：不要放弃任务——脚本只是自动化了常规的Git/文本命令，因此可以使用该环境中的任何工具直接执行相同步骤。