スキルガイド

MoAI-ADK のスキルシステムを詳しく案内します。スキルはエージェンティックハーネスの知識層であり、「必要な知識だけを必要な瞬間にロードする」という点でトークノミクスが最も具体的に実装された場所でもあります。

プラットフォームの基礎

プラットフォーム層の背景については スキル を参照してください。MoAI-ADK としての説明はこのページです。

情報

スキルとは?

1999 年の映画 マトリックス のヘリコプター操縦シーンを覚えていますか? ネオがトリニティにヘリコプターを操縦できるか尋ねると、トリニティは本部に電話してヘリコプターのモデルを伝え、取扱説明書を送ってもらいます。

Claude Code のスキル がまさにその 取扱説明書 です。必要な瞬間に必要な知識だけをロードして、AI が即座に専門家のように振る舞えるようにします。

スキルは Claude Code に特定分野の専門知識を提供する 知識モジュール です。

学校にたとえると、Claude Code が生徒でスキルは教科書です。数学の時間には数学の教科書を、理科の時間には理科の教科書を開くように、Claude Code も Python コードを書くときは Python スキルを、React UI を作るときは Frontend スキルをロードします。

flowchart TD
    USER[ユーザーリクエスト] --> DETECT[キーワード検出]
    DETECT --> TRIGGER{トリガーマッチング}
    TRIGGER -->|Python 関連| PY["moai-domain-backend
バックエンド専門知識"]
    TRIGGER -->|React 関連| FE["moai-domain-frontend
フロントエンド専門知識"]
    TRIGGER -->|セキュリティ関連| SEC["moai-foundation-core
TRUST 5 セキュリティ原則"]
    TRIGGER -->|DB 関連| DB["moai-domain-database
データベース専門知識"]

    PY --> AGENT[エージェントに知識を注入]
    FE --> AGENT
    SEC --> AGENT
    DB --> AGENT

スキルがない場合: Claude Code は一般的な知識のみで応答します。スキルがある場合: MoAI-ADK のルール、パターン、ベストプラクティスを適用して応答します。

MoAI-ADK テンプレートは合計 34 個のスキル を提供します。カタログはインストール範囲で、すべてのプロジェクトに配置される コアスキル 21 個 と、必要なときだけ配置される オプションパックスキル 13 個 (backend 3 · design 1 · devops 5 · frontend 4) に分けます。機能別にまとめると Foundation 4 + Workflow 8 + Domain 7 + Reference 11 + Meta/Harness 3 = 専門スキル 33 個で、これにリクエストを専門スキルへルーティングする moai umbrella スキル 1 個を加えて 34 個です。ユーザープロジェクトでは追加で hns-* ユーザー定義ハーネススキルを作成できます。プログラミング言語対応は rules/moai/languages/ 配下のルールで提供され、別途スキルではありません。

この数字もダイエットの結果です — スキルカタログは v3 期間中に 48 → 38 個へ精練され、オプションパックを含む現在の数は 34 個です。

moai-domain-svg-infographic スキルでどの種類のダイアグラムを作れるかは、推測ではなく実測で確認しました。外部カタログ (SkillStead TypePack) の 9 形式を同じ生成課題として実行し、スキル自身の品質ゲート (決定論的なソース lint と寸法検証付き 2 倍解像度 PNG レンダー) を通るかを測定した結果、9 形式すべてを再現できました。

各形式は、4 つの基本レイアウト (スタック、左から右へのフロー、並列比較、階層ツリー) の上で情報構造を保つ形で表現されます。形式別の判定表とゲートログは .moai/reports/t272/verdict.md にあります。

34 個のスキルは MoAI-ADK テンプレートに含まれ (コア 21 個は即時、13 個はオプションパック経由)、各スキルは独立してロードされてトークンを節約します。ユーザーは追加でプロジェクト別の hns-* ユーザー定義ハーネススキルを作成できます。

MoAI-ADK のスキルは 3 段階の段階的公開 (Progressive Disclosure) システムを使います。すべてのスキルを一度にロードするとトークンが浪費されるので、必要な分だけ段階的にロードします。コンテキストダイエットのスキル層の実装だと見ればよいでしょう。

flowchart TD
    subgraph L1["Level 1: メタデータ (~100 トークン)"]
        M1["名前、説明、トリガーキーワード"]
        M2["常にロードされる"]
    end

    subgraph L2["Level 2: 本文 (~5,000 トークン)"]
        B1["スキルドキュメント全体"]
        B2["コード例、パターン"]
    end

    subgraph L3["Level 3: バンドル (無制限)"]
        R1["modules/ ディレクトリ"]
        R2["reference.md, examples.md"]
    end

    L1 -->|"トリガーマッチ時"| L2
    L2 -->|"深層情報が必要な時"| L3

• 従来方式: 34 個のスキルを全ロード = 約 170,000 トークン (不可能)
• 段階的公開: メタデータのみロード = 約 3,400 トークン (98% 節約)
• 必要時にロード: 作業に必要な 2~3 個のスキルのみ = 約 15,000 トークン追加

スキルは 4 つのトリガー条件 で自動ロードされます。

flowchart TD
    REQ[ユーザーリクエスト分析] --> KW{キーワード検出}
    REQ --> AG{エージェント呼び出し}
    REQ --> PH{ワークフローステップ}
    REQ --> LN{言語検出}

    KW -->|"api, database"| SKILL1[moai-domain-backend]
    AG -->|"manager-develop"| SKILL1
    PH -->|"run ステップ"| SKILL2[moai-workflow-ddd]
    LN -->|"Python ファイル"| SKILL3[moai-domain-backend]

    SKILL1 --> LOAD[スキルロード完了]
    SKILL2 --> LOAD
    SKILL3 --> LOAD

# スキルフロントマターでトリガーを定義
triggers:
  keywords: ["api", "database", "authentication"] # キーワードマッチング
  agents: ["manager-spec", "manager-develop"] # エージェント呼び出し時
  phases: ["plan", "run"] # ワークフローステップ
  languages: ["python", "typescript"] # プログラミング言語

トリガーの優先順位:

1. キーワード (keywords): ユーザーメッセージからキーワードを検出すると即座にロード
2. エージェント (agents): 特定のエージェントが呼び出されたとき自動ロード
3. ステップ (phases): Plan/Run/Sync ステップに応じてロード
4. 言語 (languages): 作業中のファイルのプログラミング言語に応じてロード

Claude Code の対話で直接スキルを呼び出せます。

# Claude Code でスキル呼び出し
> Skill("moai-domain-backend")
> Skill("moai-domain-frontend")
> Skill("moai-ref-api-patterns")

ほとんどの場合、スキルはトリガーメカニズムによって 自動的にロード されます。ユーザーが直接呼び出す必要なく、対話コンテキストを分析して適切なスキルが有効化されます。

スキルファイルは .claude/skills/ ディレクトリに配置されます。

.claude/skills/
├── moai-foundation-core/       # Foundation カテゴリ (template-managed)
│   ├── SKILL.md                # メインスキルドキュメント (500 行以下)
│   ├── modules/                # 深層ドキュメント (無制限)
│   │   ├── trust-5-framework.md
│   │   ├── spec-first-ddd.md
│   │   └── delegation-patterns.md
│   ├── examples.md             # 実践例
│   └── reference.md            # 外部参照リンク
│
├── moai-domain-backend/        # Domain カテゴリ (template-managed)
│   ├── SKILL.md
│   └── modules/
│       ├── api-patterns.md
│       └── microservices.md
│
├── hns-my-harness/             # ユーザーハーネススキル (user-owned, hns-* 接頭辞)
│   └── SKILL.md
│
└── my-custom-skill/            # ユーザーカスタムスキル (user-owned)
    └── SKILL.md

スキル接頭辞は 配布主体 を区別し、moai update の動作が異なります。

hns-* 接頭辞はユーザーが生成したハーネススキルを意味し、moai update が決して上書きしたり削除したりしません。テンプレートに hns-* スキルをミラーリングしてはいけません (CI ガードが検出)。

注意

注意: moai-* 接頭辞が付いたスキルは MoAI-ADK アップデート時に上書きされます。 個人スキルとハーネススキルは hns-* 接頭辞または接頭辞のないディレクトリに作成してください。

各スキルの SKILL.md は次の構造に従います。

---
name: moai-domain-backend
description: >
  バックエンド開発専門家。API 設計、マイクロサービス、データベース統合パターンを提供。
  API、Web アプリ、データパイプライン開発時に使用。
version: 3.0.0
category: domain
status: active
triggers:
  keywords: ["api", "database", "microservices", "authentication"]
allowed-tools: ["Read", "Grep", "Glob", "Bash"]
---

# バックエンド開発専門家

## Quick Reference

(クイックリファレンス - 30 秒)

## Implementation Guide

(実装ガイド - 5 分)

## Advanced Patterns

(高度なパターン - 10 分+)

## Works Well With

(関連スキル/エージェント)

ユーザーが Python FastAPI プロジェクトで作業するシナリオです。

# 1. ユーザーが API 開発をリクエスト
> FastAPI でユーザー認証 API を作って

# 2. MoAI-ADK が自動的に検出するキーワード
# "FastAPI" → moai-domain-backend トリガー (Python パターンは rules/moai/languages/ を通じて提供)
# "認証"    → moai-domain-backend トリガー
# "API"     → moai-domain-backend トリガー

# 3. 自動ロードされるスキル
# - moai-domain-backend (Level 2): API 設計パターン、認証戦略
# - moai-foundation-core (Level 1): TRUST 5 品質基準

# 4. エージェントがスキルの知識を活用して実装
# - FastAPI ルーターパターンを適用
# - JWT 認証のベストプラクティスを適用
# - pytest テストを自動生成
# - TRUST 5 品質基準を満たす

1 つの作業で複数のスキルが協力するプロセスです。

flowchart TD
    REQ["ユーザー: Supabase + Next.js で
フルスタックアプリを作って"] --> ANALYZE[リクエスト分析]

    ANALYZE --> S1["moai-domain-frontend
React/Next.js パターン"]
    ANALYZE --> S2["moai-domain-backend
API 設計パターン"]
    ANALYZE --> S3["moai-domain-database
データベース統合"]
    ANALYZE --> S4["moai-foundation-core
TRUST 5 品質"]

    S1 --> IMPL[統合実装]
    S2 --> IMPL
    S3 --> IMPL
    S4 --> IMPL

    IMPL --> RESULT["型安全な
フルスタックアプリ"]

Claude Code はプロジェクトルートだけでなくネストした下位ディレクトリ (parent-walk) でも .claude/skills/ を発見します。したがってモノレポは各パッケージ自身の .claude/skills/ ディレクトリにパッケージローカルなスキルを配置できます。自身の .claude/skills/ を含むネストしたディレクトリ内部で作業するとき、そのネストしたディレクトリのスキルはその下位ツリーで作業する間、ルートレベルのスキルとともにロードされます。

ネストチェーンに沿って 2 つ以上の .claude/skills/ ディレクトリに同じスキル名が現れると、closest-directory-wins (最も近いディレクトリ優先) ルールが衝突を解決します: 現在の作業ディレクトリに最も近い .claude/skills/ がより上のツリーのものを隠します (shadow)。これはネストした .claude/ ディレクトリ配下でエージェント、ワークフロー、output-styles にすでに適用される先行ルールと同じです — 最も内側の .claude/ が勝ちます。ルートスキルを意図的に再定義するパッケージローカルなスキルは同じ名前を維持する必要があります。名前を変えると再定義ではなく 2 番目のスキルが生成されます。

disableBundledSkills (settings.json のブール値、または環境変数の形) は Claude Code のバンドル skills およびワークフロー — 例: /deep-research、内蔵スラッシュコマンド skills — を discovery から隠し、enterprise + personal + project + plugin skills のみを見せます。選別されたバンドルなしの skill 表面を提供するときに使ってください。MoAI-ADK はこのトグルを自身の生成器で生成しません。利用可能なオプションとしてここに文書化されます。付随する --safe-mode 起動フラグは Settings JSON ガイド に文書化されています。

• エージェントガイド - スキルを活用するエージェント体系
• ビルダーエージェントガイド - カスタムスキルの生成方法
• CLAUDE.md ガイド - スキル設定とルール体系

情報

ヒント: スキルをうまく活用する核心は 適切なキーワードの使用 です。「Python で REST API を作って」とリクエストすると moai-domain-backend スキルが自動的に有効化され (Python パターンは rules/moai/languages/ を通じて提供)、最適なコードを生成します。