Claude Skills の自作手順。SKILL.md 1枚で作る専用処理
Skills の自作は、思っているより素朴です。フォルダを1つ作って `SKILL.md` を1枚書くだけ。プログラミング言語も特別な知識もいりません。マギのクロゼミの記事執筆ルールを Skill 化する流れを実例に、最小構成からスタートして、起動しない原因の潰し方まで通しで見ていきます。
はじめに
Skills シリーズの最終章、自作編 です。前2本で、
- Skills とは何か：「専門知識のパッケージ」を Claude に渡す仕組み
- 公式 Skills を使う：
/init、/security-reviewなどを実際に呼ぶ手順
を見てきました。今回は、いよいよ 自分専用の Skill を作る ところに進みます。
「自作」と聞くと身構える方が多いのですが、Skills の自作は HTML のページを1枚作るのと同じくらいの素朴さ です。プログラミング言語は要りませんし、特別な開発環境も要りません。Markdown が書ければ、その日のうちに最初の Skill が動きます。
本記事では、マギのクロゼミの記事執筆ルールを Skill 化する流れを例に、
- 最小構成（フォルダ +
SKILL.mdだけ） - frontmatter の書き方
- 本文の書き方の原則
- 動かしてみる
- 起動しないときの直し方
- 関連ファイル（
examples/、references/）の足し方
の順で進めます。読み終わるころには、自分専用の Skill が手元で動いているはずです。
最小構成は「フォルダ1つ + ファイル1枚」
Skill を作るのに必要なものは、
- フォルダ1つ
- そのフォルダの中に
SKILL.mdというファイル1枚
これだけです。
~/.claude/skills/ ← 全 Skill を置く場所（ユーザー全体用）
└── magi-article-writer/ ← Skill 1つ = フォルダ1つ
└── SKILL.md ← 必須。本体~/.claude/skills/ というフォルダはあなたの ホーム配下のClaude設定フォルダ にあります（macOS の場合 /Users/あなたの名前/.claude/skills/）。最初は存在しないことが多いので、なければ作って構いません。
CSS で例えるなら、これは /css/components/header.css を新規作成して <head> から読ませる のと同じくらいの作業量です。フォルダを作ってファイルを置くだけ、です。
ステップ・バイ・ステップで作ってみる
実例として、「マギのクロゼミの記事を書くときのルール」を Skill にする という設定で、いちから組み立てます。
Step 1. フォルダを作る
ターミナルで（あるいはエクスプローラ／Finder で）、~/.claude/skills/magi-article-writer/ というフォルダを作ります。
mkdir -p ~/.claude/skills/magi-article-writer-p を付けると、途中の ~/.claude/skills/ がなくてもまとめて作ってくれます。
Step 2. SKILL.md を作る
そのフォルダの中に、SKILL.md という空のファイルを作ります。テキストエディタで普通に新規作成して、ファイル名を SKILL.md で保存するだけです。
Step 3. frontmatter を書く
SKILL.md の冒頭に、以下のような frontmatter（設定部分） を書きます。
---
name: magi-article-writer
description: マギのクロゼミ向けの新規記事を執筆する依頼が来たときに、口調・構成・避けたい表現のルールを適用する
------ で挟まれた3行が frontmatter で、ここが Claude にとっての「この Skill は何のためのものか」を伝える 索引カード になります。
Step 4. 本文を書く
frontmatter の下に、Skill が呼ばれたときに Claude が読む 本文 を書きます。
---
name: magi-article-writer
description: マギのクロゼミ向けの新規記事を執筆する依頼が来たときに、口調・構成・避けたい表現のルールを適用する
---
# マギのクロゼミ 記事執筆ルール
## 口調
- フォーマルな日本語、ですます調
- 「マギ」persona で書く（社長個人の名前は出さない）
- 絵文字は使わない
- 「〜と思われます」「〜でしょう」の曖昧表現は使わない
## 構成
1. はじめに（この記事の位置づけ・誰向けか）
2. 本論（h2 単位で 4〜6 章）
3. 「全部覚えなくていい」風の和らぎ段落
4. まとめ（番号付きリストで要点）
5. 次記事への誘導
## 避けたい表現
- 「破壊的操作」のような硬い専門語をそのまま使わない
→ 「元に戻せない操作」「取り返しのつかない操作」と言い換える
- 「驚くべき」「革新的」のような誇張表現を使わない
- 大げさな収益報告・誇大表現は書かないこれで Skill 1つの中身は完成です。プログラミングは1行も書いていません。
Step 5. 動かす
Claude Code を起動し直して、/help を打ってみてください。Skills の一覧に magi-article-writer が現れているはずです。
> /help
Built-in:
...
Skills:
/magi-article-writer マギのクロゼミ向けの新規記事を執筆する依頼が来たときに……
/security-review ...
...これで、Claude に「マギのクロゼミの新しい記事を書いて」と依頼すると、この Skill の本文が自動的に参照される 状態になります。/magi-article-writer と明示的に呼んで動作確認するのが、最初は確実です。
frontmatter の書き方、3つの原則
frontmatter は「Skill が呼ばれるかどうか」を左右する最重要パーツです。書き方には3つだけ原則があります。
原則1. name は kebab-case の英語にする
name は 半角英字＋ハイフン で書きます。magi-article-writer、lp-coding-rules、weekly-report-template のように、意味のある英単語をハイフンで繋ぐ のが定石です。
スペースや日本語、アンダースコア、キャメルケースは避けたほうが無難です。これは /help で表示されるコマンド名（/magi-article-writer）にもなるので、毎日打って苦にならないか を判断軸にすると良いです。
原則2. description は「いつ使うか」を書く
description の役割は 「この Skill はどういう場面で使うべきか」を Claude に教える ことです。「何ができるか」だけでなく、「いつ Claude がこれを思い出すべきか」 を書くのがポイント。
| 良くない例 | 良い例 |
|---|---|
| 記事を書く Skill | マギのクロゼミ向けの新規記事を執筆する依頼が来たときに、口調・構成・避けたい表現のルールを適用する |
| LP 用 | LP（ランディングページ）案件のコーディングを依頼されたときに、BEM 命名規約・WebP 画像・フォームのラベルルールを適用する |
| セキュリティ確認 | コードに対してセキュリティ観点でのレビューを依頼されたとき、SQLインジェクションとXSSの観点で差分を逐行確認する |
「いつ呼ばれるべきか」が具体的に書いてあると、Claude が「いまの依頼に当てはまる」と判断しやすくなります。曖昧だと、自然言語で頼んでも発火しません。
原則3. 短すぎず、長すぎず
description は 1〜2文で収める のが目安です。短すぎると判断材料にならず、長すぎると逆に何の Skill かぼやけます。「いつ／何のために／何をする」の3点が簡潔に揃っていれば十分です。
本文の書き方、3つの原則
frontmatter の下にくる本文は、Skill が呼ばれたあとに Claude が読むメモ です。書き方の原則を3つだけ。
原則1. 命令形で具体的に書く
「〜してほしい」より「〜する」「〜しない」と 断定する ほうが、Claude の挙動がブレません。
| ぼんやり | はっきり |
|---|---|
| ですます調がいいかな | ですます調で書く。だ／である調は使わない |
| 絵文字はあまり使わない | 絵文字は使わない |
| 短めがいい | 1段落は3文以内に収める |
原則2. 例（good）と反例（bad）をセットで載せる
Claude は 具体例から学ぶ のが得意です。「こうしてほしい」だけでなく、「こうするのは避けてほしい」も並べると、判断のブレがぐっと減ります。
## 言い換えのルール
「破壊的操作」のような硬い専門語は柔らかい言い換えに置き換える。
✅ よい例
- 「元に戻せない操作」「取り返しのつかない操作」
❌ 避ける例
- 「破壊的操作」
- 「Destructive operation」（英語そのまま）WordPress テーマ制作で、ヘッダーのコーディング例を 「こう書いてほしい」と「こう書かないでほしい」 の両方で示すのに似ています。
原則3. プロジェクト固有の前提を全部書く
Claude は外部の文脈を知りません。「マギのクロゼミ」と言っても、「それは何のサイトか」「どういう読者層か」「現状どんな記事が公開されているか」を その場で全部教える必要 があります。
たとえば、
## 前提
マギのクロゼミは Claude × AI × Web制作の実体験メディア。
読者は Web 制作の経験はあるが、AI 系のツール／プログラミング全般には詳しくない方を想定。
専門用語を使うときは必ず平易な言葉で補足する。というふうに、「Claude が知らない側」の情報を全部書き出す のが、ブレない Skill の条件です。
動かしてみて、思ったように動かないとき
Skill を作って Claude Code を起動し直しても、思ったように動かない ことはよくあります。原因の多くは次の3つに収束します。
症状1. /help にそもそも出てこない
→ 保存場所か、ファイル名か、frontmatter のどれかが間違っている 可能性が高いです。チェックポイントは、
- フォルダが
~/.claude/skills/<name>/の階層になっているか - ファイル名が
SKILL.mdになっているか（小文字skill.mdやSkill.mdではない） - frontmatter の冒頭・末尾の
---がそれぞれ独立行で書かれているか
の3点。Claude Code を再起動 することも必要です。実行中のセッションは新しい Skill を読み込みません。
症状2. / から呼ぶと動くけど、自然言語で呼ぶと発火しない
→ description が曖昧な可能性が高いです。「いつ／何の依頼が来たときに使うか」を、より具体的に書き直してみてください。「記事を書く」より「マギのクロゼミ向けの新規記事を執筆する依頼が来たとき」と書くだけで、発火率は目に見えて上がります。
症状3. 呼ばれているのに、書かれているルールを守ってくれない
→ 本文が 抽象的すぎる か、他のルール（CLAUDE.md など）と矛盾している 可能性があります。
抽象的なときは「✅ よい例 / ❌ 避ける例」を本文に追記すると効きます。矛盾しているときは、CLAUDE.md と Skill のどちらが正解かを揃える必要があります。
関連ファイル：examples/ と references/
Skill のフォルダには、SKILL.md 以外にも 任意のファイル を置けます。よくある構成が、
magi-article-writer/
├── SKILL.md
├── examples/ ← 参考になる過去記事を置く
│ ├── good-article-1.md
│ └── good-article-2.md
└── references/ ← 補足ドキュメント
├── tone-of-voice.md
└── word-list.mdこの examples/ や references/ は、Claude が必要だと判断したときにだけ読まれる 関連物です。SKILL.md の本文に「実例は examples/ を見ろ」と書いておくと、Claude が「あ、参考が必要だ」と判断したときにだけ追加で読みに行きます。
容量的には大きくなっても、普段は索引（description）の数十文字しか読まれない という progressive disclosure の恩恵が効きます。「重い参考資料を抱えても、普段の動作は軽い」という設計が成立する場所です。
配置場所の使い分け（おさらい）
前回お伝えした3階層を、自作の文脈で整理し直すと、
| 階層 | 場所 | 自作で使う場面 |
|---|---|---|
| User（個人） | ~/.claude/skills/<name>/ | 自分の手癖（記事執筆、よく書くコンポーネント、毎週のレポート） |
| Project（案件） | <案件フォルダ>/.claude/skills/<name>/ | その案件固有のコーディング規約、用語集、ブランドガイド |
ということになります。「全プロジェクトで使い回したい知識は User、その案件でだけ使う知識は Project」 という分け方が、迷わない判断軸です。
「失敗してもいい」雰囲気で始める
Skills の自作は、最初の1個目を作ったときに「思ったより簡単だった」と感じる のが正解です。プログラミングは1行も書かず、Markdown の心地で書いて、保存して、Claude Code を再起動する。それだけ。
最初の Skill が動かなくても、SKILL.md を1行書き直して再起動すれば、すぐに違いが出ます。「動かなければ書き直す」を3〜4回繰り返すうちに、自分なりのコツがつかめてくる タイプの機能です。
私自身も、最初に作った Skill は description が曖昧で発火せず、何度か書き直しました。「いつ使うか を具体的に書く」というコツが体感でわかったのは、3個目を作ったあたりです。最初から完璧を狙わず、動くものをまず1個出して、そこから直していく のが、無理のない順序になります。
まとめ
Skills 自作の要点を整理します。
- 必要なのはフォルダ1つと
SKILL.md1枚だけ：プログラミング不要 - 置き場所は
~/.claude/skills/<name>/（User）か<案件>/.claude/skills/<name>/（Project） - frontmatter の
nameは kebab-case の英語：/helpのコマンド名になる descriptionは「いつ使うか」を具体的に：これが起動の鍵- 本文は命令形で、例と反例をセットで、前提を全部書く
- 動かないときは：場所／ファイル名／frontmatter／再起動 を順に確認
- 関連ファイル（
examples/、references/）は必要時だけ読まれる：重くしても普段は軽い - 最初は完璧を狙わず、動かして直す
これで Skills シリーズの3本（とは／使う／自作する）を読み終わりました。Claude Code が 「人が作ったツール」から「自分仕様のツール」に変わる 入口に立った状態になっているはずです。
次の記事「Claude Code の Plugins とは」では、Skills のさらに上位概念にあたる プラグイン を扱います。プラグインは「Skills と Slash Commands と Hooks と MCP をひと包みにして、他人にも配布できるようにする入れ物」です。続けて読むと、自分の Skills を 「公開して使ってもらう」 という新しい選択肢が見えてきます。
WordPressを実際に動かしてきたサーバー：ロリポップ
Claude Code でWordPressサイトを組み立てるとき、最初に置く先として無理のないレンタルサーバー。月数百円から始められ、WordPressの自動インストールにも対応しています。設定で詰まりがちな初期段階の時間をかなり減らせます。