Tutorial

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本文です。

email-draft.skill.md
---
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記事の作成

seo-article.skill.md
---
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: 競合分析レポート

competitor-analysis.skill.md
---
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のテンプレートやサンプルスキルを多数公開しています。まずはテンプレートをコピーして、あなたの業務に合わせてカスタマイズしてみてください。

ドキュメントを見る