このリポジトリの各スキルは gh skill install コマンドでインストールする前提です。
基本的にスキルはプロジェクト単位で管理することが推奨されます。
グローバルに置くと次のような問題があります。
- そのリポジトリで利用しているスキルおよびそのバージョンが暗黙的になる
- スキルの有無はエージェントの動きを大きく変えてしまいます
- エージェントによる開発を中心に据えると、これは致命的です
- スキルを利用しないエージェントのコンテキストウィンドウを圧迫する
- スキルが誤発火しないことは重要だが、コンテキストウィンドウはモデルがどれだけ発展しても貴重です
- スキルの description を短く保つ努力をしているにもかかわらず、不要なスキルを読む余裕はありません
よってグローバルに配置することを容認できるのは、この中だと git-init, gh-init 程度です。 それ以外はプロジェクト単位でインストールするべきです。
プロジェクトを一から立ち上げるスキル。
git-init → gh-init でリポジトリを整え、gh skill install でプロジェクトの baseline スキル（git-commit / okf-knowledge / technical-writing-ja / concurrent-dev は常時、他の git-* はユーザー選択、gh-* はリモート作成時のみ全導入）を入れる。いずれのツール・スキルも無ければスキップする。最後に README.md（概要と docs/ へのリンク集）・AGENTS.md（概要とドキュメント管理規則、docs/・knowledge/ へのリンク）を軽量に作成し、git-commit でコミットして終了する。
現在のブランチから GitHub の Pull Request を作成するスキル。 差分の全体を読んでタイトルと本文を合成し、リポジトリに PR テンプレートがあればそれに従う。push はまず一度試し、失敗すればユーザーに依頼する。作成前に内容を確認する。GitHub の PR 専用。
既存の GitHub Pull Request の title・description・labels を最新の差分に合わせて更新するスキル。 レビュー指摘の反映・追加の指示・その他 PR の修正でコードを変えたときに、古い本文へ追記するのではなく現在の差分全体から再合成して、説明が実体とずれないようにする。更新前に変更内容を確認する。GitHub の PR 専用。
雑な記述から GitHub の Issue を起票するスキル。 やりたいことを構造化された本文に合成し、リポジトリに ISSUE_TEMPLATE があればそれに従い、なければ概要・目的・制約・受け入れ条件のテンプレートを使う。作成前に内容を確認する。GitHub 専用。
GitHub の Pull Request に対してコードレビューを行うスキル。 変更を確認し、該当する行に severity タグ付きのインラインコメントを投稿する。GitHub の PR 専用。
自分の PR に付いたレビュー指摘に対応するスキル。 各指摘を「対応する・押し返す・質問で返す・対応不要と説明する」の 4 つに分類し、分類表と返信文をユーザーに確認してから、修正・返信・スレッドの resolve までを行う。設計意図と衝突する指摘に盲従しないことが核。resolve は修正して push した指摘に限り、押し返しは 1 往復まで。対応後の本文更新は gh-pr-update に委譲する。GitHub の PR 専用。
GitHub の Pull Request をマージするスキル。 主に squash merge を対象とし、差分の全体を読んで短く適切な squash commit メッセージを合成し、実行前に内容を確認する。GitHub の PR 専用。
最後のリリース以降の差分を読み、新しいセマンティックバージョンを切るスキル。 トークンを食う差分の読解は Haiku の Subagent に委譲し、オーケストレーターがログと報告を突き合わせて bump 種別（major/minor/patch）を判断して次バージョンを算出する。リリースノートを合成して注釈付きタグを作成、任意で GitHub Release も作る。0.x の特例（破壊的変更でも minor）に対応し、push はまず一度試し、失敗すればユーザーに依頼する。作成前に内容を確認する。
ローカルの git リポジトリに対して GitHub 上のリモートリポジトリを作成するスキル。
gh（なければ GitHub MCP）でリポジトリを作成して origin として登録する。push はまず一度試し、失敗すればユーザーに依頼する。
git のコミットを行うスキル。 変更内容を確認し、単一行のコミットメッセージでコミットする。
複数の開発タスクを並列に進めるスキル。
オーケストレーター（Fable 5 / Opus 級）が依存関係・優先順位・競合を判断して実行計画を立て、プロジェクトルート下 .wt/ の worktree を準備し、開発作業だけを想定難易度に応じた Haiku / Sonnet / Opus の Subagent に委譲してコストを削減する。レビュー・マージ・後片付けはオーケストレーター自身が行い、一貫性を保つ。依存で一本鎖になるタスクは無理に並列化せず直列で進める。
git リポジトリを初期化するスキル。
git init を実行し、git プロファイル（ユーザー名・メールアドレス）を切り替えて、空の初期コミットを作成する。
Kent Beck の "Canon TDD" の定義に基づいてテスト駆動開発を進めるスキル。 テストリスト → Red → Green → Optionally Refactor のサイクルを1テストずつ回し、インターフェイス設計と実装設計を分けて「動かす」と「きれいにする」を同時にやらない規律を提供する。各ステップで陥りがちな間違いも示す。
作業で得た知見を Open Knowledge Format (OKF) の knowledge bundle として残すスキル。
「知見を貯めて」「知見をまとめて」をトリガーに、再利用価値のある知見を抽出して knowledge/（既定はプロジェクトルート直下）に OKF 準拠の concept ファイルとして書き出す。index.md は常に維持し、log.md は git 管理下なら作らず・非管理ならユーザーに確認（既存なら維持）、AGENTS.md と CLAUDE.md は両方確認し、存在する方（両方あれば AGENTS.md を優先）に bundle へのポインタが無ければ追記を確認する。書式の機械的な踏襲より「何をどの粒度で concept にするか」の判断に重きを置く。
日本語の技術文書を書く・直すときの文章規範を提供するスキル。 整形・段落と論証の構成・論証の厳密さ・読み手の負荷管理・演出の抑制・LLM っぽい表現の禁止・冗長の排除といった規範を、出典の gist に基づいてまとめている。
playwright-cli で認証をユーザーに行わせるスキル。 認証時だけ playwright-cli を headful で表示し、ユーザーにログイン操作を行わせた後、headless モードに戻って操作を続行する。
quiver 上で可換図式を作成して、そのリンクを作るスキル。
ブラウザ操作の裏で流れる通信を解析し、その操作を再現するワンショットスクリプト（既定は curl、指示があれば TypeScript / Python）を合成するスキル。
まず playwright-cli 単体で通信を捕捉し、request／response-body を材料に「どのリクエスト群がその操作か」を選んでノイズを削り秘密情報をパラメータ化し、リプレイで再現を検証する（捕捉のダンプではなく合成が核）。自動化検知・captcha・ログインで阻まれたら、システムの Chrome を明示プロファイル + CDP ポート + netlog で起動して attach --cdp でアタッチし、検知回避とユーザー支援を得つつセッション全体を netlog に記録する。ブラウザの HTTP(S) 通信専用。
雑なバグ報告を、報告された症状を実際に再現する最小で決定的な失敗テストに変換するスキル。 核は 2 つの規律 ── 再現できたら削れるだけ削る「最小化」と、再現できなかったときにでっち上げず試した条件を列挙して報告する「正直さ」。失敗しただけでは再現と呼ばず、失敗の内容が症状と一致することを確認する。成果物は「単一コマンド・終了コード 0/非 0 で合否」の契約に整え、git-bisect-run の述語や tdd の Red 入口にそのまま渡せる形で引き渡す。修正はしない。
回帰バグの原因コミットを git bisect で特定するスキル。
核は git bisect run に渡す述語スクリプト（ビルド失敗は 125 で skip、症状の有無を 0/非 0 に変換）の合成で、各ステップをエージェントが手で試すことを禁じ、反復は bisect に委ねる。再現手段が無ければ先に bug-repro を回し、その成果物を述語に包む。本走前に bad/good 両端で述語を校正し、名指しされたコミットは差分で症状を説明できるか検証してから報告する。専用 worktree（.wt/bisect）で回し、修正はしない。
依存パッケージを、changelog を読んで影響を判断しながら安全に更新するスキル。 核はバッチ戦略（patch/minor は一括、major は単独、lockfile のみは独立、security advisory は優先、pin はユーザー確認）と、changelog から自プロジェクトへの影響を読む判断。トークンを食う changelog の読解は Haiku の Subagent に委譲して事実抽出だけをさせる。1 バッチ = 1 コミットで、テストが無い場合は「未検証」と正直に報告する。push・PR 作成はしない。
「なぜこのコードはこうなっているのか」に答えるスキル。 blame → コミット → PR → Issue とリンクをたどり（原則 3 ホップまで）、事実の時系列ダンプではなく「設計判断の理由」と「いま変更してよいかの判断材料」に合成して報告する。表層コミット（一括フォーマット等）は blame を掘り直し、トレイルが冷えたら正直に打ち切って事実と推測を区別する。読み取り専用。得られた知見は okf-knowledge での保存を提案する。
コード変更後に README・ドキュメントが実体とずれていないか検査し、ずれた箇所だけを現在のコードから合成し直すスキル。 核は「何を直すか」より「何を直さないか」── 文体・構成・意図的に未来を書いた節には触れず、事実として実体とずれた箇所のみを、追記ではなく再合成で直す。「ドキュメントが古い」のか「コードがバグっている」のかを勝手に裁定せず、ずれとして提示してユーザーの判断を仰ぐ。
数十〜数百ファイルにまたがる機械的な変更（API 移行、非推奨パターンの一掃、ライブラリ差し替え等）を三層に分担して一掃するスキル。 核は自動化境界の三分割 ── 構文的に一意な置換はスクリプト（LLM 不使用）、文脈依存の微調整はオーケストレーター自身が作った模範変換の diff を few-shot にした Haiku のシャード、パターンの例外は残渣としてオーケストレーター（または Sonnet）が処理する。シャードはファイル単位で互いに素に切り、worktree を作らずメインの checkout 内で並列化する。「合わないものは触らず報告」を Haiku に課し、例外を弱いモデルに処理させない。層・波ごとにコミットして bisect 可能に保つ。
コンパイラ・リンタ・型チェッカの設定を今より厳しくし、噴出する診断を計画的に焼き払って二度と緩めない（ラチェット）スキル。 核はトリアージ（診断コード × 修正パターンのバケット分け）と fix / suppress / 報告の三方向判断。機械的な修正は Haiku、意味論的な修正は Sonnet に委譲し、strict 化が炙り出した本物のバグは勝手に直さずユーザーに報告する。suppress は行単位 + 理由必須の最後の手段で、ルール・ファイル全体の無効化はしない。サブフラグ単位で段階的に有効化し、1 バケット = 1 コミット、修正が先・設定が最後の順で履歴を green に保つ。
既存コードのテストスイートを、リスクの高い場所から順に、質を守りながら増強するスキル。 核はリスクによる標的選定（カバレッジ % を目標にしない）と change-detector テストの排除。期待される振る舞いの仕様はオーケストレーターが書き、テストコード化だけを Subagent に委譲する（並列実行の下回りは concurrent-dev に乗せる）。品質ゲートでは assertion の無いテスト・mock-echo・スナップショットの丸呑みを弾き、意図的なバグを仕込む mutation スポットチェックで「落ちるべきときに落ちるか」を確かめる。現行コードで落ちるテストは曲げず、バグ候補として報告する。
実装タスクの実現可能性が不透明なとき、使い捨てのプロトタイプで不透明さを潰し、知見を技術文書として回収するスキル。
核は 2 つの規律 ── 実現可能性が不透明な最小の部分だけを突く（1 スパイク 1 問い）ことと、知見をコンテキストではなく単体で完結する文書（docs/spikes/）に回収すること。調査するエージェントと実装するエージェントは別（オーケストレーターが調査を Opus・実装を Sonnet の Subagent に振る）前提で、作業ツリーの本番コードは改変せず .spike/ にのみ書く。検証が in-place 改変を要する場合だけ使い捨て worktree（.wt/spike-<slug>）に隔離し回収後に破棄する。文書は問い → 結論（＋推奨）→ 詳細 → Why not（採らない道）→ 落とし穴（採る道の罠）の体裁で、実装そのものはせず引き継ぐ。
push 時に GitHub Actions（.github/workflows/validate-skills.yml）が各 skills/*/SKILL.md を検証する。
- 妥当性チェック（エラー、CI を失敗させる）:
skills-refreference library による Agent Skills 仕様準拠チェック（必須フィールド・文字数上限・命名規則・ディレクトリ名との一致など）。 - ベストプラクティスチェック（警告、CI は失敗させない）:
name+descriptionの推定トークン数が、常時ロードされる Level 1 メタデータの目安である 100 トークンを超えていないか。
ローカルで同じチェックを実行するには(uv を使う。skills-ref は実行時に自動でインストールされる):
uv run scripts/validate_skills.py特定のスキルだけ検証する場合はパスを渡す（--strict を付けると警告もエラー扱いになる）:
uv run scripts/validate_skills.py skills/gh-pr-create --strict