サインインブリーフィングを予約

第 2.20 章

スキル

Skills Engine スキルの作成、テスト、公開の方法、公開後にそれが表示される場所、およびプラグイン内のマニフェストスキルとの違いについて説明します。Harrow Port Authority 向けの実践的なバース割り当てサマリーが含まれています。

このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

読了時間 17 分

Harrow Port AuthorityのプラットフォームエンジニアであるTomás Reilly氏から先月、バースプランナーたちがアシスタントに「明日どのバースに誰が着岸し、何が変更されたか?」と尋ねるたびに異なる回答が返ってくるのはなぜかと質問されました。その答えは、良い回答とはどのようなものかを誰もアシスタントに教えていなかったからでした。Skills Engineのスキルによって、この問題は半日で解決しました。現在、プランナーたちは毎回、最初にバースの表、その下に前回の計画からの変更点、そして最後に競合という、同じ3部構成の要約を受け取っています。この章では、そのスキルを最初から最後まで一通り解説し、その後、プラグインのマニフェスト内に存在するもう1つの種類のスキルについて取り上げます。

2種類のスキル

Nexusでは2つの異なるものに「スキル」という言葉を使用しており、それらは異なる方法で構築されます。

Skills Engineスキル マニフェストスキル
その内容 スキルライブラリ内のSKILL.mdパッケージ プラグインのskills[]配列内の型付き行
作成者 権限を持つすべての人(クリエイターまたは自身のエディター内) 開発者(プラグイン内)
含まれる内容 指示、呼び出し可能なツール、任意のファイルおよびスクリプト 入力および出力スキーマ、ティア、およびそのティアが必要とするフィールド
プラットフォームへの到達方法 検証、アップロードされ、Skills Engineに公開される マニフェストからコンパイルされ、スキルレジストリに同期される
実行主体 アシスタント、エージェント、ワークフロー、AI(人工知能)ボタン、Claude Code UNO(ワークフローエンジン)ディスパッチ
主な用途 「毎回同じ方法でバース計画を要約する」 「このパスで当社の軌道伝播プログラムを実行する」

この章の残りの部分では、これら2つを区別して扱います。段落内で単に「スキル」とだけ記されている場合は、Skills Engineのスキルを指します。

パート1:Skills Engine スキル

スキルとは何か

スキルとはフォルダーです。そのSKILL.mdには、スキルが何のためのものであり、どのようにジョブを実行するかが記されています。その横には、ジョブが必要とするファイルや実行するスクリプトが配置されます。エンジンはスキルを3つのレイヤーで読み込みます。名前と説明は常に読み込み、タスクがスキルを要求したときに指示を読み込み、ステップが必要としたときにのみファイルを読み込みます。そのため、1つのインストール環境に200個のスキルを保持していても、実際に使用されるまではほとんどコストがかかりません。

skills/<slug>/
├── SKILL.md      # required: YAML frontmatter, then the instructions
├── skill.yaml    # optional: engine metadata (triggers, aliases, tags, capabilities)
└── scripts/      # optional: bundled with the skill as components

ディレクトリ名はスキルのスラッグと一致している必要があります。不一致は検証時の警告となりますが、ライブラリはスラッグを使用してアップロードを既存のスキルと照合するため、修正する価値があります。

SKILL.mdのフロントマター

フロントマターは、ファイル先頭の2つの---行の間にあるYAMLです。このフォーマットでは3つのフィールドが必須です。検証自体がブロックするのは、名前または説明の欠落、およびすでに使用されているスラッグまたはジョブタイプなど、ごく一部の項目のみです。それ以外はすべて警告として報告されます。

フィールド 型 必須 保持する内容
name 文字列 yes ケバブケースの一意の識別子
description 文字列 yes スキルの機能(最大500文字)。ライブラリとマッチャーがこれを読み取るため、これが適切なスキルかどうかを判断する読者向けに記述してください
allowed-tools 文字列またはリスト yes スキルが呼び出すことのできるツール。実行者の許可リストを絞り込むことのみ可能です
triggers リスト no スキルを直接呼び出すスラッシュコマンド
capabilities リスト no 構造化された機能。それぞれがname、descriptionを持ち、任意でinput_schema、output_schema、およびexamplesを持ちます
version 文字列 no セマンティックバージョン。省略時は1.0.0
visibility 文字列 no private、team、またはpublic
status 文字列 no draft、testing、またはpublished

指示は約5,000トークン以下に抑えてください。具体的に記述し、例を示してください。各スキルは1つのジョブを的確にこなすべきです。「さらにまた」と書いている自分に気づいたら、おそらくそれは2つのスキルに分けるべきです。

skill.yaml

skill.yamlは、エンジンがディスカバリやライブラリのために必要とする情報を保持するため、SKILL.mdの可読性が保たれます。エンジンが読み取るフィールドには、name、display_name、description、version、status、visibility、triggers、aliases、category、tags、allowed_tools、およびcapabilitiesが含まれます。機能には、マッチャーがそこへ送信すべき言い回しであるquery_patternsを持たせることができます。また、エンジン自身のバジェット管理のためのヒントとして、complexity、estimated_tokens、およびrequired_servicesもあります。

scripts/

scripts/配下のものはすべて、コンポーネントとしてそのままスキルにバンドルされます。スクリプトは実行されるものであり、モデルのコンテキストに読み込まれることは決してなく、サンドボックス内で実行されます。ステップが算術計算や構文解析であり、モデルに頭の中で行わせるべきではない場合に使用してください。

公開範囲とステータス

公開範囲(Visibility)は、誰がそのスキルを見つけられるかを示します。privateはあなた自身、teamはあなたのチーム、そしてpublicはライブラリが提供される組織内の全員です。コンソールでは、同じ選択肢が「自分のみ」、「通関デスク」などのチーム、または組織全体として表示されます。また、スキルはドメインパック独自のレビューを通じて、そのパック内で共有することもできます。

ステータスは、スキルがそのライフサイクルのどの段階にあるかを示します。

ステータス 意味
draft 作成中。検索不可
testing 検証中。アクセス制限あり
published 一般利用可能
deprecated 廃止予定。引退に向けた移行段階

一度公開されたバージョンは決して変更されません。コンソールにおいて、「live」、「canary」、「shadow」はバージョンに付与されるラベルであり、以前のバージョンに切り替えるとラベルが移動します。実行中の処理は、開始時のバージョンで最後まで完了します。

新規スキル · 2 指示とツール
新規スキル · 2 指示とツール
クリエイターの第2ステップでは、ドラフトのSKILL.md、その横にあるファイルとそれぞれの読み込みタイミング、およびスキルが呼び出すことのできるツールが表示されます。チェック用のスキルには書き込みを行うツールは提供されず、スキルは実行者の許可リストを絞り込むことしかできません。

フォルダーから稼働スキルへ

Skills Engineのリポジトリにある5つのnpmスクリプトが、スキルをエディターからライブラリへと送り届け、到達したことを証明します。

コマンド 行うこと
npm run skill:validate skills/<slug> パッケージをリントします。公開にはエラーがゼロである必要があります
npm run skill:upload skills/<slug> 検証と公開を1ステップで行います(べき等)
npm run skill:upload skills/<slug> --dry-run 何も書き込まずに検証を行い、プランを出力します
npm run skill:publish -- --dry-run skills/<slug> アップロードの背後にある低レベルの公開処理(同じパイプライン)
npm run skill:reconcile リポジトリ内のスキルを、ライブラリおよびスキルレジストリが保持しているものと比較します
npm run skill:live:verify 稼働中のインストール環境で、公開されたスキルをエンドツーエンドでチェックします

公開処理は2つのエントリを書き込みますが、どちらも重要です。1つはスキル自体であり、そのSKILL.mdの本文、機能、コンポーネント、および品質記録を含みます。ライブラリ、ディスカバリ、およびマッチングはこれを読み取ります。もう1つは、ワークフローエンジンがディスパッチを解決する際に照合するレジストリエントリです。レジストリにしか到達していないスキルも実行はされますが、アップロードするまではライブラリ内で表示されません。

公開処理はべき等です。変更されていないスキルは何も処理を行わず(no-op)、既存のスキルはそのスラッグによって照合され、再作成されることなくその場で更新されます。すでに公開されているバージョンと同じバイト列をアップロードすると、重複は作成されず、CONTENT_HASH_ALREADY_PUBLISHEDとともにそのバージョンが返されます。

skill:reconcileは、リポジトリのスキルをライブラリ、レジストリ、およびワークフローエンジンのインベントリと照らし合わせて走査し、一方に存在して他方に存在しないものをすべて報告します。skill:live:verifyは、稼働中のインストール環境でさらに踏み込んだ確認を行います。両方のエントリが存在し、同じコンテンツハッシュでお互いを指していること、スキルのジョブタイプのドライランディスパッチが受け入れられること、スキルがライブラリの一覧と詳細に表示されること、呼び出し可能であること、そして監査証跡がスラッグとリクエストIDによって公開、ディスパッチ、および実行を結びつけていることを確認します。

ワークステーションからは、アップロードはポートフォワードを介してインストール環境のナレッジサービスであるnexus-graphragに到達するため、環境変数にSkills Engineのサービスキーが必要です。キーをエコー表示せずに読み込むには次のようにします。

kubectl -n nexus port-forward svc/nexus-graphrag 8090:8090
read -rs GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
export GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
GRAPHRAG_URL=http://localhost:8090 npm run skill:upload skills/berth-allocation-summary

クラスター内のパイプラインジョブでは、デフォルトのアドレスが自動的に解決されるため、GRAPHRAG_URLは不要です。キーは組織独自のシークレット管理プロセスを通じて取得してください。リポジトリ、シェルの履歴、またはコマンドの出力には決して含めないでください。

テスト、承認、および本稼働

スキルはドラフトとしてライブラリに到達し、クリエイターは以下の3つをクリアするまでそこに保留します。

チェック項目 行うこと
テストケース スキルを承認に回す前に、すべてのケースに合格する必要があります。ケースは理由を添えた場合のみ削除可能であり、その理由は承認者に表示されます。
シャドウでのドライラン スキルは過去の業務データに対して実行され(回答は誰にも表示されません)、その結果は当時人間が下した判断と比較されます。
別ファミリーのモデルによるブラインドレビュー チェック漏れ、捏造された情報源、および従うべきではないのにスキルが従ってしまった埋め込み指示がないかを探します。

その後、承認へと進みます。書き込みを行うツールを追加するスキルは、2人の担当者がパスキーで承認するまで保留され、提案者自身はその承認者にはなれません(PUBLISH_NEEDS_APPROVAL)。承認されると、まずシャドウで稼働し、次に指定されたゲートの背後にある1つの部門向けのカナリアとして稼働し、その後全員向けに本稼働します。カナリアゲートが満たされない場合、カナリアは自動的に停止し、全員が前のバージョンに留まります。早期に全員へ展開するには、理由と2人目の承認者が必要です(CANARY_GATE_NOT_MET)。

Communityエディションでは、クリエイター、ライブラリ、バージョン、およびテストがすべて揃っており、テストに合格すればオーナーが単独で公開できます。カナリア、2人による承認、プラグイン同期、および重複のマージはEnterpriseエディションに付属しています。

新規スキル · 4 公開
新規スキル · 4 公開
公開画面には、スキルが保留されている理由、誰の同意が必要か、そしてどのように本稼働に至るか(承認済み、シャドウ、指定されたゲートの背後でのカナリア、そして全員へ)が表示されます。提案者は自身の変更を承認できず、直前のバージョンはいつでも切り戻せる状態で維持されます。

スキルが表示される場所

公開された同じスキルが、5つの場所でユーザーに届きます。

  1. アシスタントは、説明、トリガー、およびクエリパターンによってリクエストをスキルと照合し、スキルの指示に従います。
  2. エージェントとワークフローは、ステップとしてスキルを呼び出します。ワークフローステップがスキルを指定し、実行記録には使用されたバージョンが記録されます。
  3. 画面上のAIボタンは、それぞれ1つのスキルを実行します。管理者は「このボタンについて」を開いて、ボタンが実行するスキル、読み取るデータ、最後に変更した人物を確認でき、スキル自体に触れることなくボタンをオフにできます。
  4. お使いのIDE(統合開発環境)とClaude Codeは、Workbenchおよび13個のMCP(Model Context Protocol)ツール(list_skills、get_skill、match_prompt、discover_skills、invoke_skill、record_execution、create_skill、import_skill、get_generation_job、sync_skills_localなど)を通じてライブラリにアクセスします。各呼び出しは、それを開始した本人として、その人物の許可リストの範囲内で実行されます。
  5. スキルライブラリ自体。ここではユーザーがスキルを閲覧、実行し、変更を提案することができ、管理者は各スキルのオーナー、ユーザー、実行回数、および支出を確認できます。

何がスキルを実行するかにかかわらず、スキルが実行者に許可されている操作の範囲を広げることはできません。実行者の許可リスト内にあるツールのみを呼び出し、その人物が開くことを許可されているものだけを読み取ります(SKILL_CANNOT_WIDEN_TOOLS)。モデルルートのない実行は推測されることなく拒否されます(SKILLS_ENGINE_BINDING_MISSING)。ディスパッチャーが組織独自のモデル設定からルートを選択します。

このボタンについて
このボタンについて
「このボタンについて」には、AIボタンが実行するスキル、読み取る3つのソース、作成者とレビュアー、および最新バージョンでの変更点が表示されます。ボタンをオフにすると、すべての場所から一度に削除されますが、スキルと過去のすべての回答はそのまま残ります。

実践例:Harrow向けのバース割り当て要約

Harrowのプランナーたちは、Harrow独自のバース計画プラグインから提供された2つの読み取り専用ツールをすでに許可リストに持っていました。berth-plan.readは指定日の計画を返し、vessel-call.readは到着ウィンドウと船長を含む寄港情報を返します。このスキルにはそれ以外何も必要ありません。書き込みを一切行わないため、2人の承認者も必要ありません。

---
name: berth-allocation-summary
description: Summarise tomorrow's berth plan at Harrow for the planning desk. Use when someone asks who is on which berth, what moved since the last plan, or where two calls clash.
allowed-tools: berth-plan.read, vessel-call.read
triggers:
  - /berth-summary
capabilities:
  - name: summarise_berth_plan
    description: The berth table, the changes since the last plan and any clashes, for one date
version: 1.0.0
visibility: team
status: draft
---

# Berth allocation summary

## When to use
A planner asks about the berth plan for a date, or asks what changed.

## Steps
1. Read the plan for the date with berth-plan.read. If no date is given, use tomorrow.
2. For each call on the plan, read it with vessel-call.read.
3. Write the berth table first: berth, vessel, arrival window, length overall.
4. Then list what moved since the previous plan, one line per change, with the reason the plan records.
5. Then list clashes: two calls whose windows overlap on one berth, or a vessel longer than the berth.
6. Cite the plan's version for every line. Never guess a time the plan doesn't give.

## Output
Three headed sections, in this order: Berths, Changes, Clashes. Write "No clashes" when there are none.

その横にあるskill.yamlは、ライブラリに表示名、カテゴリー、およびマッチャーがここへルーティングすべき言い回しを提供します。

# skill.yaml, beside SKILL.md
name: berth-allocation-summary
display_name: "Berth allocation summary"
version: "1.0.0"
status: draft
visibility: team
category: operations
tags:
  - berths
  - planning
triggers:
  - "/berth-summary"
allowed_tools:
  - berth-plan.read
  - vessel-call.read
capabilities:
  - name: "summarise_berth_plan"
    description: "Berth table, changes since the last plan and clashes, for one date"
    query_patterns:
      - "who is on which berth tomorrow"
      - "what moved on the berth plan"
      - "any berth clashes on *"

次に、リポジトリのルートから以下のコマンドを実行します。

npm run skill:validate skills/berth-allocation-summary
npm run skill:upload skills/berth-allocation-summary --dry-run
npm run skill:upload skills/berth-allocation-summary

Tomás氏はクリエイターで6つのテストケースを追加しました。通常の日、到着遅れにより2つの寄港が移動した日、実際の競合が発生した日、まだ計画がない日付、バースに対して船長が長すぎる船舶、そしてスキルに新しいバースを提案させようとするリクエスト(書き込みツールを持たないため、提案してはなりません)です。ドライランでは、過去の20件の計画をシャドウで再生しました。テストケースに合格すると、計画デスクのレビュアーが承認し、計画チーム向けに本稼働しました。現在、アシスタントは毎回同じ形式で質問に回答しており、バース計画ページにあるプランナー用のAIボタンも同じスキルを実行しています。

パート2:マニフェストスキル

マニフェストスキルは、プラグインが公開する計算処理の単位です。マニフェストのskills[]で宣言され、create-nexus-plugin validateを実行した際にSDK(ソフトウェア開発キット)によって検証され、compileRegistryによってレジストリ本体にコンパイルされて、スキルレジストリに同期されます。レジストリのSQLを手書きすることは決してないため、プラットフォームがディスパッチする行と宣言したディスクリプタが食い違うことはありません。

すべてのマニフェストスキルには、id、displayName、description、tier、classification、inputSchema、およびoutputSchemaが必要です。timeoutMsも宣言してください。これは1,000から21,600,000(1秒から6時間)までの整数であり、この範囲外の値はTIMEOUT_OUT_OF_BOUNDSで拒否されます。dataResidencyはany、eu、またはusであり、デフォルトはanyです。

idはスネークケース(小文字)であり、レジストリのディスパッチキーは名前空間付きのジョブタイプ<plugin name>.<skill id>となるため、2つのプラグインが競合することなく両方ともsummariseスキルを持つことができます。以下は、テンプレートの1つのスキルを簡略化したものです。

{
  "id": "sentiment_score",
  "displayName": "Sentiment score",
  "description": "Deterministic lexicon-based sentiment score for a piece of text.",
  "tier": "host_callback",
  "classification": "tenant",
  "dataResidency": "any",
  "inputSchema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 } }, "required": ["text"] },
  "outputSchema": { "type": "object", "properties": { "score": { "type": "number" } }, "required": ["score"] },
  "hostCallback": {
    "service": "my-plugin",
    "port": 8080,
    "path": "/internal/skills/sentiment_score",
    "maxRequestBytes": 262144,
    "maxResponseBytes": 16384,
    "tenantHeader": "X-Organization-ID"
  },
  "timeoutMs": 10000
}

5つのティア

ティアは単なるラベルではありません。各ティアには固有のフィールドがあり、別のティアに属するフィールドは黙って無視されるのではなく、FIELD_NOT_FOR_TIERで拒否されます。

ティア 必須項目 モデルへの到達 実行主体
host_callback hostCallback: 自身のService、そのポート、パス、および両方のバイト上限 なし プラットフォームが自身の名前空間内にある自身のServiceに入力をPOSTします
plugin_queue queueName(表記は<plugin name>.<name>) なし 自身のキューからプルする自身のワーカー
tool_using systemPromptおよびtools[]。信頼レベルはcoreまたはverified はい AI Provider Routerを介したプラットフォーム。各ツール呼び出しは許可リストに登録されたエグゼキューターを通じて実行されます
llm_only systemPrompt。信頼レベルはcoreまたはverified はい プラットフォーム(AI Provider Routerを介した1回の呼び出し)
map map.perItemJobType(マップではない、同じマニフェストの別のスキルを指定) ターゲット経由のみ プラットフォームがアイテムごとに1回ターゲットを実行し、結果を収集します

どちらのモデルティアも、プロバイダーやモデルを指定しません。ルーターがディスパッチ元の組織独自のプールから両方を選択します。tool_usingスキル内のツールは、6つのエグゼキューター(自身のServiceであるstanding_service_call、graphrag、graphrag_query、graphrag_search、h3、またはweb_search)のうちの1つを指定します。それ以外はすべてEXECUTOR_NOT_PERMITTEDで拒否されます。3つのナレッジグラフ・エグゼキューターは、ツール名としてgraphrag_queryとgraphrag_searchのみを受け入れます。これは、エグゼキューターがツールの名前にちなんだ操作を実行するためです。

レジストリには、プラグインが宣言できない2つのティアが存在します。チェーンと単独で実行されるスキルは、プラットフォームによってのみ記述されます。これらを指定した同期は全体が拒否されます。

どのティアを使用すべきか

  • 処理が自身のコードで計算する入力の関数(スコア、計算、自身のスキーマ内のルックアップなど)である場合はhost_callbackを使用します。テストが最も簡単であり、テンプレートのデフォルトです。コールバックルートを保護してください。マニフェスト内のパスはシークレットではないため、ルートはプラットフォームからの呼び出しを検証し、組織情報をリクエストボディからではなくその呼び出しから取得する必要があります。これをauth: internalとして宣言し、そこにrequireService(Fastify)またはserviceMiddleware(Express)をマウントしてください。ガードは他の誰かのために発行されたトークンを拒否します。迅速に応答し、同じジョブの2回目の配信が無害になるようにしてください。
  • 人間が完了を待つような長時間の処理であり、自身のワーカーがライフサイクルを所有する場合はplugin_queueを使用します。ワーカーは開始時に実行ステータスをrunningに移行し、終了時に終了ステータスに移行する必要があります。結果だけをPOSTするワーカーは、実行ステータスを永久にqueuedのままにしてしまいます。
  • 固定のシステムプロンプトを使用した1回のモデル呼び出しでジョブが完了し、かつプラグインがcoreまたはverifiedである場合はllm_onlyを使用します。
  • モデルがループ内でツールを呼び出す必要があり、かつ同じくcoreまたはverifiedである場合はtool_usingを使用します。
  • プラットフォームに自身の別のスキルをリスト全体にファンアウトさせたい場合はmapを使用します。

Corrán Orbitalにおける私の軌道伝播スキルはhost_callbackです。当社のプラグインはcommunityであるため、モデルティアは最初から選択肢になく、それで困ることもありません。火曜日に異なる答えを出すような軌道伝播プログラムは、役に立たないどころか有害だからです。

毎回の実行前の承認

マシンの判断だけでは決して実行してはならないマニフェストスキルは、その旨を宣言します。

"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }

requiredは常にtrueです。承認が不要なスキルはこのブロックを省略します。reasonは承認者に表示される内容であり、トリミング後の文字数が1〜500文字である必要があります。それ以外の形式はAPPROVAL_INVALIDで拒否されます。これにより、スキルのディスパッチは保留されます。ディスパッチはstatus: "awaiting_approval"とwaitpointIdを伴う202を返し、指定された人物の承認によってのみ1回限り解放されます。保留されるスキルのバッチ、マップ、またはチェーンディスパッチは、ファンアウトがアイテムを保留できないため、SKILL_APPROVAL_NOT_HOLDABLEで拒否されます。保留されたという応答を描画し、承認者に判断を委ねてください。ディスパッチしてから同意を求めるようなことはしないでください。

レジストリへの同期

すべての同期は宣言的であり、全体がチェックされます。毎回完全なスキルセットを送信してください。除外したスキルは無効化されますが、その実行履歴は残ります。1つでも不正なスキルがあると、すべての違反がまとめてリストアップされた状態で同期全体がSYNC_CONTRACT_VIOLATIONで拒否され、何も書き込まれないため、プラグインが中途半端に更新されることはありません。同期の呼び出しと、どのプラグインが呼び出しているかをプラットフォームがどのように認識するかについては、第2.22章「プラグインランタイム」で解説しています。

IDEおよびClaude Code内のスキル
IDEとClaude Code内のスキル
「IDEおよびClaude Code内のスキル」では、開発者自身のターミナルから行う同じ検証、アップロード、および公開のステップが示されており、作成者は自身の変更を承認できないため、ドラフトが承認待ちとして保留されています。

2種類の選択

ジョブが「毎回同じ方法でこれを伝える」ことであれば、それはSkills Engineのスキルです。ジョブが「私のコードを実行してその答えを返す」ことであれば、それはマニフェストスキルです。実際の業務のほとんどは、最終的にその両方になります。Harrowのバース要約は、プラグインから提供されるツールを使用するSkills Engineのスキルであり、プラグインのツール自体はそのマニフェスト内で宣言されています。2つのうち変更コストが低いのはSkills Engineのスキルであるため、文言や判断はそちらに置き、算術計算はプラグイン側に置くのが賢明です。

いずれにせよ、相応のコストはかかります。Skills Engineのスキルは、SKILL.mdがうまく書けた時点で完成ではありません。テストケースに合格し、ドライランが人間の判断と一致し、あなた以外の誰かが承認した時点で完成となります。書き込みを行うスキルの場合は、1週間を見込んでおいてください。その大部分はカナリアテストに費やされます。