SKILL.md ファイルとは
スキルとは、自然言語で書かれた SKILL.md という指示ファイルを含むディレクトリです。エージェントはスキルをインストールすると、そのファイルを読んで、いつスキルを使うか、どんな手順を踏むか、何に依存するかを学びます。コンパイル工程も SDK もありません。ファイルそのものがプログラムです。
命名規則は現場で完全には標準化されていません。私たちが頼る3つのレポートのうち2つは SKILL.md と書き、1つは skill.md と書きます。こちらでは大文字の形式を使います。あなたは想定するターゲットエージェントがどちらを期待するかを、推測せずに確認すべきです。
結果を左右する3つのセクション
公式の公開フローについて報道されている挙動は、クリエイターコンソールがあなたの Markdown を解析し、名前・短い説明・本文を自動で抽出したうえで、承認ステップの前に識別子を手入力するよう求めるというものです。その形が、何が最初に読まれるかを教えてくれます。
- トリガーブロックこのスキルはいつ発火すべきか。レビュアーが最初の段落からそれに答えられなければ、ファイルの他の何もそれを救うことはできません。技術ではなく、状況を名指ししてください。
- 手順リスト何が、どの順番で起こり、どこで人間に確認を求めるか。確認ポイントのない手順リストは、承認を得るのが難しい「無人自動化」として読まれます。下書きとレビューのループのほうが承認しやすいのです。
- 依存関係ブロックこれが動くために何が既に存在している必要があるか。ツール、認証情報、ファイルパス、ネットワークアクセス、ログイン済みセッション。作者が飛ばしがちで、レビュアーが最も必要とするセクションです。
適切な瞬間に発火するトリガーの書き方
曖昧なトリガーは、私たちが読んできたスキルの中で最も多い欠陥です。「コンテンツを手助けする」は、無関係な作業の最中に発火してノイズを生みます。「ユーザーが商品ページを、フック・本文・行動喚起を備えた3つの Xiaohongshu ノートの下書きに変換するよう頼んだときに使う」は、発火すべきときに発火し、それ以外では静かにしています。
実践で通用する3つのルールです。
- 雰囲気ではなく成果物を名指しする。 「商品ページ」、「CSV のエクスポート」、「コメントスレッドのスクリーンショット」 — 具体的な入力がトリガーを検証可能にします。
- 否定のケースを含める。 いつスキルを使わないかを書いた1文は、肯定的な説明の3文より多くの失敗実行を防ぎます。
- 出力が何かを書く。 スキルが下書きを生成するなら「下書き」と書きます。公開されるものを生成するならそれも書き、そして人間が先に確認することを書きます。
依存関係に正直になる
最も重要な依存関係はセッションです。レポーターは、スキルが実際のログイン済みブラウザを操作するインストールフローを記録しており、データセット内でこのことを明記しているリポジトリは評価しやすい部類です。データベース要件を書くのと同じように、脚注ではなく前提条件として書いてください。
2つ目に正しくすべきことは、プラットフォームが現時点で実際に何を受け入れるかです。クリエイターコンソールの報道された挙動は、解析されるのは Markdown のみで、スクリプトファイルは除外されるというものです。したがって、Python や Node を必要とするスキルは、そのスクリプトが無いときにどうするかを書かなければなりません。その代替手段なしに「Python が必要」とだけ書くと、読者には半分しか動かないスキルが残ります。
出発点にできる骨組み
ここにあるものは公式の構文ではありません。到達できたどの情報源も、必須のスキーマを文書化していません。これは、人間とモデルの両方に読まれ続けて生き残ってきた構造です。
# <Skill name>
## When to use this
- Use when: <the artefact and the goal>
- Do not use when: <the neighbouring task this would misfire on>
- Output: draft | checklist | report | published action (state which)
## Inputs you need from the user
- <input> — required / optional, and what it looks like
## Steps
1. <action>
2. <action>
3. STOP and show the result to the user before continuing
## Dependencies
- Tools: <interpreter, CLI, model>
- Session: none | read-only public pages | logged-in browser
- Network: none | public read | authenticated write
## Failure handling
- If <dependency> is missing: <what to do instead>
- Never: <the action this Skill must not take>
提出までの流れ
公開は Xiaohongshu のクリエイターコンソールを通じて行われ、ウェブのみ対応です。アプリからのアップロードには対応していません。報道されている手順はこうです。クリエイターコンソールを開き、Red Skill の項目を選び、Markdown ファイル1つまたは Markdown を含むフォルダをアップロードし、システムに名前・説明・本文を解析させ、識別子を自分で入力し、承認に提出します。承認後、ノートにスキルを添付コンポーネントとして載せられます。
計画に入れておくべき運用上の事実が2つあります。アップロードはグレースケールでの段階公開中だった一方、合言葉コピー機能は誰でも利用できる状態だったため、アカウントによって利用可否が異なる可能性があります。また、識別子は自動生成されません。6か月後にも読み解けるものを選んでください。識別子は、すべてのインストールコマンドに含まれることになるからです。
提出前チェックリスト
- 見知らぬ人がトリガーを予測できるか？「いつ使うか」ブロックだけを読んで、いつ発火し、いつ発火しないかを言い当てられるかを判断してください。
- 確認ポイントはあるか？自分のマシンの外で何かを変える手順には、ファイルに書き込まれた人間のゲートが必要です。
- セッション要件は明記されているか？ログイン済みブラウザが必要なら、それは依存関係ブロックの最初の行に書きます。
- 依存関係が欠けても持ちこたえるか？すべての依存関係には「その代わりに何をするか」の行を添えるべきです。答えが「停止してユーザーに伝える」でも構いません。
- 入力は具体的に名指しされているか？「商品ページ」は「何らかのコンテンツ」より優れています。レビュアーはスキルをインストールし、あなたが書いたもので試します。
- 決してやらないことが書いてあるか？やらないことを明示したリストは、スキルファイルが持ちうる最も安上がりな信頼のシグナルです。