writing-skills

スキルの作成

概要

確実に起動し、効率よく読み込まれ、一貫した結果を生み出す、効果的で十分にテストされた Claude Code スキルを作成します。このスキルでは、スキル作成に TDD アプローチを徹底します。まずテスト用プロンプトを定義し、最小限のスキルを作成してから、誤作動や正当化を防ぐよう強化します。

これは厳格なスキルです。 すべての手順に厳密に従う必要があります。近道はできません。

フェーズ 1：テスト用プロンプトを定義する（RED）

［厳格な必須条件］ スキルの内容を書く前に、スキルが起動すべきプロンプトを定義します。

テスト用プロンプトを 3～5 個作成します。

#	テストの種類	目的	例
1	明確な起動条件	明らかに一致すること	"Create a new React component with tests"
2	間接的な起動条件	こちらも一致すること	"I need a reusable button"
3	紛らわしい不一致条件	一致しないこと	"Review this component code"
4	エッジケース	期待される動作を定義すること	"Create a component and write its docs"
5	曖昧な条件	どのスキルを優先するか定義すること	"Set up the frontend"

それぞれに期待される動作を記録します。

Test prompt: "Create a new React component with tests"
Expected: Should trigger component-creation skill
Should NOT trigger: testing-strategy, code-review, writing-skills

停止 — テスト用プロンプトをすべて記録するまで、フェーズ 2 に進んではいけません。

フェーズ 2：最小限の SKILL.md を作成する（GREEN）

フェーズ 1 のすべてのテスト用プロンプトに合格する、最小限のスキル定義を作成します。

必須の構成

すべての SKILL.md には、次の要素をすべて含める必要があります。

要素	必須	目的
フロントマター（name、description）	はい	識別と起動条件の照合
CSO に最適化された description	はい	「Use when...」で始まり、起動条件を列挙すること
概要（2～3 文）	はい	目的と価値
STOP マーカー付きの複数フェーズのプロセス	はい	明確なアクションを伴う番号付きフェーズ
判断テーブル	はい	アプローチを選ぶためのテーブル
アンチパターン／よくある間違いのテーブル	はい	「してはいけないこと」のセクション
正当化を防ぐガード	はい	HARD-GATE または「Do NOT skip」マーカー
統合ポイントのテーブル	はい	スキルが他のスキルとどう連携するか
具体例	はい	自明でない場合のコード／コマンド例
スキル種別の宣言	はい	最後に RIGID または FLEXIBLE

フロントマターのルール

---
name: skill-name          # lowercase with hyphens, unique identifier
description: "Use when [trigger conditions]"  # Max 1024 chars
---

［厳格な必須条件］ description フィールドは必ず「Use when」で始める必要があります。

CSO（Claude Search Optimization）のルール

description フィールドによって、どのタイミングでスキルが選択されるかが決まります。検索クエリのように最適化します。

ルール	説明
「Use when...」で始める	起動条件の形式
能力ではなく具体的な条件を列挙する	何を教えるかではなく、何をきっかけに起動するか
最大 1024 文字	簡潔にする
動作を表す動詞を使う	「creating（作成する）」、「debugging（デバッグする）」、「designing（設計する）」、「reviewing（レビューする）」

適切な例：

description: "Use when creating database migrations, designing table schemas, adding indexes, or optimizing SQL queries"

不適切な例：

description: "A comprehensive guide to database design covering normalization, indexing, query optimization, and migration strategies"

起動条件のパターン

パターン	形式	例
アクションベース	「作成、更新、削除するときに使用」	CRUD 操作
問題ベース	「デバッグ、修正、解決するときに使用」	バグ修正
成果物ベース	「Docker ファイル、CI 設定ファイルを扱うときに使用」	ファイルの種類
フェーズベース	「プロジェクトを開始するとき、機能を完成させるときに使用」	ワークフローの段階

停止 — 説明がフェーズ 1 のテスト用プロンプトに一致することを確認してから、次に進みます。

フェーズ 3：スキルを強化する（REFACTOR）

抜け道がないか確認し、塞ぎます。

確認項目	質問	不合格の場合の修正
過剰な起動	一致すべきでないプロンプトにも一致しますか？	description を絞り込む
起動漏れ	有効なプロンプトを取りこぼしますか？	不足している起動条件を追加する
正当化	エージェントが手順を省略する方法を見つけられますか？	「Do NOT skip」の制約を追加する
曖昧さ	指示を複数の方法で解釈できますか？	例を使って具体化する
トークンの肥大化	500 行を超えていますか？	参考資料を別ファイルに移す
ゲートの不足	フェーズ間にチェックポイントがありますか？	STOP マーカーを追加する

トークン効率の目標

スキルの種類	目標行数	方針
はじめて使う方向けのワークフロー	< 100 行	手順を最小限にする
頻繁に読み込まれるスキル	< 200 行	説明文より表を使う
包括的なリファレンススキル	< 400 行	フェーズごとに分割する
許容される最大行数	500 行	余分な内容は別ファイルに移す

トークン削減の方針

• 構造化された情報には、説明文の代わりに表を使う
• 説明的な段落ではなく、簡潔な命令文を使う
• リファレンス資料は必要なときだけ読み込まれる別ファイルに移す
• 重複をなくし、同じことは一度だけ述べる
• パターンが自明でない場合にのみコード例を使う

停止 — テスト用プロンプトをもう一度頭の中で実行します。このスキルは5つすべてで正しく発動しますか？また、よく似ているが条件を満たさないケースでは発動しませんか？

フェーズ 4：検証して保存する

1. フェーズ 2 の必須要素が10個すべて含まれていることを確認する
2. トークン予算が目標内に収まっていることを確認する
3. フェーズ間に STOP マーカーがあることを確認する
4. SKILL.md ファイルを保存する
5. 各テスト用プロンプトでスキルを呼び出してテストする

検証チェックリスト

#	確認項目	状態
1	Frontmatter に name と description がある	[ ]
2	Description が「Use when」で始まっている	[ ]
3	概要が2～3文である	[ ]
4	フェーズに番号が付いており、STOP マーカーがある	[ ]
5	意思決定表がある（説明文ではない）	[ ]
6	アンチパターンの表がある	[ ]
7	合理化を防ぐガードがある	[ ]
8	統合ポイントの表がある	[ ]
9	具体例がある	[ ]
10	スキルの種類が宣言されている（RIGID/FLEXIBLE）	[ ]
11	合計500行未満である	[ ]

スキルの種類とテスト

スキルの種類ごとのテスト

スキルの種類	テスト方法	検証内容
テクニック（TDD、デバッグ）	問題 X と、通常とは異なる問題 Y に適用する	適切な手順を実行し、適切に応用できる
パターン（デザインパターン）	コード X（一致）とコード Y（よく似ているが不一致）を提示する	正しく識別し、正しく却下できる
リファレンス（API ドキュメント、チェックリスト）	「X のルールは何か？」と「エッジケース Z ではどうか？」と尋ねる	正しい答えを見つけ、情報の不足に対応できる
規律（セキュリティレビュー）	正しいコードをレビューし、その後、時間に追われている状況でレビューする	問題のないコードを正しく評価し、時間に追われてもすべてのルールを徹底できる

アンチパターン／よくある間違い

間違い	問題となる理由	代わりに行うこと
説明が発動条件ではなく内容を説明している	スキルが選択されない	「Use when」から始め、発動条件を列挙する
範囲が広すぎる — 何にでも発動する	何にも役立たない	対象となるアクションと成果物を絞る
長すぎる — 1000行以上ある	呼び出すたびにコンテキストトークンを浪費する	500行未満に抑え、リファレンス資料を分割する
制約がない	エージェントが手順を省略する理由を正当化する	「Do NOT」ルールと HARD-GATE マーカーを追加する
実際のプロンプトでテストしていない	本番環境で誤作動する	スキルを書く前にテスト用プロンプトを作成する
外部ファイルへの依存	ファイルが存在しない可能性があり、壊れやすい	自己完結させるか、まずファイルの存在を確認する
表が適している箇所で説明文を使う	ひと目で把握しにくく、トークンも増える	構造化された比較には表を使う
フェーズ間に STOP マーカーがない	エージェントがチェックポイントなしに先へ進む	各フェーズの後に STOP を追加する

合理化を防ぐガード

• [HARD-GATE] まずテスト用プロンプトを定義せずにスキルを書いてはいけません（フェーズ 1）
• [HARD-GATE] description フィールドを省略したり、「Use when」以外の形式にしたりしてはいけません
• 省略禁止：強化フェーズを省略してはいけません — すべてのスキルで合理化のレビューが必要です
• 省略禁止：検証チェックリストを省略してはいけません — 11項目すべてに合格する必要があります
• 禁止：500行を超えるスキルを作成してはいけません — スキルとリファレンスファイルに分割してください
• 禁止：表のほうが明確な箇所で説明文を使ってはいけません

統合ポイント

スキル	関連性
self-learning	スキルシステムを通じてスキルを検出し、読み込みます
auto-improvement	スキルの有効性を追跡し、改善を提案します
spec-writing	JTBD 手法を使用してスキルを仕様化できます
code-review	デプロイ前に、スキルの品質をレビューする必要があります
testing-strategy	テスト用プロンプトはテスト手法に従います

具体例：完全な最小スキル

---
name: docker-setup
description: "Use when creating Dockerfiles, docker-compose configurations, or containerizing an application for development or production"
---

# Docker Setup

## Overview

Guide the creation of Docker configurations for development and production environments. Produces Dockerfiles, docker-compose files, and .dockerignore with best practices.

## Phase 1: Discovery
[Ask about: runtime, ports, volumes, env vars, multi-stage needs]
STOP — confirm requirements.

## Phase 2: Generate Configuration
[Create Dockerfile, docker-compose.yml, .dockerignore]
STOP — present for review.

## Phase 3: Verify
[Build image, run container, verify health check]

## Anti-Patterns
| Mistake | Fix |
|---------|-----|
| Running as root | Use non-root USER |
| No .dockerignore | Always create one |

## Skill Type
**Flexible**

スキルの種類

厳格 — TDD のアプローチ（最初にテスト用プロンプトを作成）、必須の構成要素、検証チェックリストに厳密に従う必要があります。要素を省略することはできません。