スキルを書くのにプログラマーである必要はありません。いちばんシンプルな形なら、フォルダと、その中のテキストファイル1つで足ります。ただ、よく働くスキルと、まったく起動しないスキルの差は、たいてい1つの文に隠れています。説明文です。この記事では、小さいけれど本物のスキルをゼロから書きます。
ステップ1: フォルダとSKILL.mdを作る
Agent Skillsの仕様によると、スキルは少なくとも1つのSKILL.mdファイルを含むフォルダです。ファイルの先頭にはYAMLのフロントマターがあり、必須項目は2つです。
- name: 最大64文字。小文字、数字、ハイフンのみ。ハイフンで始めることも終わることもできず、ハイフンを2つ続けることもできず、フォルダ名と一致している必要があります。Claudeのドキュメントはさらに、名前に「anthropic」と「claude」という語を使えないとも述べています。
- description: 空にはできず、最大1,024文字。スキルが何をするのか、いつ使うのかを書く必要があります。
任意の項目もあります(license、compatibility、metadata、実験的なallowed-tools)が、ほとんどのスキルには不要です。
ステップ2: 説明文を丁寧に書く
なぜ説明文がそんなに重要なのでしょうか。エージェントは起動時に、各スキルの名前と説明文だけを読むからです。agentskills.ioの表現を借りれば、起動の「負担のすべて」が説明文にかかっています。説明文がいつ役立つかを伝えていなければ、エージェントはそのスキルに手を伸ばしません。
各資料の推奨は、次のようにまとめられます。
- 何をするかといつ使うかの両方を書く。
- Claudeのドキュメントは、説明文がシステムプロンプトに入るため三人称で書くよう勧めています(「Excelファイルを処理する」はよく、「お手伝いできます」はよくない)。
- agentskills.ioは、ユーザーがその分野の名前を口にしない場面も明示的に挙げておくよう勧めています。
- 短く保つ。数文で、長くても短い段落まで。Claude Codeは一覧で説明文を1,536文字で切るので、最も重要な使用場面は先頭に置きましょう。
ステップ3: 本文は短く、スクリプトは賢く
例として、このブログ自身の執筆ルールに沿ったスキルを考えてみましょう。文章にダッシュ(emダッシュとenダッシュ)を残さない、というルールです。フォルダ構成はこうします。
tire-denetimi/
├── SKILL.md
└── scripts/
└── tire_bul.py
SKILL.mdファイルは、これだけです。
---
name: tire-denetimi
description: Türkçe blog yazılarında uzun tire (U+2014) ve orta tire (U+2013) kullanımını bulur ve düzeltme önerir. Kullanıcı bir Markdown yazısını yayına hazırlarken, "tireleri kontrol et", "yazım kurallarına uyuyor mu" dediğinde ya da adını anmasa da yayın öncesi son kontrol istediğinde kullanılır.
---
# Tire denetimi
1. `python scripts/tire_bul.py <dosya.md>` komutunu çalıştır.
2. Çıktıdaki her satır için tireyi nokta, virgül, iki nokta veya parantezle değiştirmeyi öner.
3. Anlamı değiştirme. Emin olmadığın satırları kullanıcıya sor.
4. Sonunda kaç satır düzelttiğini tek cümleyle bildir.
Claudeのドキュメントは、コンテキストウィンドウを「共有の資源」と見なし、モデルがまだ知らない情報だけを加えるよう勧めています。本文は500行未満に収めるべきです。長い参考資料は別ファイルに移し、SKILL.mdから1階層のリンクでつなぎます。
スクリプトのルールも明快です。「解決して、丸投げしない」。つまり、スクリプトはエラーの場合を自分で処理するべきで、「落ちてもClaudeがなんとかする」という発想で書いてはいけません。スクリプトが実行されたとき、コンテキストに入るのはコードそのものではなく出力だけです。そのため、繰り返しの作業やミスの許されない作業では、指示文よりスクリプトのほうが信頼できます。
ステップ4: テストして、もう一度テストする
Claudeのベストプラクティスガイドは、長いドキュメントを書く前に評価シナリオを用意することを勧めています。公開前のチェックリストには、少なくとも3つの評価と、Haiku、Sonnet、Opusの各モデルでの個別テストが入っています。理由は単純です。Opusで完璧に動く指示でも、Haikuにはもっと詳しい説明が必要かもしれないからです。
起動のテストについては、agentskills.ioの提案が具体的です。ユーザーのメッセージ例を約20個用意します。そのうち8〜10個はスキルを起動させるもの、8〜10個は起動させないものにします。いちばん価値のある否定例は「ぎりぎり外れる」もの、つまり同じ言葉を含みながら別の仕事を頼むメッセージです。モデルの挙動は毎回同じではないので、各メッセージを数回(最初は3回)実行して起動率を見るのがよいとされています。
| よくない説明文 | よい説明文 |
|---|---|
| 「PDFの作業を助けます。」 | 何をするか、いつ使うかを伝える |
| 技術的な詳細だけ | ユーザーの意図を伝える |
| 何でも対象にする | やらないことも明示する |
導入も簡単です。Claude Codeでは、フォルダを~/.claude/skills/の下(個人用)か、プロジェクトの.claude/skills/フォルダに置くだけです。Claude Codeはこれらのフォルダを監視していて、再起動しなくても同じセッション内で変更を検知します。claude.aiでは、設定からスキルをzipでアップロードできます。
あなたの最初のスキルは、どんな繰り返し作業を自動化しますか?