finding-skill-opportunities

スキルの機会を見つける

概要

スキルの機会とは、判断を伴う、繰り返し行われる複数ステップの手順で、手作業で何度も実行されるものです。どこにそのような手順があるのかを示す、独立した2種類の証拠があります。

• リポジトリ — Git の履歴と既存の自動化です。繰り返されるコミットの種類、いつも一緒に変更されるファイル、リリースや移行に関するキーワード、途中までしか書かれていない Makefile のターゲット、運用手順書などです。
• セッション — ローカルにある Claude Code のトランスクリプトです。実際に依頼された内容、実行したツールの一連の操作、触れたファイルが分かります。

それぞれ見落とすものが異なるため、デフォルトでは両方を使います。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 を vault やワークスペースのルートから実行することはよくあります。サマリーでは一致を（matched by cwd と by files edited に）分けて示すため、どちらに該当したかを確認できます。リポジトリへの所属を完全に無視するには、--scope all を使用してください。

   このユーザーのマシンでは Python を uv run 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 の既存のスキルに関するセクションを必ず読んでください。
• 1つのシグナルだけを信頼する。 複数の情報源による裏付けがあってこそ、確信を持てます。
• 限られた期間の情報を全体像として報告する。 セッション分析の対象はこのマシンのトランスクリプトのみで、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-gram、変更頻度の高いファイル、一緒に編集されたファイルの組み合わせ、使用されたスキル、摩擦）。--repo、--days、--since、--top、--scope、--transcripts-dir、--no-examples を指定できます。詳細は --help を実行してください。

3つのスクリプトはいずれも、デフォルトで現在のディレクトリを対象とし、ソート済みの出力を生成します。現在時刻のタイムスタンプは含まれないため、期間と入力が同じであれば、再実行後もバイト単位で同一の出力になります。

スクリプトをここで実行できない場合（bash がない、Python がない、トランスクリプトのディレクトリがない、または OS が異なる場合）：タスクを放棄せず、実行できる情報源を分析し、スキップした情報源とその理由を説明して、この環境のツールで可能な限り再現してください。