Agent Skillsを自作する方法【SKILL.mdの書き方を徹底解説】

既存のスキルを使っていると、「自分のワークフローに合ったスキルがほしい」と感じることがあります。

Agent Skillsは、SKILL.mdファイルを書くだけで作成できます。プログラミングの知識がなくても、ドキュメントが書ければスキルを作れます。

この記事では、オリジナルスキルの作成から公開までの流れを解説します。

スキル作成の基本

最小構成

スキルに必要なのは、SKILL.mdファイル1つだけです：

my-skill/
└── SKILL.md

SKILL.mdの書き方

---
name: daily-standup
description: 毎朝のスタンドアップミーティング用のサマリーを作成する
---

## 目的

チームのスタンドアップミーティングで共有するサマリーを作成します。

## 手順

1. 昨日のコミット履歴を確認
2. 進行中のPRを一覧化
3. 以下のフォーマットでサマリーを生成

## 出力フォーマット

### 昨日やったこと
- [コミット内容を箇条書き]

### 今日やること
- [PRのステータスから推測]

### 困っていること
- [なければ「特になし」]

各セクションの役割

セクション	必須	役割
name	✓	スラッシュコマンド名になる
description	✓	Claudeがスキルを選ぶ際の判断材料
目的	-	スキルの意図を明確にする
手順	-	Claudeが従うステップ
出力フォーマット	-	期待する出力の形式

より高度なスキル構成

参照ファイルを追加

大きなスキルは、詳細を別ファイルに分割できます：

my-skill/
├── SKILL.md
└── references/
    ├── coding-standards.md
    └── review-checklist.md

SKILL.mdから参照する：

## 詳細ルール

コーディング規約は `references/coding-standards.md` を参照してください。

スクリプトを追加

実行可能なスクリプトを含めることもできます：

my-skill/
├── SKILL.md
└── scripts/
    └── generate-report.sh

ただし、スクリプトの実行はツールによって対応状況が異なります。Claude Codeでは動作しますが、他のツールでは動かない可能性があります。

テンプレートを追加

Claudeに埋めてもらうテンプレートを用意できます：

my-skill/
├── SKILL.md
└── templates/
    └── pr-description.md

descriptionの書き方

descriptionは、Claudeがスキルを自動適用するかどうかを判断する重要な要素です。

悪い例

description: コードを確認する

曖昧すぎて、いつ使うべきかわかりません。

良い例

description: TypeScriptプロジェクトのプルリクエストをセキュリティ・パフォーマンス・型安全性の観点でレビューする

具体的なので、関連するタスクで自動的に適用されます。

ポイント

何をするスキルか明記する
どんな状況で使うか想像できる書き方にする
キーワードを含める（「PR」「レビュー」「TypeScript」など）

ベストプラクティス

サイズを小さく保つ

SKILL.md本体：5,000トークン以下
行数：500行以下

大きくなる場合は、references/に詳細を分割します。

1つのスキルに1つの責務

「コードレビューもしてテストも書いてデプロイもする」スキルは複雑すぎます。それぞれ別のスキルに分けましょう。

具体的な指示を書く

# ❌ 曖昧
コードをチェックしてください。

# ⭕ 具体的
1. 未使用のimportがないか確認
2. any型の使用箇所をリストアップ
3. console.logが残っていないか確認

期待する出力を示す

## 出力例

```json
{
  "issues": [
    {
      "file": "src/index.ts",
      "line": 42,
      "type": "unused-import",
      "message": "'lodash'がインポートされていますが使用されていません"
    }
  ]
}


## テスト方法

### 1. ローカルで配置

```bash
mkdir -p ~/.claude/skills/my-skill
cp SKILL.md ~/.claude/skills/my-skill/

2. Claude Codeで呼び出し

/my-skill

または、自然言語で関連するタスクを依頼してみます。

3. 動作確認

スキルが認識されているか（/skillsで確認）
期待通りの出力が得られるか
エッジケースでも動作するか

スキルの公開

GitHubで公開する手順

新しいリポジトリを作成
SKILL.mdと関連ファイルをpush
READMEに使い方を記載
（任意）Skill Galleryに登録申請

READMEに含めるべき内容

スキルの概要
インストール方法
使用例
対応ツール（Claude Code、Codex CLIなど）
ライセンス

よくある質問

スキルが動かない

フロントマターのnameが正しいか確認
ファイル名がSKILL.md（大文字）か確認
ディレクトリ構成が正しいか確認

複数のツールで動かしたい

基本的なSKILL.md形式は共通ですが、scripts/などの実行機能はツールによって異なります。汎用性を重視するなら、SKILL.md本体だけで完結するスキルにするのがおすすめです。

まとめ

Agent Skillsは、SKILL.mdファイルを書くだけで作成できます。

フロントマター（name、description）を書く
Claudeへの指示を本文に書く
ローカルに配置してテスト
GitHubで公開

まずは自分が繰り返している作業を1つ選んで、スキル化してみてください。

スキル一覧で他の人が作ったスキルを参考にするのもおすすめです。

チームでスキルを共有する方法 - 作ったスキルをチームで使う
スキルのセキュリティベストプラクティス - 安全なスキルを作るために
開発効率を上げる7つのTips - スキルを使いこなすコツ
CLAUDE.mdからの移行ガイド - 既存設定をスキル化