Skill authoring

スキル執筆(メタスキル)

目的

このリポジトリのSKILL.mdを高品質に新規作成・改善し、「意図した場面で確実に発動し、新しいエージェントが読んでも同じ品質で実行できる」スキルを届ける。

使うタイミング

• 新しいSKILL.mdを書くとき
• 既存スキルのdescriptionや本文を改善するとき
• スキルが意図した場面で発動しないと気づいたとき
• scripts/validate-skills.sh がエラーを出したとき
• スキルのメンテナンス(陳腐化チェック・統合・削除)を行うとき

良いスキルの条件

1. descriptionだけで発動判断できる: Claudeはdescriptionのみを読んでスキルを使うか決める。「何のスキルか」+「いつ使うか(〜のときに使う)」を1〜2文で記す
2. 1スキル1トピック: 「開発全般」のような広すぎるスキルは発動判断も本文も曖昧になる。テーマが2つ以上なら分割する
3. 実行可能な手順: 抽象論・精神論を排除し、番号付きステップ・テンプレート・チェックリストで記述する
4. 曖昧語ゼロ: 「適切に」「いい感じに」「丁寧に」を使わない。判断基準・数値・具体例に置き換える
5. 100〜200行以内: 読み込まれるとコンテキストを消費する。長い参考資料は別ファイルに分離してスキルから参照する(progressive disclosure)
6. 再現性: 新しいエージェントが読んでも同じ品質で実行できることが目標

進め方

1. 既存スキルの調査

   • ls skills/ でスキル一覧を確認し、類似スキルが存在しないか確認する
   • 近いスキルがあれば統合か分割を検討する

2. descriptionの草案作成

   • 「何のスキルか」+「いつ使うか」を1〜2文にまとめる
   • 発動トリガーとなるユーザーの言葉・状況を具体的に書き込む
   • 曖昧なdescription例: スキルの書き方に関するスキル
   • 良いdescription例: Claude Code用スキル(SKILL.md)の新規作成・改善を行うメタスキル。「新しいスキルを作りたい」「スキルが発動しない」と言われたときに使う

3. ディレクトリとファイルの作成

   • skills/<name>/ ディレクトリを作成する(nameはディレクトリ名と一致させる)
   • 下記「成果物テンプレート」を雛形にSKILL.mdを書く

4. 本文の執筆

   • 統一セクション構成(後述)を守る
   • 「である」調または体言止め。空セクションや「TBD」を残さない

5. モデル委譲ガイドの記述

   • 冒頭に 共通原則は [[orchestration]] を参照 を記す
   • 司令塔/Opus相当/Sonnet相当/Haiku相当の役割分担表を書く
   • 特定モデル名(OpusやSonnetの固有バージョン名等)を焼き込まない

6. バリデーション

   • bash scripts/validate-skills.sh を実行し、全チェックをパスすることを確認する
   • チェック項目: frontmatter存在・nameとディレクトリ名の一致・必須セクション(## 目的/## モデル委譲ガイド/## 関連スキル)・固有モデル名の不在・[[参照]]先の実在

7. 発動テスト

   • 実際のタスクで(a)意図した場面で発動するか、(b)本文の指示に従った成果物が出るか、を確認する
   • 発動しない場合はdescriptionを修正する

8. READMEへの追記

   • README.md のスキル一覧に追加する(validate-skills.shが確認する)

成果物テンプレート

---
name: <ディレクトリ名と一致させる>
description: <何のスキルか>。<いつ使うか: 「〜のときに使う」形式で発動トリガーを含める>
---

# <スキルの日本語タイトル>

## 目的

<このスキルが解決する問題と、達成したい状態を2〜4文で記述>

## 使うタイミング

- <ユーザーの言葉・状況の具体例>
- <別の発動条件>
- <別の発動条件>

## 良いスキルの条件

<!-- スキル固有の「良い成果物の条件」をここに列挙 -->
- <条件1>
- <条件2>

## 進め方

1. **<ステップ名>**
   - <具体的な手順。「適切に」「いい感じに」は禁止>
   - <判断基準・数値・具体例を入れる>

2. **<ステップ名>**
   - <手順>

<!-- 目安: 4〜8ステップ -->

## 成果物テンプレート

\`\`\`markdown
# <成果物タイトル>

## <セクション>
<内容の書き方を示すコメントまたは例>
\`\`\`

## チェックリスト

- [ ] <完了条件>
- [ ] <完了条件>
- [ ] lint・テストがパスしている(該当する場合)

## アンチパターン

- **<アンチパターン名>**: <なぜ問題か・どうすべきか>
- **<アンチパターン名>**: <説明>

## モデル委譲ガイド

共通原則は [[orchestration]] を参照。

| 役割 | 担当範囲 |
|---|---|
| **司令塔(メインモデル)** | <この作業での司令塔の責務> |
| **Opus相当** | <高難度・深い推論が必要な作業> |
| **Sonnet相当** | <通常の実働タスク> |
| **Haiku相当** | <軽作業・探索・定型処理> |

## 関連スキル

- [[orchestration]] — モデル委譲共通原則
- [[<関連スキル名>]] — <一言説明>

チェックリスト

• name がディレクトリ名と一致している
• description に「何のスキルか」と「いつ使うか」が両方入っている
• description内に発動トリガーとなるユーザーの言葉・状況が具体的に書かれている
• 「適切に」「いい感じに」等の曖昧語がない
• 1スキル1トピックになっている(テーマが広すぎないか確認)
• 100〜200行以内に収まっている
• 統一セクション構成(目的/使うタイミング/進め方/成果物テンプレート/チェックリスト/アンチパターン/モデル委譲ガイド/関連スキル)を満たしている
• モデル委譲ガイドに司令塔/Opus相当/Sonnet相当/Haiku相当の4役割が揃っている
• [[参照]]がすべて実在するスキル名である
• bash scripts/validate-skills.sh がパスしている
• README.md のスキル一覧に追加した

アンチパターン

• なんでも入り巨大スキル: 「開発全般」「プロジェクト全体」のような範囲の広いスキル。発動条件が曖昧になり、本文も薄くなる。テーマを1つに絞るか複数スキルに分割する
• 概要だけのdescription: コードレビューのスキル のように何をするかだけ書いて、いつ使うかが不明。永遠に発動しない。「〜のときに使う」を必ず含める
• 論文調の本文: 背景・経緯・理論を長々と書き、実行可能な手順がない。手順・テンプレート・チェックリストに書き直す
• テンプレートのない精神論: 「丁寧に設計する」「品質を意識する」だけで、成果物の雛形がない。コピペして使えるテンプレートを必ず用意する
• 書きっぱなし放置: 一度も使わずにリポジトリに眠るスキル。使ったあとに不足を反映し、使われないスキルは統合か削除する
• 固有モデル名の焼き込み: claude-opus-4 のようなバージョン付きモデル名を本文に記述する。モデルラインナップは変わるため、役割(司令塔/Opus相当等)で書く

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

このリポジトリ自体が「司令塔が構成指示書を作り、Sonnet相当に執筆を委譲し、司令塔が検品する」方式で運用されている。新規スキル作成時の役割分担の実例でもある。

役割	担当範囲
司令塔(メインモデル)	スキルの必要性判断・テーマ設定・構成指示書の作成・成果物レビュー・バリデーション確認・README更新判断
Opus相当	複雑なスキル設計(依存関係が多い・判断軸が難しい)・既存スキル群の構造的な整合レビュー
Sonnet相当	SKILL.mdの本文執筆・既存スキルの改善・チェックリスト・アンチパターンの補充
Haiku相当	ディレクトリ一覧取得・既存スキルの行数確認・validate-skills.sh 実行・[[参照]]の実在確認

関連スキル

• [[orchestration]] — モデル委譲共通原則。スキル執筆の委譲方針もここに準拠
• [[documentation]] — READMEや設計書の書き方。スキルと通常ドキュメントの書き分け
• [[implementation]] — スキル執筆の委譲例として参考になる構成を持つ
• [[requirements-definition]] — 新スキルの「何を解決するか」の整理に使う観点が共通