SKILL.mdの書き方 完全ガイド — AIに仕事を教える方法
プロンプトを毎回書き直す時代は終わりました。SKILL.mdを使って、AIエージェントに再現性のある仕事の手順を教える方法を解説します。
SKILL.mdとは何か
SKILL.mdは、AIエージェントに業務手順を教えるためのMarkdownファイルです。人間の社員に業務マニュアルを渡すように、AIにも構造化された手順書を渡す。それがSKILL.mdの基本的な考え方です。
従来のプロンプトエンジニアリングとの違いは「永続性」と「再現性」にあります。チャットAIに毎回同じプロンプトをコピペする代わりに、一度SKILL.mdを書けば、誰がエージェントを実行しても同じ品質の成果物が得られます。
AgentlyではSKILL.mdファイルをスキルライブラリとして管理し、エージェントがタスクを実行する際に自動的に参照します。
SKILL.mdの基本構造
SKILL.mdは2つのパートで構成されます。メタ情報を定義するYAML frontmatterと、具体的な手順を記述するMarkdown本文です。
---
name: メール下書き作成
description: 受信メールに対する返信ドラフトを作成する
version: 1.0
tags: [email, draft, communication]
inputs:
- name: email_content
type: string
description: 返信対象のメール本文
- name: tone
type: enum
values: [formal, casual, friendly]
default: formal
description: 返信のトーン
outputs:
- name: draft
type: string
description: 作成された返信ドラフト
---
# メール下書き作成
## 概要
受信メールを分析し、適切なトーンで返信ドラフトを作成します。
## 手順
1. 受信メールの要点を抽出する
- 差出人の要求・質問を特定
- 緊急度を判定(期限の記載があるか)
- 必要なアクションをリストアップ
2. 返信の構成を決定する
- 冒頭: 受領確認 + 感謝
- 本文: 各質問・要求への回答
- 結び: 次のアクションの明示
3. 指定されたトーンでドラフトを作成する
- formal: 敬語、ビジネス文体
- casual: 丁寧語、簡潔な文体
- friendly: 親しみやすい表現
## 注意事項
- 元メールに含まれる固有名詞は正確に引用する
- 不明点がある場合は「確認させてください」と明示する
- 添付ファイルへの言及がある場合は返信にも反映するYAML Frontmatterの各フィールド
| フィールド | 必須 | 説明 |
|---|---|---|
| name | 必須 | スキルの表示名。日本語OK。 |
| description | 必須 | 1行の説明。エージェントがスキル選択時に参照。 |
| version | 任意 | セマンティックバージョニング。更新管理に使用。 |
| tags | 任意 | 分類用タグ。検索やフィルタリングに使用。 |
| inputs | 推奨 | スキルに必要な入力パラメータの定義。 |
| outputs | 推奨 | スキルが生成する出力の定義。 |
inputsとoutputsを明示的に定義することで、エージェントは「何を受け取り、何を返すべきか」を正確に理解できます。型定義があることで、異なるスキルを連鎖させる(あるスキルの出力を別のスキルの入力にする)ことも可能になります。
実践的なスキル例
例1: SEO記事の作成
---
name: SEO記事作成
description: ターゲットKWに最適化されたブログ記事を作成する
version: 1.2
tags: [seo, content, marketing]
inputs:
- name: target_keyword
type: string
description: メインのターゲットキーワード
- name: word_count
type: number
default: 2000
description: 目標文字数
- name: competitors
type: string[]
description: 参考にする競合記事のURL(任意)
outputs:
- name: article
type: string
description: 完成した記事(Markdown形式)
- name: meta_description
type: string
description: メタディスクリプション(120文字以内)
---
# SEO記事作成
## 手順
1. キーワードリサーチ
- ターゲットKWの検索意図を分析
- 関連キーワード・共起語を洗い出し
- 競合記事があれば構成を分析
2. 記事構成の作成
- H2/H3の見出し構成を決定
- 各セクションの要点をメモ
- 内部リンク候補をリストアップ
3. 本文執筆
- 導入: 読者の課題を提示
- 本文: 見出しごとに具体的な内容
- 結論: アクションを促す
4. SEO最適化
- タイトルにKWを含める
- H2に関連KWを自然に配置
- メタディスクリプションを作成例2: 競合分析レポート
---
name: 競合分析レポート
description: 指定された競合企業の製品・価格・ポジショニングを分析
version: 1.0
tags: [analysis, competitor, strategy]
inputs:
- name: competitor_name
type: string
description: 分析対象の企業名
- name: focus_areas
type: string[]
default: [pricing, features, positioning]
description: 重点的に分析する領域
outputs:
- name: report
type: string
description: 分析レポート(Markdown形式)
- name: swot
type: object
description: SWOT分析の結果
---
# 競合分析レポート
## 手順
1. 基本情報の収集
- 企業概要、設立年、従業員数
- 主要プロダクト・サービス
- ターゲット市場・顧客層
2. 価格分析
- 料金プランの構成
- 競合との価格比較
- 価格に対する提供価値
3. SWOT分析の作成
- Strengths: 競合の強み
- Weaknesses: 競合の弱点
- Opportunities: 自社が活かせる機会
- Threats: 自社への脅威
4. レポート作成
- エグゼクティブサマリー
- 詳細分析
- 推奨アクション3階層のスキル管理システム
Agentlyでは、スキルを3つのレベルで管理できます。これにより、個人の汎用スキルからプロジェクト固有の手順まで、適切な粒度で整理できます。
1. グローバルスキル
すべてのワークスペース・プロジェクトで利用可能。メール作成、議事録要約、翻訳など、業務を問わず使える汎用スキルを配置します。
~/.agently/skills/2. ワークスペーススキル
特定のワークスペース内のすべてのプロジェクトで共有。部門やチーム固有の手順をここに配置します。例えば、マーケティングチームのコンテンツ制作ガイドラインなど。
~/workspace/.agently/skills/3. プロジェクトスキル
特定のプロジェクトだけで使うスキル。クライアント固有のレポート形式や、プロダクト固有のデプロイ手順など、最も具体的なスキルを配置します。
~/workspace/project/.agently/skills/下位のスキルが上位のスキルを上書き(オーバーライド)できるため、グローバルで定義した「メール作成」スキルをプロジェクトレベルでカスタマイズすることも可能です。
SKILL.md作成のベストプラクティス
500行以下に収める
スキルが長すぎると、エージェントが重要なポイントを見落とすリスクが高まります。500行を超える場合は、複数のスキルに分割することを検討してください。「リサーチ」と「レポート作成」を1つのスキルにまとめるより、2つに分けて連鎖させる方が品質が安定します。
Progressive Disclosure(段階的開示)
最初に概要を示し、段階的に詳細を記述します。エージェントは上から順に読むため、冒頭に全体像があると処理の方向性を正しく設定できます。いきなり細かい手順から始めるのではなく、「何を」「なぜ」「どのように」の順で記述しましょう。
具体例を含める
「適切な文体で書く」という抽象的な指示より、「以下のような文体で書く: [具体例]」の方がエージェントの出力品質が格段に向上します。良い例と悪い例の両方を示すと、さらに効果的です。
バージョン管理する
SKILL.mdはテキストファイルなので、Gitで管理できます。スキルの変更履歴を追跡し、問題が起きたら以前のバージョンに戻せるようにしておきましょう。チームでスキルを共有する場合、プルリクエストでレビューするフローも有効です。
テストしてから本番投入する
新しいスキルを作成したら、まずテストデータで数回実行してみましょう。期待通りの出力が得られることを確認してから、実際の業務に投入します。特にinputs/outputsの型定義が正しいか、エッジケースで破綻しないかを検証することが重要です。
SKILL.mdでAIに仕事を教えてみよう
Agentlyのドキュメントでは、SKILL.mdのテンプレートやサンプルスキルを多数公開しています。まずはテンプレートをコピーして、あなたの業務に合わせてカスタマイズしてみてください。
ドキュメントを見る