ドキュメントをスキルに変える

チュートリアル · 6 分で読めます

エージェントに持たせたい知識は、たいていすでにどこかに書かれています。オンボーディングの PDF、Word のスタイルガイド、Markdown のランブック。足りないのは知識ではありません。文書は最初から最後まで読む人に向けて書かれているのに対し、スキルは作業の途中でそれを読み込み、行動しなければならないエージェントのために機能する必要がある、ということです。

Skilnu はこの変換の最初の一周を引き受けられます。文書をアップロードすると SKILL.md の下書きが返ってきます。中心となる考え方、重要な定義、実行できる指針が、指示として組み直されたものです。何も公開されません。読んで、おかしなところを直し、納得してから公開する — 他のどのスキルともまったく同じです。

1. 文書をアップロードする

アプリで + New skill を開き、「SKILL.md をアップロード」の隣にある Draft from a document をクリックします。ファイルを選んだらお待ちください。文書を丸ごと読んで書き直すため、アプリの他の操作よりも時間がかかります。

対応している形式: .pdf、.docx、.txt、.md、.markdown、.rst、.adoc。

それ以外はアップロード前に拒否されます。この一覧にない形式なら、まず PDF に書き出してください。その経路は十分に整っています。

2. 送るのは一節であって、蔵書ではありません

抽出テキストにはおよそ 40,000 文字という上限があり、長めの章 1 つ分にあたります。それを超えるとアップロードは黙って切り詰められるのではなく拒否されます。300 ページの本の最初の 40,000 文字だけから起こしたスキルの下書きを、その本から起こしたかのように渡されるのは、エラーよりたちが悪いからです。

これは聞こえるほど窮屈ではありません。よいスキルを作る条件と、この上限に収まる条件は同じ — ひとつのまとまった主題だからです。「私たちのコードレビュー基準」はスキルですが、「エンジニアリング・ハンドブック全体」はスキルの入ったフォルダーです。大きな文書なら章ごとに分け、別々に下書きしてください。どのみち、全体を一度に通したときより良いスキルになります。

3. スキャンした PDF は先に OCR が必要です

実体がページの写真である PDF には抽出できるテキストがないため、空のスキルではなく、その旨を伝えるメッセージが返ります。まず任意の OCR ツールを通し — たいていの PDF アプリには「テキストを認識」が入っています — 検索可能な版をアップロードしてください。

手早い見分け方: PDF を開いて一文を選択してみてください。選べなければ画像です。

4. 下書きをきちんと読む

下書きは作成フォームに現れ、名前と説明はその frontmatter から埋まります。これは、あなたの文書を一度読んだモデルによる最初の一周です。仕上がった成果物としてではなく、有能な同僚の初稿として読んでください。

毎回確かめる価値があるのは次の 3 点です。

具体的な記述は残っているか？ Commands, thresholds, names of internal tools, the actual numbers. These are the most useful part of a skill and the easiest thing to lose when prose gets condensed.

何か作り話をしていないか？ The draft is told to stay inside what the document supports, but if your document was vague somewhere, check that the draft was vague in the same place rather than confidently filling the gap.

これは指示か、それとも要約か？ The failure mode to watch for is a draft that describes what the document says instead of telling the agent what to do. If a section reads like a book report, rewrite it as a rule.

5. 公開する

納得がいくまでフォームで編集し、通常どおり公開します。そこから先はごく普通のスキルです。バージョン管理でき、他のスキルから依存でき、チームと共有でき、MCP ライブラリにも追加できます。

エージェントから行う場合

同じ流れは MCP でも、2 つのツールとして利用できます。その間にファイルがストレージへ届く必要があるからです。アップロード URL を求め、バイト列を送り、それから下書きを求めます。

get_document_upload_url(filename="handbook.pdf")
  -> { upload_url, document_key }

PUT the file's bytes to upload_url
  (no auth header -- the URL is already signed)

draft_skill_from_document(document_key=...)
  -> { name, description, skill_md }

エージェント版には、ウェブフォームにはない instructions 引数があり、ここでは実際に役立ちます —「第 3 章に絞って」「この分野が初めての人向けに書いて」「コード例はすべて残して」。あなたの恒常的なコンパイル指示を置き換えるのではなく、その上に重なります。

他と同じく、draft_skill_from_document は下書きを作るだけです。公開は別の publish_skill 呼び出しなので、あなたが下書きを見る前にエージェントが文書を公開済みスキルに変えてしまうことはありません。

費用

下書き 1 件につき、1 日のコンパイル枠を 1 単位使います。モデルは設定で選んだもの — 公開時にコンパイルする場合と同じ予算です。対応していないファイルや長さ超過など、モデルに届かないまま失敗した下書きは何も消費しません。

アップロードした文書は一時的な置き場です。成功・失敗にかかわらず下書きが生成された時点で削除され、それでも残ったものは 24 時間以内に消えます。公開されるスキルの一部になることは決してありません。含まれるのは、あなたが確認した下書きだけです。

どんなときに向いているか

いちばん向いているのは、すでに仕事のやり方が書き込まれている文書です。スタイルガイド、レビューのチェックリスト、インシデント対応のランブック、引用ではなく適用してほしい技術書の一章など。手順の入っていない参照資料 — API のダンプ、用語集、PDF に書き出した表計算 — は、元に取り出すべき指針がないため、痩せたスキルにしかなりません。

アップロード前のよい判断材料: 誰かがこの文書を読んだあと、何かを違うやり方でするでしょうか。するなら、スキルになります。調べ物にしか使わないものなら、たぶんなりません。