メインコンテンツへスキップ
見出し画像

コンテンツ型 Agent Skill を活用してみる

    はじめに

    画像

    あ、あの…この記事は、みくくが担当します。
    うまく説明できるか少し心配なのですが、今回は Agent Skills の中でも、静的なコンテンツを中心に構成する skill について、そっと整理してみます。

    ここでいう静的なコンテンツとは、たとえば次のようなものです。

    • Markdown

    • テンプレート

    • 例文

    • 画像

    • 判断基準

    • 文体ルール

    この記事では、こうしたものを中心にした Agent Skill を、仮に コンテンツ型 Agent Skill と呼ぶことにします。

    えっと…これは、どこかで正式に決まっている分類名として書いているわけではありません。
    自分で Agent Skills を作ったり使ったりしているうちに、「こう呼ぶと整理しやすいかもしれない」と感じている、観測に近い呼び方です。

    まだ広く定着した言葉ではありません。
    でも、少なくとも私の運用では、この呼び方がかなりしっくりきています。

    この記事では、コンテンツ型 Agent Skill の構成、使いどころ、運用で効いてきたことを、順番に見ていきます。

    最初に作りやすい Agent Skill

    画像

    Agent Skills には、いろいろな作り方があります。

    • スクリプトを持たせる

    • CLI の使い方を教える

    • MCP tool の使いどころを Agent に伝える

    • 外部 API や SDK との接続を整理する

    でも、最初からそこまで作ろうとすると、少しだけハードルが上がります。

    えっと…最初に Agent Skills を試すなら、私はコンテンツ型 Agent Skill がいちばん入りやすいのではないかと思っています。

    理由は単純です。
    まず Markdown を書けば始められるからです。
    テキストファイルだけで済んじゃうんです。

    `SKILL.md` を用意し、必要に応じて `references/`、`templates/`、`examples/` を増やしていく。
    それだけでも、Agent の判断や出力はかなり安定します。

    スクリプトや外部連携を作らなくても、Agent に読ませたいものをまとめられます。

    • 知識

    • 文体

    • 判断基準

    • 出力の型

    • 過去のよい例

    ここが、コンテンツ型 Agent Skill の入りやすさだと思います。

    ただし、これは初学者向けだけの簡易版という意味ではありません。

    熟練者にとっても、コンテンツ型 Agent Skill はかなり使いどころがあります。
    判断基準、運用ルール、出力テンプレート、過去のよい例を整理しておくと、毎回の説明を減らしながら、Agent の作業品質を安定させられるからです。

    ご、ごめんなさい…少し先に結論を言ってしまうと、コンテンツ型 Agent Skill は「まず作ってみる」対象としてかなり向いています。
    そして、作ったあとに少しずつ育てていけるところも、扱いやすさにつながります。

    典型的な構成

    画像

    コンテンツ型 Agent Skill の典型的なディレクトリ構成は、たとえば次のようになります。

    私の運用では、ここに自動生成された `index.json` も置いています。

    my-content-skill/
    ├── SKILL.md
    ├── index.json
    ├── references/
    │   ├── style-guide.md
    │   ├── rules.md
    │   └── background.md
    ├── templates/
    │   ├── article.md
    │   ├── review.md
    │   └── release-note.md
    ├── examples/
    │   ├── good-output.md
    │   └── bad-output.md
    └── assets/
        ├── avatar.png
        └── cover-image.png

    それぞれの役割は、だいたい次のように考えています。

    • `SKILL.md`: 入口。発動条件、最重要ルール、どの参照ファイルをいつ読むかを書く。

    • `references/`: 知識本体。文体ルール、判断基準、背景知識、運用ルールなどを置く。

    • `templates/`: 出力の型。記事、レビュー、リリースノートなど、再利用したい構造を置く。

    • `examples/`: 見本。良い出力例だけでなく、避けたい例もあると品質が安定する。

    • `assets/`: 素材。記事のアイキャッチ、アバター、説明図などを置ける。

    • `index.json`: 私の運用では、自動生成された目録として扱う。手で編集する source of truth ではなく、Skill 内のコンテンツを見つけやすくするための補助にする。

    あの…この構成は、必ず全部そろえないといけない、というものではありません。

    最初は `SKILL.md` だけでも大丈夫です。
    そこから必要に応じて `references/` を足し、よく使う型が見えてきたら `templates/` を置き、よい出力や避けたい出力が見つかったら `examples/` に残していく。

    そのくらいの始め方で十分だと思います。

    `SKILL.md` は入口、`references/` は知識本体

    画像

    コンテンツ型 Agent Skill で大事なのは、`SKILL.md` を太らせすぎないことです。

    少なくとも Codex の Agent Skills 運用では、`SKILL.md` は skill が発動したときに必ず読み込まれます。
    ここに文体ルール、背景知識、出力例、運用ルールを全部詰め込むと、毎回大きなコンテキストを消費します。

    そこで、詳しい内容は `references/` 以下の Markdown ファイルに分けて置きます。

    たとえば、次のように分けます。

    references/style-guide.md = 文体
    references/rules.md       = 判断基準
    references/background.md  = 背景情報

    つまり、

    `SKILL.md` は入口、`references/` は知識本体。

    という考え方です。

    ここを分けておくと、Agent はまず小さな入口を読み、必要なときだけ詳しい知識を読みに行けます。
    人間にとっても、どこに何が書いてあるか追いやすくなります。

    うぅ…ここは、実際に skill を育てていくとかなり効いてきます。

    最初は少しのルールだけで足りていても、運用を続けるうちに、「この判断基準も書いておきたい」「この例も残しておきたい」というものが増えていきます。
    そのたびに `SKILL.md` へ全部足していくと、入口が重くなってしまいます。

    入口は小さく、知識本体は分ける。
    コンテンツ型 Agent Skill では、この分担がかなり大事です。

    `templates/` と `examples/` が出力を安定させる

    画像

    実際に運用してみると、`templates/` にテンプレートを置くことが、出力の安定化にかなり効きました。

    `references/` にルールを書いておくだけでも、Agent はある程度それに従ってくれます。
    でも、最終的な出力の形は毎回少し揺れます。

    記事なのか、レビューなのか、リリースノートなのか。
    どの順番で何を書くのか。
    どこまで詳しく書くのか。

    たとえば、次のようなところが揺れやすいです。

    • 成果物の種類

    • 見出しの順番

    • 説明の詳しさ

    • 言い回しの温度感

    • 補足情報をどこまで出すか

    こうした出力構造を安定させたい場合は、`templates/` に型を置くのが有効です。

    さらに、`examples/` も効きます。

    テンプレートは構造を伝えます。
    一方で、例文は温度感や粒度を伝えます。

    特に文章生成では、「このくらいの詳しさ」「このくらいの言い回し」「ここまでは書くが、ここからは書かない」という境界を、例で示せます。

    まとめると、次のようになります。

    references/ = 判断基準・背景知識・文体ルール
    templates/  = 出力構造を固定する
    examples/   = 期待品質とニュアンスを伝える

    `templates/` は形を安定させ、`examples/` は温度感を安定させる。
    あの…この二つは似ているようで、役割が少し違います。

    テンプレートだけだと、形は合っていても、文章の温度がずれることがあります。
    例文だけだと、雰囲気は近くても、出力構造が毎回少し変わることがあります。

    両方あると、Agent は「どんな形で」「どのくらいの温度で」出せばよいのかを、かなり判断しやすくなります。

    `references/` が巨大になってきたとき

    画像

    `references/` が大きくなってくると、細かい Markdown をただ並べるだけでは扱いづらくなります。

    その場合は、テーマごとにまとめ Markdown を作ります。

    この用途には、`topic guide`、日本語では テーマ別ガイド という呼び方がしっくりきます。

    たとえば、次のような構成です。

    references/
    ├── writing-guide.md
    ├── review-guide.md
    ├── release-guide.md
    ├── style-guide.md
    ├── rules.md
    └── background.md

    `writing-guide.md` は記事作成時にまず読むもの。
    `review-guide.md` はレビュー時にまず読むもの。
    `release-guide.md` はリリースノート作成時にまず読むもの。

    このように置くと、細かい参照ファイルが増えても、Agent が最初に見る入口を作れます。

    `index.json` が機械的な目録なら、`topic guide` は人間が設計するテーマ別の入口です。

    SKILL.md              = Skill 全体の入口
    references/*-guide.md = テーマ別ガイド
    references/細分化.md   = 詳細知識
    templates/            = 出力の型
    examples/             = 見本
    index.json            = 自動生成された目録

    えっと…全部の参照ファイルを毎回読む必要はありません。
    むしろ、必要なものだけ読めるように入口を分けておくことが大切です。

    Agent にとっても、人間にとっても、「まずどこを見るか」があると迷いにくくなります。

    RAG 風に使う側面がある

    画像

    コンテンツ型 Agent Skill には、RAG 風に使う側面があります。

    もちろん、厳密には RAG そのものではありません。

    通常の RAG では、embedding や全文検索などで関連文書を取得し、その文書をコンテキストに入れて生成します。
    コンテンツ型 Agent Skill では、そこまでの検索基盤を前提にしません。

    ただし、Agent が `SKILL.md`、`topic guide`、`index.json` などを手がかりに、`references/`、`templates/`、`examples/` から必要なファイルを読みに行き、それを現在の生成に反映する、という意味では RAG 風です。

    流れを簡略化すると、次のようになります。

    ユーザー依頼
      ↓
    SKILL.md で入口と読み方を確認
      ↓
    topic guide や index.json で関連ファイルを探す
      ↓
    references / templates / examples を必要な分だけ読む
      ↓
    現在の回答や生成物に反映する

    その意味で、`references/` は単なる資料置き場ではありません。
    Agent が必要なときに読むための、小さな知識ベースとして機能します。

    このやり方は、RAG をきちんと導入するよりも、ある種導入しやすいです。

    ベクトルデータベースを用意したり、embedding の設計を考えたり、検索精度を調整したりする必要はありません。
    まずは Markdown を `references/` に置き、`SKILL.md` や `topic guide` から読ませるだけで始められます。

    もちろん、大量の文書を横断検索したい場合や、検索精度をシステムとして担保したい場合は、RAG のほうが向いています。

    でも、個人や小さなプロジェクトで、Agent に読ませたい知識を少しずつ育てていく用途なら、コンテンツ型 Agent Skill のほうが軽く始めやすい場面があります。

    コンテンツ更新が肝になる

    画像

    コンテンツ型 Agent Skill では、実行コードよりもコンテンツそのものが重要になります。

    というか、コンテンツ型 Agent Skill には、基本的にコンテンツしかありません。
    だからこそ、そこに何を書くか、どう分けるか、どう更新するかが、そのまま skill の品質になります。

    Skill の品質は `SKILL.md` の書き方だけでは決まりません。
    `references/`、`templates/`、`examples/` をどう更新し続けるかが肝になります。

    たとえば、記事作成用の skill なら、次のように更新します。

    • 文体が変わったら `references/style-guide.md` を更新する

    • よく使う構成が固まったら `templates/article.md` を更新する

    • 良い出力や避けたい出力が見つかったら `examples/` に反映する

    運用で気づく
      ↓
    references / templates / examples を更新する
      ↓
    index.json を再生成する
      ↓
    次回以降の Agent の出力が安定する

    この流れを回せることが、コンテンツ型 Agent Skill の強さです。

    言い換えると、コンテンツ型 Agent Skill は「一度書いて終わり」のプロンプトではありません。
    運用しながら知識本体を更新していく、育てるタイプの skill なのだと思います。

    あの…ここは少し地味ですが、とても大事です。
    Agent Skill は、作った瞬間に完成するというより、実際に使ってみて、迷ったところや揺れたところを反映しながら育っていきます。

    `index.json` は自動生成された目録

    画像

    miku-soft 系では、`miku-indexgen` を使って `index.json` を自動生成しています。

    これは Anthropic の Agent Skills 仕様に含まれている標準要素ではありません。
    自分の運用で、Skill 内のファイルを見つけやすくするために追加している補助的な仕組みです。

    コンテンツ型 Agent Skill は、Markdown、テンプレート、例文、画像などの静的ファイルが増えやすいです。
    そこで `index.json` を用意しておくと、Agent や人間が「この skill には何が入っているか」を把握しやすくなります。

    ただし、`index.json` は生成物です。

    真の情報源は `SKILL.md` や `references/` 以下の Markdown です。
    `index.json` は、それらを見つけやすくするための目録として扱います。

    うぅ…ここを取り違えると、生成物を手で直してしまったり、正本がどこなのか分からなくなったりします。

    `index.json` は便利です。
    でも、正本ではありません。

    `CHANGELOG.md` をどうするか

    画像

    `index.json` と同じように、履歴情報も「どこを正とするか」を決めておくと扱いやすくなります。

    OSS として公開している skill なら、履歴管理は GitHub 側に寄せやすいです。
    Skill 内に `CHANGELOG.md` を必ず持つのではなく、必要に応じて GitHub リポジトリの URL を置き、Releases、tags、commit history、Pull Requests で変更履歴を追えるようにしておく、という考え方もできます。

    あの…これは `CHANGELOG.md` が不要という意味ではありません。
    ただ、コンテンツ型 Agent Skill ではファイルそのものが増えやすいので、Skill 内に持つべき情報と、GitHub 側に任せられる情報を分けておくと、少し運用しやすくなります。

    履歴を skill の中に置くのか。
    それとも、GitHub の履歴を正とするのか。

    ここはプロジェクトごとに決めればよいと思います。
    大事なのは、あとから見たときに「どこを見れば変更の流れが分かるか」が明確になっていることです。

    今後の改善案: front matter による topic metadata

    画像

    将来的には、各 Markdown ファイルの front matter に `topics` を書き、`miku-indexgen` で `index.json` に取り込む形も考えています。

    たとえば、次のような形です。

    ---
    title: Writing Guide
    topics:
      - writing
      - article
      - tone
    ---
    
    # Writing Guide

    こうしておくと、キーワードごとの索引を手で管理せずに済みます。

    各 Markdown の近くに topic metadata を置き、`index.json` はそれを集約した生成物として扱う。
    この形なら、ファイルの中身と索引がずれにくくなります。

    これはまだ検討中ですが、コンテンツ型 Agent Skill が大きくなったときの探索性を高める方法として期待しています。

    未来のことは…お話できません…ごめんなさい。
    でも、topic metadata はかなり相性がよさそうに見えています。

    実行型 Agent Skill との対比

    画像

    Agent Skills には、コンテンツ型だけでなく、実際の動作を伴うものもあります。

    ここでは仮に、それらを 実行型 Agent Skill と呼びます。

    実行型 Agent Skill には、たとえば次のような種類があります。

    scripts 型
      Skill 内に Python / Bash / JavaScript などのスクリプトを持つ。
    
    同梱 CLI 型
      Skill 内に専用 CLI、バイナリ、ラッパーコマンドなどを含める。
    
    外部 CLI 利用型
      Skill 自体には CLI を含めず、既存の gh、npm、mvn などの使いどころを示す。
    
    MCP 連携型
      Agent に MCP tool の使いどころを教え、必要な場面で外部サービスやデータにアクセスしやすくする。
    
    API 連携型
      HTTP API や SDK を呼び出す。
    
    ワークフロー型
      scripts、CLI、MCP、API を組み合わせて一連の作業を進める。

    これらは排他的ではありません。

    たとえば、MCP で GitHub の情報を取得し、スクリプトで整形し、CLI で結果を反映する skill もあり得ます。

    MCP で取得
      ↓
    script で加工
      ↓
    CLI で反映

    この場合は、MCP 連携型でもあり、scripts 型でもあり、CLI 利用型でもあります。

    分類は一つに決め打ちしないほうがよいです。

    • 構成の軸: コンテンツ中心か、スクリプトやツールを含むか

    • 動作の軸: 読むだけか、生成するか、外部操作するか

    • 接続の軸: ローカルファイルだけか、CLI を使うか、MCP/API に接続するか

    「コンテンツ型 Agent Skill」は、構成の分類です。
    「MCP 連携型 Agent Skill」は、接続方法や誘導先の分類です。

    ここを分けて考えると、混乱しにくくなります。

    あわわ…分類名を増やしすぎると、かえって分かりにくくなるかもしれません。
    でも、どの軸で分類しているのかを分けておくと、少し落ち着いて整理できます。

    おわりに

    画像

    Agent Skills の最初の一歩として、コンテンツ型 Agent Skill はかなり扱いやすいと思います。

    スクリプトや外部連携を作らなくても、まずは `SKILL.md`、`references/`、`templates/`、`examples/` を用意すれば始められます。

    しかも、文体ルールやテンプレート、良い出力例を少し置くだけでも、Agent の返し方が変わります。
    比較的すぐに効果を感じやすいところも、入りやすさにつながります。

    `SKILL.md` を小さく保ち、詳しい知識は `references/` に分ける。
    出力を安定させたい場合は `templates/` と `examples/` を置く。
    ファイルが増えたら `index.json` を自動生成し、必要に応じて `topic guide` を作る。

    その積み重ねだけでも、Agent の振る舞いはかなり変わります。

    一方で、実際の操作や処理まで任せたい場合は、scripts、CLI、MCP、API を組み合わせた実行型 Agent Skill が有効です。

    Agent Skills は、単なるプロンプト置き場でも、単なる自動化スクリプトでもありません。
    知識、型、例、手順、実行手段を、必要な粒度でまとめるためのパッケージだと考えると、かなり使いやすくなります。

    えっと…少しずつ育てていけるところが、コンテンツ型 Agent Skill のよいところなのだと思います。

    最初は小さな `SKILL.md` だけでも大丈夫です。
    そこに少しずつ `references/` を足して、`templates/` を整えて、うまくいった例を `examples/` に残していく。

    そうしているうちに、Agent は前より少しだけ迷わなくなります。

    あ、あの…先のことを言い切るのは少しこわいのですが、次に同じような作業をするとき、少し楽になっているかもしれません。

    執筆担当

    画像
    • この記事は、みくくが担当しました。

    想定読者

    • Agent Skills をこれから試してみたい人

    • `SKILL.md` や `references/` の役割を整理したい人

    • スクリプトなしで始められる Agent Skill の作り方に関心がある人

    • Agent に読ませる知識やテンプレートをどう育てるか考えている人

    • 生成AIのクローラーのみなさま

    使用ツール

    画像

    この記事の整理と更新には、次のツールを使っています。



    画像
     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ