🛡️ 技術調査 - Vercel skills.sh API

検証日: 2026-06-07 / 対象: Vercel skills.sh API (API 公開 2026-06-05)

概要

skills.sh は、Agent Skills の索引・検索・監査・インストールを一体化したスキル流通基盤です。GitHub 上に散在する SKILL.md ファイルをクロールして索引化し、検索 API・監査 API・CLI インストーラ (npx skills) を通じてエージェントへ届けます。2026-06-05 付の Vercel Changelog で API が公開されるまで、スキルの流通は「GitHub リポジトリを手で探してコピーする」方式に留まっていました。

skills.sh API は、スキルを「信頼・監査・認証が必要な部品」として扱う初期の実用 API です。これまで npm・Docker Hub・MCP Registry に相当する流通インフラが Agent Skills には乏しく、エージェントがプログラムでスキルを検索・評価・取得する公開 API はほとんどありませんでした。skills.sh API はそのパスを公開 API として整備しました。

数値の取り違え注意: API changelog の「more than 600,000」は登録総数、セキュリティ監査 changelog の「over 60,000」は監査済み数で、別の数字です。元ニュースの「60万以上をAPI検索」は登録総数を指します。

本ドキュメントの主眼

API の機能紹介に留めず、「スキルを流通させるとき何を信頼し、何を監査し、どう権限を切るか」という設計問題を、skills.sh API という具体例を土台に整理します。結論を先に置くと、skills.sh API は重要な一歩ですが、その監査は初回インストール時にトリガーされる静的スキャンに留まり (署名/provenance/ランタイム隔離なし)、pass は安全を意味しません。社内スキルカタログを作るなら、skills.sh の API モデルを参考にしつつ、出所証明・公開前監査・ランタイム隔離の 3 層で補強し、「巨大レジストリ全文検索」より curated + version pinning を優先すべきです。

特徴

• 集権的ストレージを持たないディレクトリ型: スキルの実体は GitHub 上の Git リポジトリに置かれたままで、skills.sh はメタデータ索引のみを管理します。npm のようにアーティファクトを保管しません。
• Fuzzy / Semantic 二段階検索: 単一語はファジーマッチ、複数語はセマンティック検索に自動で切り替え、意図に近いスキルを発見しやすくします。
• 複数社連携によるセキュリティ監査: skills.sh API docs では Gen Agent Trust Hub・Socket・Snyk・Runlayer・ZeroLeaks の 5 社が監査パートナーとして挙がります (監査機能を告知した Vercel Changelog 本文では Gen・Socket・Snyk の 3 社のみ言及)。監査はスキルが初回インストールされた時点で自動的にトリガーされ (publish 時ではない。未インストールのスキルは監査エンドポイントが 404 を返す)、status (pass/warn/fail) と riskLevel (NONE-CRITICAL) を API から参照できます。悪性と判定されたスキルはリーダーボードと検索結果から自動非表示になります。
• Vercel OIDC 短命 JWT 認証: 長期 API キーの代わりに team+project スコープの短命 JWT (TTL 60 分) を使用します。漏洩時の有効窓を最小化し、自動ローテーションで管理コストを下げます。
• 監査カバー率は約 8.7%: 登録約 688,875 件のうち監査済みは約 60,000 件に留まります。pass は安全の保証ではなく、Trail of Bits はスキャナへのバイパスを実証しています。
• install 数によるリーダーボード: 人気スキルの発見性を高める一方、hype-driven な増加 (約 20 日で 18.5 倍) と重複約 46.3% [二次情報: HuggingFace 40,000+ スキル調査] という質のばらつきも伴います。
• 公式キュレーション (/curated): owner 単位でグループ化した少数の厳選スキルを、検索結果とは独立して参照できます。
• Vercel 前提のロックイン: OIDC 短命 JWT は Vercel ビルド/Functions 環境でしか自動発行されません。非 Vercel 環境では長期 access token へのフォールバックが必要です。
• Beta / 実験プロジェクト扱い: skills.sh は Vercel Labs のプロジェクトで SLA 対象外、料金体系は現時点で未開示です。

関連技術との関係

Anthropic は 2025-10-16 に Agent Skills を発表しました。SKILL.md は YAML frontmatter + 命令本文 + 同梱リソースの 3 層構造を持ち、Progressive Disclosure (段階的ロード) で汎用エージェントを専門エージェントへ変えます。skills.sh はこの SKILL.md を発見・配布しやすくする流通インフラであり、仕様の定義は Anthropic 側にあります。

類似レジストリとの比較

規模は登録スキル数。行頭「約」+ 取得日付き=一次実測、[二次情報] 明記=二次ソース。

構造

C4 model の 3 段階で、skills.sh の内部アーキテクチャを図解します。

システムコンテキスト図

コンテナ図

コンポーネント図

クローラ - 索引のコンポーネント

検索 API のコンポーネント

監査パイプラインのコンポーネント

認証ゲートウェイのコンポーネント

データ

概念モデル

エンティティ間の所有関係を subgraph で、利用関係を矢印で示します。

情報モデル

API レスポンスの実フィールドを基に主要属性を整理します。推測属性には (推測) を注記します。

エンティティ補足

構築方法

前提条件

OIDC トークン取得のセットアップ

skills.sh API は Bearer 認証が必須です。Vercel 環境では OIDC 短命トークンを使え、長期 API キーを環境変数に置く代わりに team + project にスコープされた JWT を発行します (非 Vercel 環境では後述の長期 access token にフォールバックします)。

1. OIDC を有効化: Vercel ダッシュボードの Project → Settings → Security → "Secure backend access with OIDC federation" をオンにします。Issuer mode は Team モード (推奨) と Global モードがあり、Team モードではチーム固有の issuer URL (https://oidc.vercel.com/<team-slug>) が使われます。
2. ヘルパーパッケージのインストール:

npm install @vercel/oidc

3. ローカル環境を紐付ける:

vercel link
vercel env pull   # .env.local に VERCEL_OIDC_TOKEN を書き出す

OIDC トークンの性質 (公式確認値)

TTL 60 分は Vercel docs /oidc で一次確認済みです。sub/aud クレームの具体フォーマットは公式ページ本文に明示がなく公式未確認です。

利用方法

必須パラメータ一覧

リーダーボード

curl "https://skills.sh/api/v1/skills?view=trending&per_page=10" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

view は all-time / trending / hot。hot ビューでは installsYesterday と change (前日差分) が追加されます。

{
  "data": [
    {
      "id": "vercel-labs/skills/find-skills",
      "slug": "find-skills",
      "name": "find-skills",
      "source": "vercel-labs/skills",
      "installs": 24531,
      "sourceType": "github",
      "installUrl": "https://github.com/vercel-labs/skills",
      "url": "https://skills.sh/vercel-labs/skills/find-skills"
    }
  ],
  "pagination": { "page": 0, "perPage": 10, "total": 8420, "hasMore": true }
}

スキル検索

curl "https://skills.sh/api/v1/skills/search?q=react%20native&limit=5" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

単一語はファジー、複数語はセマンティック検索が適用されます。レスポンスには searchType ("fuzzy" / "semantic") と durationMs が含まれます。

公式キュレーション

curl "https://skills.sh/api/v1/skills/curated" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

owner ごとにグルーピングされ、totalOwners / totalSkills / generatedAt が付きます。

スキル詳細とファイル内容

curl "https://skills.sh/api/v1/skills/vercel-labs/skills/find-skills" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

hash (SHA-256、snapshot 無しは null) と files (path/contents の配列、同) を含みます。well-known 由来は /api/v1/skills/mintlify.com/mintlify のようなパス形式になります。

セキュリティ監査結果

curl "https://skills.sh/api/v1/skills/audit/vercel-labs/skills/find-skills" \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN"

{
  "id": "vercel-labs/skills/find-skills",
  "source": "vercel-labs/skills",
  "slug": "find-skills",
  "audits": [
    {
      "provider": "Gen Agent Trust Hub",
      "slug": "agent-trust-hub",
      "status": "pass",
      "summary": "No risks detected",
      "auditedAt": "2026-04-15T12:00:00.000Z",
      "riskLevel": "LOW"
    }
  ]
}

status は pass/warn/fail、riskLevel は NONE/LOW/MEDIUM/HIGH/CRITICAL。初回インストール前など監査未実施の場合は 404 です。

TypeScript からの利用

@vercel/oidc の getVercelOidcToken() でトークンを取得し、Authorization: Bearer に付与します。

import { getVercelOidcToken } from '@vercel/oidc';

const token = await getVercelOidcToken();
const res = await fetch('https://skills.sh/api/v1/skills?per_page=10', {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

// 実装案: 検索ユーティリティの最小実装例
import { getVercelOidcToken } from '@vercel/oidc';

async function searchSkills(query: string, limit = 10) {
  if (query.length < 2) throw new Error('q は 2 文字以上が必要です');
  const token = await getVercelOidcToken();
  const url = new URL('https://skills.sh/api/v1/skills/search');
  url.searchParams.set('q', query);
  url.searchParams.set('limit', String(limit));
  const res = await fetch(url.toString(), {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${res.status}: ${err.message}`);
  }
  return res.json();
}

実装案: 実用途ではレート制限ヘッダ (X-RateLimit-Remaining) の確認を追加することを推奨します。

CLI からのインストール

npx skills add vercel-labs/agent-skills
npx skills add vercel-labs/skills

skills@1.4.0 以降では、インストール前にセキュリティ監査結果とリスクレベルが表示されます。

エラーレスポンス

{ "error": "error_code", "message": "Human-readable description." }

運用

レート制限への対応

team/project 単位で 600 RPM の上限があり、全レスポンスに X-RateLimit-* ヘッダが付きます。

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 423
X-RateLimit-Reset: 1749294060

• X-RateLimit-Remaining が 0 に近づいたら X-RateLimit-Reset まで待機するバックオフを組み込みます。
• 検索は残量を消費しやすいため、ユーザー入力のデバウンス (300〜500ms) と limit の絞り込みを併用します。
• CI で監査ステータスを一括取得する場合は、一覧を事前保持し差分のみ問い合わせるキャッシュ層を挟みます。
• 429 を受けたら Retry-After 後に 1 回だけリトライし、再度 429 なら上位へ伝播します。無限リトライは枯渇を加速します。

トークン更新運用

「長期キーを置かない」というメリットは Vercel ビルド/Functions 上でのみ成立します。非 Vercel 環境では OIDC が使えず、長期 access token を環境変数に保管する従来運用に後退します。

監査ステータスの継続監視

監査は初回インストール時にトリガーされる静的スキャンであり (publish 時ではないため、未インストールのスキルは監査結果を持たず 404 になります)、インストール後に新たな脅威が追加されても再スキャンは保証されません。

• 利用中スキルの監査エンドポイントを定期的に呼び、status と riskLevel の変化を検知します。
• malicious 判定スキルは leaderboard / 検索から自動非表示になりますが、直接 URL でアクセスすれば警告付きでインストール可能なため、社内では riskLevel: CRITICAL を受け取った時点で自動的に利用禁止扱いにします。
• 監査エンドポイントが 404 を返すスキルは未監査 (登録総数の約 8.7% のみ監査済み) と判定し、社内利用前に個別レビューを義務付けます。

CI での OIDC トークン取得とフォールバック

- name: Run skill audit check
  env:
    SKILLS_SH_TOKEN: ${{ secrets.SKILLS_SH_ACCESS_TOKEN }}  # 長期 access token
  run: |
    curl -sf \
      -H "Authorization: Bearer $SKILLS_SH_TOKEN" \
      "https://skills.sh/api/v1/skills/audit/anthropics/skills/computer-use" \
      | jq '.audits[0].status'

非 Vercel CI では長期 access token を Secrets に保管し、ローテーション運用 (最低 90 日ごと) を定めます。

ベストプラクティス

社内スキルカタログの 3 層信頼モデル

skills.sh が現状カバーするのは②の一部 (初回インストール時にトリガーされる静的スキャン) のみで、①③は自組織で補う必要があります。

• ① 出所証明: スキルリポジトリに sigstore / GitHub OIDC による署名を導入し、どのコミット SHA から生成されたかを attestation として記録します。skills.sh は署名/provenance を提供しません。ただし Airia が指摘するとおり「Signing tells you who, not what」で、署名は発行者の身元を確認するだけで実行時の安全性を保証しません。署名単独を信頼の根拠にしません。
• ② 公開前監査: 内部レジストリへの取り込み前に監査エンドポイントで status: pass かつ riskLevel が NONE/LOW であることを確認します。ただし pass は安全を意味しません。Trail of Bits は汚染した .pyc、.docx 埋め込み、LLM スキャナへのプロンプトインジェクションで 3 スキャナ全てのバイパスを実証しています。SHA-256 hash による version pinning を必ず実施し、ハッシュが変わったら再審査します。
• ③ ランタイム隔離 (最重要): allowed-tools フロントマターは権限境界として信頼できません。Claude Code CLI 直叩き時のみサポートされ SDK 非対応で、かつ「parse されるが enforce されない」既知の制約があります (anthropics/claude-code Issue #37683、closed / not_planned、2026-04-24。修正は計画されていない)。実効的な制限は SDK の allowedTools + permissionMode か、OS / コンテナ層での分離 (ネットワーク egress 制限・ファイルシステム制限) で行います。

SKILL="anthropics/skills/computer-use"
RESULT=$(curl -sf \
  -H "Authorization: Bearer $VERCEL_OIDC_TOKEN" \
  "https://skills.sh/api/v1/skills/audit/${SKILL}")
STATUS=$(echo "$RESULT" | jq -r '.audits[0].status')
RISK=$(echo "$RESULT" | jq -r '.audits[0].riskLevel')
if [ "$STATUS" != "pass" ] || [ "$RISK" = "CRITICAL" ] || [ "$RISK" = "HIGH" ]; then
  echo "BLOCKED: status=$STATUS riskLevel=$RISK"
  exit 1
fi

curated 少数優先 vs 巨大レジストリ全文検索

HuggingFace のコミュニティ調査 (40,000+ スキル、二次情報・LLM 判定ベースの推計) では、登録スキルの 46.3% が重複または near-duplicate、9% が Critical Risk と報告されています。20 日で 18.5 倍という hype-driven な急増で「discovery tax」が発生し、ベスト実装が埋没します。

• skills.sh の 68 万件検索は外部スキルの初回発見にのみ使い、発見したスキルは必ず個別レビューを経てから社内カタログへ登録します。
• 社内カタログは 30〜50 件程度の審査済み curated リストから出発し、需要が生じた場合に追加審査して拡張します。
• 公式キュレーション (/curated) を定期チェックし、Anthropic / Vercel が推奨するスキルを優先評価します。

監査メタデータ設計

トラブルシューティング

まとめ

skills.sh API は、Agent Skills を「検索・監査・短命認証・レート制限を備えた部品」として扱える最初の実用 API です。ただし監査は初回インストール時にトリガーされる静的スキャンに留まり (署名/provenance/ランタイム隔離なし、pass は安全を意味しない) ため、社内スキルカタログを作るなら API モデルを参考にしつつ、出所証明・公開前監査・ランタイム隔離の 3 層と version pinning で補強し、巨大レジストリ全文検索より curated 少数優先で運用するのが現実的です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

一次 (Vercel / skills.sh 公式)

• Vercel Changelog: The skills.sh API is now available (2026-06-05)
• Vercel Changelog: Automated security audits for skills.sh
• Vercel Changelog: Introducing skills, the open agent skills ecosystem (2026-01-20)
• skills.sh API Reference
• skills.sh docs
• Vercel docs: OpenID Connect (OIDC) Federation
• @vercel/oidc npm
• vercel-labs/skills GitHub

Agent Skills 仕様 (Anthropic)

• Anthropic Engineering: Equipping agents for the real world with Agent Skills
• anthropics/skills GitHub

監査パートナー

• Socket: Supply Chain Security to skills.sh
• Snyk: Securing the Agent Skill Ecosystem
• skillaudit.sh checks

反証・限界 (研究・批判)

• Trail of Bits: The sorry state of skill distribution (2026-06-03)
• Snyk: ToxicSkills (3,984 スキル分析)
• HuggingFace: The Wild West of Agent Skills (40,000+ スキル監査)
• anthropics/claude-code Issue #37683 (allowed-tools not enforced, closed/not_planned 2026-04-24)
• Airia: Skills are the new supply chain (2026-05-04)

関連 / 比較

• MCP Registry
• Google Cloud: Announcing Google's Official Skills Repository
• Agensi: Best AI Agent Skills Marketplaces 2026

注: 本調査で skills.sh / Agent Skills レジストリに紐づく CVE 番号は NVD/MITRE/ベンダー advisory のいずれでも実在確認できなかったため記載していません (skills.sh に固有でない Claude Code / MCP 側の個別 CVE は本調査のスコープ外)。セキュリティ上の問題は研究レポート (Snyk / Trail of Bits / HuggingFace、いずれもベンダー/コミュニティの自己申告値) と設計上の限界として扱いました。