multica-skill-importing

Multica へのスキルのインポート

このスキルは、ユーザーがスキルの URL、スキル、または現在の Multica ワークスペースへ特定のスキルをインポートする明確な意図を提供した場合に使用します。

ユーザーが必要としているスキルを判断するためにこのスキルを使用しないでください。ユーザーが機能を説明し、スキルが不明な場合は、外部検索で候補 URL を生成できますが、URL または具体的なインポートが判明するまでインポートスキルは開始されません。

以下のすべての記述は references/skill-importing.md のソースに基づいています。疑わしい場合はそちらを参照してください。

スキル

スキルが Multica にインストールされるのは、それが現在のワークスペースに存在する場合のみです。それを配置する唯一の方法はインポートエンドポイントです。これは、次の CLI によって駆動される、アップロードされたローカルアーカイブ（.skill / .zip）のいずれかを受け付けます。

multica skill import --url <url> --output json              # hosted source
multica skill import --file <path-to.skill> --output json   # local archive

CLI のデフォルトは --on-conflict fail です。URL インポートでは次を送信します。

POST /api/skills/import
Content-Type: application/json
body: { "url": "<url>", "on_conflict": "fail" }

--file インポートは同じルートに multipart/form-data として、file パート（.skill / .zip のバイト列）と on_conflict フィールドを付けてアクセスします。--url と --file は相互に排他的であり、いずれか一方のみが必須です。

npx skills add で終わらせないでください。それは外部/ローカルのスキル環境にインストールするのであり、Multica ワークスペース DB ではないため、Multica はそれを管理またはバインドできません。

サポートされている URL ソースファミリー

detectImportSource はこれら（および www. のバリアント）を受け付けます。次のいずれかの形式を multica skill import --url <url> --output json に渡してください。

multica skill import --url clawhub.ai/owner/skill --output json
multica skill import --url skills.sh/owner/repo/skill --output json
multica skill import --url github.com/owner/repo --output json
multica skill import --url github.com/owner/repo/tree/main/path/to/skill --output json
multica skill import --url github.com/owner/repo/blob/main/path/to/SKILL.md --output json

• clawhub.ai、skills.sh、github.com が認識されるホストです。
• GitHub URL は、ベアの owner/repo、/tree/{ref}/... ディレクトリ、または /blob/{ref}/.../SKILL.md ファイルのいずれかです。
• ベアの ClawHub スラッグ（ホストなし）も受け付けられ、ClawHub にルーティングされます。
• その他のホストは、サポートされているソースを示す 400 で拒否されます。

ローカルアーカイブのインポート（.skill / .zip）

multica skill import --file <path> --output json は、ホストされた URL の代わりにローカルアーカイブからスキルをインポートします。.skill ファイルは標準の zip であり、Anthropic の skill-creator の package_skill が生成する形式です。スキルフォルダーの通常の .zip も同様に機能します。サーバーは次のように動作します。

• 同じ POST /api/skills/import ルートで、アップロードを multipart/form-data（file パートと任意の on_conflict フィールド）として受け付けます。
• それを展開し、最も浅い SKILL.md をルートとするため、ルートレベルの SKILL.md とネストされた my-skill/SKILL.md ラッパーレイアウトの両方が受け付けられます。
• 名前/説明は SKILL.md のフロントマターから取得し、フォールバックとしてラッパーディレクトリ名、次にアップロードされたファイル名を使用します。
• サポートファイルを保持します — SKILL.md、ドットファイル、__MACOSX、ライセンスファイル、バイナリアセットは除外します — URL インポートと同じ、ファイルごと（1 MiB）、バンドルごと（8 MiB）、ファイル数（256）の上限の下で、パストラバーサル（zip-slip）を拒否します。
• URL インポートと同じ構造化結果エンベロープを返し、同じ --on-conflict 戦略に従います。

アップロード自体は 16 MiB（圧縮）に制限されています。ローカルアーカイブでないソースは、引き続き --url を経由します。

ダイレクト URL フロー

1. リクエストに具体的な URL が含まれている場合、インポートエンドポイントを直接呼び出すことができます。API では検索は必須ではありません。

multica skill import --url <url> --output json

2. レスポンスを信頼できる情報源として扱ってください。現在の CLI インポートは、構造化されたインポート結果のエンベロープを使用します。

{
  "status": "created|updated|conflict|skipped|failed",
  "reason": "...",
  "skill": { "...": "SkillWithFilesResponse when created/updated" },
  "existing_skill": { "id": "...", "name": "...", "can_overwrite": true }
}

created / updated の場合、skill はワークスペースの SkillWithFilesResponse です。これは標準の SkillResponse を内包し、補助的な files 配列を追加します。関連するフィールドを報告してください。

• 存在する場合は status と reason。
• skill.id / skill.name / skill.description。
• skill.config.origin（プロベナンス: そのスキルがどのソースからインポートされたか — ソースが origin を提供した場合にのみ設定されるため、存在しない可能性があるものとして扱ってください）。
• skill.files / ファイル数。
• skill.created_at / skill.updated_at。
• 既存のスキルが原因でステータスが conflict、skipped、または failed の場合の existing_skill.id / existing_skill.name。

レスポンスは構造化されているため、インポートが成功したかどうかを推測するのではなく、これらの返されたフィールドを読み取ってください。

3. エージェントとスキルのバインドは、別個の可変操作です。add は既存の割り当てを保持し、新しい id を追加します。

multica agent skills add <agent-id> --skill-ids <skill-id> --output json
multica agent skills list <agent-id> --output json

最後の multica agent skills list <agent-id> --output json の後、そのスキルがそのエージェントで利用可能であると主張する前に、対象のスキル id が存在することを確認してください。

追加型の add と全置換型の set

multica agent skills add は追加型です。サーバーは既存の割り当てをクリアせずに割り当てを挿入します（AddAgentSkills）。

multica agent skills set は全置換型です。サーバーは現在のすべての割り当てをクリアしてから、渡された id だけを正確に再追加します（SetAgentSkills）。set は置換用のパスです。set に 1 つの id だけを渡すと、エージェントにはその 1 つのスキルだけが残り、以前の割り当てはすべて削除されます。

予約済みの SKILL.md 補助ファイル

スキルの主要なコンテンツは SKILL.md です。このファイル名は予約されています。デーモンは実行環境を準備する際に主要なコンテンツを SKILL.md 自体に書き込むため、補助 ファイルも SKILL.md という名前にはできません（IsReservedContentPath。このチェックはパスをクリーンし、大文字と小文字を区別しないため、./SKILL.md や sub/../SKILL.md も検出されます）。

スキルをインポートまたは作成する際の実際の影響: マニフェストに SKILL.md という名前の補助ファイルが記載されている場合、サーバーはそれを黙って破棄します — インポートは依然として成功しますが、そのエントリは返される files に含まれません。したがって、期待していた補助ファイルが存在しない場合は、それが SKILL.md という名前だったかどうかを確認してください。予約されていないパスに名前を変更してください。（ハードな 400 拒否 — 「SKILL.md is reserved for the primary skill content」 — は、専用の単一ファイルエンドポイント PUT /api/skills/{id}/files でのみ発生し、インポート時には発生しません。）

同名の競合: --on-conflict

デフォルトの動作は安全です。multica skill import --url <url> は --on-conflict fail と同等です。インポートするスキル名がすでに存在する場合、コマンドは 構造化された conflict 結果を出力し、非ゼロで終了します。スキルは作成も 更新もされません。

明示的な戦略を選ぶのは、ユーザーがそれを求めた場合、または意図が 明確な場合だけにしてください:

• --on-conflict fail (デフォルト): 競合時には何もせず、上書きまたは名前変更を 示唆する理由とともに status: conflict を報告します。
• --on-conflict overwrite: 既存の同名スキルをその場で更新しますが、 現在のユーザーがそのスキルの元の作成者である場合に限ります。これにより スキル ID、created_by、created_at、およびエージェントとスキルのバインディングが保持されます。代わりに 説明、コンテンツ、provenance 設定、およびサポートファイルが置き換えられます。作成者でない場合は status: failed になります。
• --on-conflict rename: -2 / -3 などの自動サフィックスを付けて新しいスキルを 作成します。既存のスキルはそのままです。
• --on-conflict skip: 既存のスキルをそのままにして status: skipped を報告します。

具体的な例:

# Safe default. Fails with status=conflict if review-helper already exists.
multica skill import --url https://skills.sh/acme/repo/review-helper --output json

# Replace the existing same-name skill, preserving its ID and agent bindings.
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite --output json

# Keep the existing skill and import a copy such as review-helper-2.
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename --output json

# Batch-friendly behavior: leave the existing skill alone and mark it skipped.
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip --output json

レガシー互換性: on_conflict を送信しないクライアントは古い 契約を維持します。重複インポートは 409 を返し、ボディには既存の ワークスペーススキルの識別情報が含まれます:

{
  "error": "a skill with this name already exists",
  "existing_skill": {
    "id": "<skill-id>",
    "name": "<skill-name>"
  }
}

現在の CLI はそのレガシーな形式を status: conflict に正規化し、デフォルトの fail 戦略では 非ゼロで終了します。existing_skill.id と existing_skill.name を信頼できる情報源として扱い、必要に応じて詳細を取得してください:

multica skill get <skill-id> --output json

古いサーバーは、existing_skill キーがなく、a skill with this name already exists のような文字列だけをボディに含む 409 を返すことがあります。その場合は、 既存のワークスペーススキルを自分で見つけて復旧してください:

multica skill list --output json
multica skill get <skill-id> --output json

その後、スキルがすでに存在することを報告し、その id / name を含めてください。ループで 再試行しないでください。また、競合を避けるためだけに別の名前で 2 つ目のスキルを 作成しないでください。

すでにインポート済みのスキルを更新する: multica skill refresh

ワークスペースにすでにあるスキルの最新バージョンを取得することが目的の場合は、 インポート URL を再入力するよりも refresh を優先してください:

multica skill refresh <skill-id> --output json

これは POST /api/skills/{id}/refresh (空のボディ) を送信します。サーバーは、スキルの config.origin (github、skills_sh、または clawhub とその source_url) に保存された provenance から バンドルを再ダウンロードし、スキルをその場で上書きします:

• 保持されるもの: スキル ID、created_by、created_at、エージェントとスキルのバインディング、および ラベル — エージェントはスキルを再追加することなく維持します。
• 置き換えられるもの: 名前 (上流での名前変更が採用されます)、説明、SKILL.md コンテンツ、provenance 設定、およびサポートファイル一式。
• 権限: スキルの作成者、またはワークスペースの owner/admin — これは import --on-conflict overwrite よりも広範で、そちらは作成者限定のままです。

成功時のレスポンスは、インポート結果のエンベロープではなく、通常の SkillWithFilesResponse (multica skill get --with-content と同じ形式) です。ループで再試行する代わりに 報告すべき失敗モード:

• 422: スキルに更新可能な provenance がありません (手動で作成、ローカルアーカイブから インポート、またはローカルランタイムからコピー)。代わりに再インポートしてください。
• 409: 上流でスキルの名前が変更され、別のワークスペーススキルがすでに その名前を使用しています。何も変更されていません。
• 403: 呼び出し元が作成者でもワークスペース管理者でもありません。
• 502 / 503 / 504 / 413: 上流の取得に失敗しました (削除済み、利用不可、 タイムアウト、またはインポート上限を超過)。スキルはそのままです。

スキルを読み戻す：デフォルトではメタデータ

multica skill get と multica skill files list はメタデータのみを返します — ファイルごとのパス、バイトサイズ、コンテンツハッシュ、および SKILL.md 本文のサイズとハッシュです。これは上記の競合と検証の手順に必要なものであり、大きなスキルをそもそも検査可能に保つものです。すべての本文をインライン化すると、約 600KB のスキルを低速な回線で取得することが不可能になっていました（GH #7498）。

multica skill get <skill-id> --output json                  # metadata
multica skill get <skill-id> --with-content --output json   # bodies inlined
multica skill files list <skill-id>                         # paths and sizes

--with-content は、実際にコンテンツを読む場合にのみ使用してください。スキルがなぜ大きいのかを調べるには、デフォルトの出力ですでに答えが得られます。size 列がそのファイルを示しています。

誤り → 正しい

誤り（Multica をバイパスしています）：

npx skills add https://skills.sh/owner/repo/skill

スキルはローカルに存在するかもしれませんが、Multica はそれをワークスペーススキルとして管理できません。

通常の追加における誤ったエージェントバインディング（既存のすべての割り当てを置き換えます）：

新しいスキル ID のみを指定して set を使用すると、エージェントの他のスキルが消去されます。追加には add を使用してください。

正しいインポート：

multica skill import --url https://skills.sh/owner/repo/skill --output json

インポート後のエージェントバインディング。呼び出し元がそのエージェントのスキル割り当てを意図的に変更したい場合：

multica agent skills add <agent-id> --skill-ids <skill-id> --output json
multica agent skills list <agent-id> --output json

参考文献

• references/skill-importing-source-map.md — 上記のすべての動作を server/ 内の file:line に対応付け、さらにその行を再導出するための検証コマンドを示します。