スキルマイニング:3,500の候補から466の能力へ

3,500スキル問題

エージェントオーケストレーションシステムの構築を始めたとき、私たちは興味深い課題に直面しました。AIエコシステム全体に、何千もの潜在的なスキルが散らばっているのです。GitHubのリポジトリ、ベンダーのドキュメント、コミュニティのプロジェクト、社内のパターン ―― スキルはあらゆる場所に存在します。しかしどれが重要なのか? どれが機能するのか? そして、エージェントが実際に使える一貫性のあるスキルライブラリを、どうやって維持すればいいのか?

私たちの答えは、体系的なマイニングと取り込みのループです。

今日の数字

Anthropicが2025年10月16日にAgent Skillsをローンチしてから3か月あまり。この記事が公開された2026年1月27日時点での、私たちの立ち位置は次の通りです:

指標	数
識別された候補	3,500以上
採用したスキル	466
ベンダースキル	373
社内スキル	93
アクティブなベンダー	25以上
スキルあたりの平均トークン数	2,834
参照されているツール	89
ユニークなタグ	635

私たちは3,500件を超えるスキル候補をレビューしてきました。そして466個を採用しました。採用率にして13% ―― この選別の厳しさは意図的なものです。

ナレッジティアシステム

すべてのスキルが平等に作られているわけではありません。私たちはそれらを、それぞれ異なる適用範囲を表す5つのナレッジレイヤー(K0〜K4)に整理しています:

K0:基盤(普遍的)

すべてのエージェントが持つべきスキルです。これらは、どこでも通用する「優れた思考者」としての能力を表しています。

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0のスキルは、どんなプロジェクト、どんなドメイン、どんなスタックにも持ち運べます。普遍的な認知パターンを体現しているからです。

K1:アイデンティティ(規律)

「優れたエンジニア」や「優れたリサーチャー」としての、ある専門分野内のプロジェクト全体に当てはまるスキルです。

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2:ドメイン(専門知識)

「優れたデータベース専門家」や「優れたセキュリティエンジニア」としての、ある分野内で持ち運べるスキルです。

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3:スタック(技術)

「優れたSupabaseユーザー」や「優れたCloudflare開発者」としての、特定の技術スタックに特化したスキルです。

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4:プロジェクト(組織)

私たちの組織とワークフローに固有のスキルです。

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

マイニングループ

フェーズ1:発見

スキルはあらゆる場所からやってきます:

ベンダーリポジトリ:AWS、Anthropic、Cloudflare、Supabase、そしてコミュニティの貢献者たちが、スキル集を公開しています。私たちは25以上のベンダーのルートを追跡しています。

コミュニティプロジェクト:GitHubには、Claude Codeのテンプレート、エージェントパターン、ワークフロー定義があふれています。

社内パターン:私たちのチームが問題を解決していく中で、パターンが浮かび上がってきます。それらはスキルとして形式化されます。

ドキュメントマイニング:技術ドキュメントには、手順、チェックリスト、意思決定ツリーといった暗黙のスキルが含まれていることがよくあります。

発見は継続的なプロセスです。正式な評価の前に候補を追跡するため、スキルのバックログを使っています。

フェーズ2:評価

すべての候補は、同じルーブリックを通過します:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

5つのプロダクト基準すべてに合格しなければなりません。これが、候補の87%が却下される理由です。

その上で、すべての候補は別途トラストレビューを通過します。私たちは、公式のベンダーリポジトリ、よく知られたコミュニティメンテナー、そして無作為なGitHubリポジトリを、同等の信頼できる情報源としては扱いません。

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

信頼できるベンダーは、より軽めの来歴レビューで済みますが、無条件で通過するわけではありません。信頼できない、あるいは未知の情報源は、より深い手動監査を受けます。同梱されたスクリプトは、読み込み、スコープを確認し、安全であると分類されるまでは実行しません。

ギャップ分析:採用する前に、私たちのレジストリを検索します:

uv run orkestra skills search "<capability>"

すでに持っているなら、必要ありません。近いものを持っているなら、採用ではなく統合するかもしれません。

深さと標準のスコアリング:候補がエージェントスキルモデルをどれだけ十分に活用しているかもスコアリングします。単独のSKILL.mdでも有用なことはありますが、agentskills.ioが推奨する形で指示を参照・スクリプト・アセットから分離しているような、より深いスキルの方が価値が高くなります。

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHubのスター数は信頼性スコアを多少押し上げることはありますが、浅い、あるいは安全でないスキルを救うことは決してありません。あいまいなSKILL.mdが1つだけで不透明なスクリプトを含む高スター数のリポジトリは、正確な説明、厳選されたreferences/、そしてスキルの能力を実際に活かすアトミックなヘルパーを持つ、より小さなリポジトリよりも低いスコアになります。

構造分析:スキルの品質を確認します:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

候補にスクリプトが含まれている場合、レビューはより厳格になります。優れたスキルは有用であるだけでは足りません。読みやすく、境界が明確で、エージェントに渡しても安全でなければなりません。この安全性フィルタだけで、他の点では興味深い候補のかなりの割合が失格になります。

フェーズ3:取り込み

スキルが評価を通過すると、レジストリに加わります。しかしスキルがそのままの形で採用されることは決してありません。私たちのシステムに合わせて修正されます。

採用時の修正内容:

1. メタデータの正規化:すべてのスキルに私たちのフロントマタースキーマを適用する
2. Kティアの割り当て:スキルを適切なナレッジレイヤーへ配置する
3. タグの拡充:発見しやすくするためタグを追加する
4. ツール宣言:許可されたツールを明示的に宣言する
5. セクションの整合:コンテンツを私たちのテンプレートに合わせて再構成する

取り込み後の典型的なスキルYAMLです:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

フェーズ4:スコープの割り当て

スキルはスコープ ―― どのエージェントがどのスキルを読み込むかを決めるカテゴリー ―― に割り当てられます:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

エージェントは自分のスコープを宣言し、スキルは自動的に割り当てられます:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

フェーズ5:実体化

本番環境では、スキルはYAMLのまま存在しているわけではありません。Claude Codeが読み込めるSKILL.mdファイルへとレンダリングされます:

uv run orkestra sync

このコマンドは:

1. すべてのスキルYAML定義を読み込む
2. Jinjaテンプレートを通じてそれらをレンダリングする
3. SKILL.mdファイルを.claude/skills/へ書き出す
4. Kティア別(foundations/、identities/、domains/、stacks/、project/)に整理する

最終的な出力構造です:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

休眠スコープパターン

私たちの最も強力なパターンの1つが、「採用済みだが読み込まれていない」スキルです。私たちはこれを休眠スコープと呼んでいます。

k-dense-scientificリポジトリ由来の科学計算スキルを考えてみましょう。私たちは、バイオインフォマティクス、化学、量子コンピューティング、臨床情報学をカバーする120以上のスキルを採用しています。しかし私たちのエージェントのほとんどは、分子ドッキングや遺伝子発現解析を必要としません。

120個すべてのスキルをすべてのエージェントに読み込ませてコンテキストウィンドウを肥大化させる代わりに、私たちは次を行います:

1. 特定のスコープ(例:bioinformatics)付きでスキルを採用する
2. 登録はされているが読み込まれていない、休眠状態に保つ
3. エージェントがそのスコープを宣言したときにのみ有効化する

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

このパターンによって、レジストリには466個のスキルを持ちながら、典型的なエージェントはそのうち関連する40〜60個だけを読み込む、ということが可能になっています。

スキルの種類

スキルには3つの認知パターンがあります:

ワークフロー

順序立った手続き的なステップです。「1. Xをする、2. 次にYをする、3. 最後にZをする」

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

規律

振る舞いのガードレールです。「常にXせよ」「決してYするな」「Zを優先せよ」

type: discipline
# Examples: test-first-discipline, evidence-based-completion

チェックリスト

検証基準です。「Xを確認せよ」「Yを検証せよ」「Zをチェックせよ」

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

品質ゲート

すべてのスキルは、出荷前にバリデーションを通過しなければなりません:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

説明文は、Claude Codeがいつ提案すればよいかを判断できるよう、トリガーフレーズ(「Use when…」「When you need…」)を含む50〜400文字でなければなりません。

私たちは継続的に検証しています:

uv run orkestra validate --show-warnings

ベンダーエコシステム

私たちの373個のベンダースキルは、次から来ています:

プロバイダー	スキル数	ドメイン
AWS Agent	19	クラウドサービス
Anthropic	12	ドキュメント生成
Cloudflare	8	エッジコンピューティング
Supabase	5	データベース
k-dense	100+	科学計算
silvainfm	4	データサイエンス
Java Developer Kit	45+	Spring/Java
Vercel	1	ブラウザ自動化

各ベンダーのルートはmetadata.yamlで宣言されます:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

orkestra syncが実行されると、ベンダースキルはそれぞれのプロバイダー名前空間つきで.claude/skills/vendor/へシンボリックリンクされます。

私たちが学んだこと

選別の厳しさは報われる。 有用そうに見えるものすべてを採用したくなる誘惑はあります。しかしどのスキルにもトークンのコストがかかります。スキルあたり平均2,834トークンともなれば、肥大化はすぐに痛手になります。13%という採用率が、エージェントを軽量に保っています。

構造が発見を可能にする。 Kティアシステムは単なる整理ではなく、持ち運びやすさに関わるものです。K0のスキルはどこでも再利用できます。K4のスキルは意図的にプロジェクト固有です。この明確さが、人間とエージェントの双方が必要なものを見つける助けになります。

休眠スコープはスケールする。 すべてを読み込ませることなく、何百ものスキルを採用できます。スコープによって、個々のエージェントのコンテキストウィンドウを扱いやすいサイズに保ちながら、包括的なレジストリを構築できます。

採用時の修正は不可欠である。 生のままのベンダースキルが、自分たちのシステムに合うことはめったにありません。メタデータの追加、ティアの割り当て、タグの拡充といった取り込みプロセスが、外部のスキルを社内で機能させます。

マイニングは継続的である。 3,500という数字は増え続けています。新しいベンダーリポジトリが現れます。コミュニティのパターンが生まれます。社内のワークフローが固まっていきます。このループが止まることはありません。

次にやること

私たちはいくつかの改善に取り組んでいます:

1. 自動ギャップ検出:未採用のスキルによってよくあるエージェントの失敗が解決できそうな場合にアラートを出す
2. スキルの非推奨化ワークフロー:置き換えられた、あるいは使われていないスキルを引退させるための正式なプロセス
3. スキル間の依存関係:スキルの前提条件を明示的に宣言する
4. 利用状況の分析:エージェントが実際に呼び出しているスキルと、単に読み込んでいるだけのスキルを追跡する

スキルマイニングループはインフラです。華やかではありません。しかしこれこそが、41体のエージェントが466個の能力とともに、コンテキストの上限内に収まりながら一貫して機能する理由です。

これが、3,500が466になった経緯です。3,000を無視したのではなく、体系的に評価し、機能するものだけを採用した結果です。

---

スキルシステムの実際の動きを見てみたいですか? uv run orkestra skills listをチェックして、私たちの現在のレジストリを探索してみてください。