初めてのSkillを最初から最後まで書く
- 動作するSkillをゼロから構築し、それが実際に起動することを実証する
- 適切なタイミングでトリガーされる description を書く — Skillが起動するかどうかを決める唯一のフィールド
- 決定論的なデータ収集のために、いつヘルパースクリプトを追加すべきかを判断する
- 起動しないSkillを診断し、その原因となる3つの落とし穴を知る
動作するSkillをゼロから構築し、それが起動することを実証しましょう。小さな「changelogエントリ」Skillを作ります — 汎用的で再利用可能なものです。
ステップ1 — フォルダを作成する
Skillのフォルダを作成する
mkdir -p .claude/skills/changelog-entry
（すべてのプロジェクトにまたがる個人用Skillには ~/.claude/skills/… を使ってください。）
ステップ2 — SKILL.mdを書く
.claude/skills/changelog-entry/SKILL.md:
---
name: changelog-entry
description: Use when the user wants to turn recent git commits into a Keep a Changelog entry.
---
# Changelog Entry
When asked for a changelog entry:
1. Run `git log --oneline -20` to see recent commits.
2. Group them into Added / Changed / Fixed / Removed (Keep a Changelog style).
3. Write concise, user-facing bullets (not raw commit messages).
4. Output only the formatted entry.
description がトリガーです — 「Use when…」の形式で書くことで、Claude が適切なタイミングでこれを読み込みます。
ステップ3 — （任意）ヘルパースクリプトを追加する
Skillはスクリプトを同梱できます。決定論的なデータ収集を行いたい場合は、scripts/recent.sh を追加し、SKILL.md から参照してください:
#!/usr/bin/env bash
git log --oneline -20
ステップ4 — トリガーされることを実証する
セッションを開始して、下のプロンプトを試してください。Claude は意図を認識し、Skillを読み込み、その手順に従うはずです。起動しない場合は、おそらく description がそれをいつ使うかについて十分に具体的でないので、より鋭くしてください。
Skillがトリガーされることを実証する
Draft a changelog entry for recent work.
ステップ5 — 共有する
（他のものと一緒に）プラグインにまとめれば、チームが1ステップでインストールできます — あるいは AILmanac のskillパックに貢献しましょう。
落とし穴
- 曖昧な description → 決してトリガーされない（または常にトリガーされる）。具体的にしましょう。
- 1つのSkillに詰め込みすぎ → 1つの明確な仕事に絞りましょう。
- 共有Skillにシークレット → 絶対にやめましょう。サードパーティコードのレビューを参照してください。
- Skillとはフォルダと SKILL.md のことです — プロジェクト用は .claude/skills/<name>/、すべてのプロジェクト用は ~/.claude/skills/
- description がトリガーです。「Use when…」の形式で書き、Claude が適切なタイミングで読み込めるようにしましょう
- Skillはスクリプトを同梱できます — Claude にコマンドを即興させるのではなく、決定論的なデータ収集をしたいときに使いましょう
- Skill名を指定するのではなく、意図をプロンプトすることで動作を実証しましょう。起動しないなら、description が「いつ」について十分具体的ではありません
- 1つのSkillは1つの明確な仕事に絞り、共有するSkillには決してシークレットを入れないこと