Skill のパターンとベストプラクティス
よくあるパターン、アンチパターン、優れた skill ビルダーの習慣
⏱ 想定 ~8 分
01 · 読む
skill がどう動くか分かったところで、開発者が日々実際に使っているパターンを見ていきましょう。
人気のある skill はいくつかのカテゴリに収まります。- コードスタイル—命名規則、書式ルール、構造パターンを強制する - コードレビュー—PR やコード変更を一貫した観点でレビューする - コミットメッセージ—Conventional Commits のような形式を強制する - テスト—プロジェクトのテストフレームワークやパターンに合わせる - ドキュメント—ドキュメント、コメント、README の書き方を標準化する
どのパターンも同じ構造に従います: 明確なルール、具体的な例、はっきりした出力形式。最も役立つ 2 つを見ていきましょう。
ポイントまとめ
- コードスタイル skill は命名、書式、構造の慣習を強制する
- レビュー skill は一貫したコードレビューチェックリストを提供する
- コミットメッセージ skill は Conventional Commits のような形式を強制する
- テスト skill はプロジェクトの既存のテストパターンに合わせる
- ドキュメント skill はドキュメントの書き方を標準化する
02 · コード例
下は、すべてのコミットメッセージに Conventional Commits 形式を強制する skill です。
commit-style/SKILL.md
---
name: Commit Message Style
description: Enforces Conventional Commits format
instructions: Use when creating git commits
---
## Format
All commits must follow Conventional Commits:
```
<type>(<scope>): <description>
[optional body]
```
## Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `refactor`: Code change that neither fixes nor adds
- `test`: Adding or updating tests
- `chore`: Maintenance (dependencies, CI, build)
## Rules
- Description must be lowercase, no period at the end
- Scope is optional but encouraged
- Body should explain WHY, not WHAT (the diff shows what)
- Max 72 characters for the first line
## Examples
Good: `feat(auth): add password reset flow`
Good: `fix(api): handle null response from payment gateway`
Bad: `Fixed stuff`
Bad: `Update code`
どれだけ明確かを見てください—正確な形式、列挙された type、文字数上限、良い例と悪い例。ルールが明確であるほど、Claude のコミットは一貫します。「良いコミットメッセージを書いて」のような曖昧な指示では効きません。
03 · コード例
下は、プロジェクトの既存のテスト慣習に Claude を合わせる skill です。
test-writer/SKILL.md
---
name: Test Writer
description: Writes tests matching project conventions
instructions: Use when writing or updating tests
---
## Conventions
- Use `describe` / `it` blocks (not `test`)
- Test file goes next to source: `Foo.ts` → `Foo.test.ts`
- Use `vi.fn()` for mocks (Vitest, not Jest)
- Arrange-Act-Assert pattern in every test
## What To Test
- Happy path first
- Error cases and edge cases
- Boundary values (0, 1, -1, empty string, null)
- Never test implementation details — test behavior
## Naming
`it('should return 404 when user not found')`
Not: `it('test user')`
この skill はプロジェクト固有のテストフレームワーク(Vitest)とパターン(describe/it、vi.fn)を参照しています。「良いテストを書いて」のような汎用的な指示は効きません—Claude はもともとそうしようとしています。この skill はあなたの特定の慣習を Claude に伝えるためのものです。
04 · クイズ
覚えておきましょう: skill には Claude が自分では知り得ないルールを加えるべきです。次のうち、Claude の振る舞いを実際に変えられるほど具体的な指示はどれでしょう？
- 良いコードを書く役に立つアシスタントになって
- API エンドポイントを書くときは、camelCase の key を持つ JSON を返し、URL は kebab-case を使い、エラーコードは error-codes.ts ファイルのものを使う
- コードを書くときは常にベストプラクティスを使う
- シニアエンジニアのようにコードを書く
05 · ドラッグ分類
skill の質に最も大きく影響するのは何かを考えてみましょう。例のない曖昧な skill は、具体的なものに劣ります—これらの実践を、影響の大きい順に並べてください。
（このセクションはインタラクティブです — JavaScript を有効にしてください。）
06 · 読む
Claude を悪化させる skill もあります。下は避けるべきパターンです。曖昧すぎる: 「良くて、きれいなコードを書いて。」Claude はもともとそうしようとしています。あなたの skill は、Claude 自身では知り得ない具体的なルールを加えるべきです。
長すぎる: 想定されるあらゆる状況にルールを書いた 500 行の skill は、Claude のコンテキストを圧迫します。skill はひとつのワークフローに集中させましょう。焦点の絞られた skill が複数あるほうが、巨大な skill ひとつより優れています。
組み込みの振る舞いの重複: Claude はすでにコードを整形でき、markdown を書け、git を使えます。Claude がデフォルトでうまくやれることに skill のスペースを使わないでください。
矛盾するルール: 「常にコメントを付ける」+「コードは最小限に保つ」は混乱を生みます。テストする前に、ルールに内部矛盾がないか確認しましょう。
ポイントまとめ
- 曖昧な skill を書かない—具体的に書くか、書かないか
- 巨大な skill を書かない—1 つの skill につき 1 つの焦点を絞ったワークフロー
- Claude がデフォルトでうまくやれることを重複させない
- skill の中にルールの矛盾がないかチェックする
07 · 読む
あなたはいま、ほとんどの Claude Code ユーザーが知らない超能力を手に入れました:Claude にあなたの正確な働き方を教える力です。
チームには慣習があります。開発者には好みがあります。Skill は、明文化されていないルールを永続的で、共有可能で、バージョン管理された指示に変えます。
小さく始めましょう。Claude に最もよく伝えていることをひとつ選び、それを skill にしてください。テストし、磨き、コミットする。そしてもうひとつ追加する。時間が経つにつれて、あなたの skill コレクションは力の増幅器になります—skill を書くごとに、Claude はあなた固有の仕事でより役に立つようになります。
汎用的な AI アシスタントと、自分専用に調整された AI ワークフローの違いは何か?それが Skill です。
ポイントまとめ
- 最も繰り返している指示ひとつ分の skill から始める
- 反復する: テスト、磨き、コミット
- プロジェクト skill を git で共有して、チーム全員が恩恵を受けるようにする
- 時間とともにコレクションを育てる—skill が増えるほど、Claude はあなたの仕事で賢くなる
- Skill が、汎用的な AI アシスタントと自分専用の AI ワークフローを分ける
08 · クイズ
「良くて、きれいなコードを書いて」とだけ書いた skill を作りました。テストしてみると、Claude の出力に違いがないように見えます。なぜでしょう？
- SKILL.md ファイルに構文エラーがある
- Skill は Opus モデルでしか動かない
- 指示が曖昧すぎる—Claude はもともと良いコードを書こうとしている
- skill を追加したあとは Claude Code を再起動する必要がある
09 · 空欄補充
あらゆる状況を 500 行でカバーする skill はアンチパターンです。代わりに、ひとつのワークフローを扱う _____ skill を複数書くべきです。
⚠ 全機能のインタラクティブ体験には JavaScript が必要です。JavaScript を有効にして再読み込みしてください。
※ このサイトは独立した教育プロジェクトで、Anthropic の公式製品ではありません。Claude™ は Anthropic, PBC の商標です。