Skills - Qoder

このページの「メインセッション」は query()（または Python の QoderSDKClient）が直接駆動するセッションを指し、Agent ツールで委任されるサブ Agent と対比されます。両者の関係はサブ Agent を参照してください。 options.skills はメインセッションの skill コンテキストと Skill ツールの呼び出しポリシーを制御します。文字列リストを渡すと、SDK はメインセッションの skill allowlist を発行し、各項目を Skill(name) にコンパイルしてツール許可リスト（allowedTools / allowed_tools）とマージします。'all' を渡すと発見済みのすべての skill を呼び出せ、メインセッションのコンテキストは追加でフィルタされません。

SDK は内蔵 skills をロードしない

SDK は CLI 起動時に常に --disable-builtin-skills を追加するため、セッションは CLI 出荷時の組み込み skill 群（simplify、debug、security-review、quest、batch、agent-creator、hook-config、mcp-config、skill-creator など）を取得しません。発見リスト（TypeScript の initializationResult().skills、Python の get_server_info()['skills']）にも source: 'built-in' のエントリは現れず、モデルのシステムプロンプトからも見えません。これは SDK の固定動作で、オプトインのスイッチはありません。CLI 内蔵 skill の機能が必要な場合は、plugin / ユーザーディレクトリ / プロジェクトディレクトリのいずれかに自前で SKILL.md を用意するか、SDK を使わずに CLI を直接実行してください。セッションは以下のソースから提供される skills を引き続き利用できます：

plugin skills：options.plugins でロードし、プラグイン修飾名（plugin:skill）でアドレスします。
ユーザー / プロジェクト skills：setting sources オプションで user / project / local を明示的に有効化すると発見されます。
Agent プリロード skills：options.agents[name].skills で宣言し、対象のサブ Agent のみに作用します。

このセッションでどの skills が発見されたかを確実に知るには、実行時に発見リストを読み取ってください。コードに集合をハードコードしないでください。

CLI デフォルトポリシーの使用

skills を渡さない場合、SDK は追加の Skill allowlist を注入せず、CLI 自身のポリシーに完全に委ねます。組み込み skill は無効化済みのため、setting sources / plugins のないセッションでは発見リストは空になります。

import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Analyze the test coverage of this project',
  options: {
    cwd: '/path/to/project',
  },
});

発見済みの全 skills を有効化

const q = query({
  prompt: 'Use an appropriate skill to perform a code review',
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
    skills: 'all',
  },
});

skills に 'all' を指定すると、Skill ツールは CLI が現在発見しているすべての skill を呼び出せます（ソースは setting sources / plugins で決まり、組み込みはもう含まれません）。

指定した skills のみ有効化

const q = query({
  prompt: 'Use the review skill to inspect recent changes',
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
    skills: ['review'],
  },
});

文字列リストを渡すと、一致する skill だけがメインモデルの skill 一覧に表示され、Skill ツールから呼び出せます。項目には通常名とプラグイン修飾名の両方を使用できます。空リスト [] を渡すと、メインセッションではすべての skill が非表示になり、Skill ツールからの呼び出しも拒否されます。このリストは CLI の発見結果を変えません。列挙されていない skill も発見リストに現れることがあります。

プラグイン内 skill の有効化

プラグイン内の skill はプラグイン修飾名 plugin:skill を使用します。プラグインのロード方法については Plugins ドキュメントを参照してください。

const q = query({
  prompt: 'Use the echo skill provided by the plugin to handle this input',
  options: {
    plugins: [{ type: 'local', path: '/path/to/sdk-test-plugin' }],
    skills: ['sdk-test-plugin:sdk-echo'],
  },
});

明示的なツールホワイトリストとのマージ

const q = query({
  prompt: 'Read the source and use the review skill to produce a list of issues',
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
    allowedTools: ['Read', 'Grep'],
    skills: ['review'],
  },
});

上記の設定は最終的に、列挙した読み取り / 検索ツールと Skill(review) を許可します。SDK はマージと重複排除を行い、同名エントリを重複して書き込みません。

発見済み skills を非表示にする

文字列リスト形式の options.skills はメインセッションのモデルコンテキストをフィルタし Skill ツール呼び出しを制限しますが、発見リストの発見結果は変えません。plugin / ユーザー / プロジェクトの skill を発見リストからも消したい場合は、settings.skillOverrides を使ってください。

const q = query({
  prompt: 'Handle this task',
  options: {
    plugins: [{ type: 'local', path: '/path/to/sdk-test-plugin' }],
    settings: {
      skillOverrides: {
        'sdk-test-plugin:sdk-echo': 'off',
      },
    },
  },
});

'off'：完全に非表示。発見リストにもモデルのシステムプロンプトにも現れず、Skill ツール呼び出しも拒否されます。
その他の値：'on'（デフォルト）、'name-only'（名前のみ表示、説明は非表示）、'user-invocable-only'（モデルからは見えないが、ユーザーは /name でトリガー可能）。
影響範囲：SDK から見える全ソース（plugin、user、project など）がこの override を尊重します。CLI 内蔵 skill はすでに --disable-builtin-skills で遮断されているため、override を書いても作用対象がありません。
キーの命名規則：プラグイン skill はプラグイン修飾名 plugin:skill を使用、非プラグイン skill は修飾なしの名前を使用。両方の形式を同時に記述可能で、マッチング時は完全名で先にヒットし、ヒットしない場合は修飾なしの名前にフォールバックします。

options.skills はメインセッションのモデルコンテキストを隠せますが、発見リストはフィルタしません。発見リストからも隠す場合は skillOverrides: { name: 'off' } を使ってください。

現在のセッションで発見された skills の取得

初期化結果には、CLI がこのセッションで発見した完全な skill リストが含まれ、文字列リスト形式の options.skills によるフィルタは受けません。ホスト UI で「発見済み skills」を表示する用途に適しており、メインセッションの現在呼び出し可能なリストとしては使えません。Python では query() は単発ストリームで簡便なクエリ API がないため、QoderSDKClient でハンドシェイク後に読み取ってください。

const q = query({
  prompt: 'Do not execute any task yet',
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
    skills: 'all',
  },
});

const init = await q.initializationResult();
console.log(init.skills?.map((skill) => skill.name));

文字列リスト形式の skills はメインセッションのコンテキストとツール可視性を制御しますが、セキュリティ境界ではありません。未指定の skill はモデルの skill 一覧に表示されず、Skill ツールからも呼び出せませんが、そのファイルはディスク上に残り、通常のファイルツールでアクセスされる可能性があります。

カスタム Agent への Skills プリロード

options.agents でカスタムサブ Agent を定義する場合、Agent 定義内で skills を宣言できます。メインセッションが Agent ツールを呼び出すと、サブ Agent は指定された skill を持って実行されます。

const q = query({
  prompt: 'Dispatch a helper agent that uses the sdk-agent-marker skill to return the marker',
  options: {
    cwd: '/path/to/project',
    allowedTools: ['Agent'],
    agents: {
      'sdk-skill-helper': {
        description: 'Invoke when the sdk-agent-marker skill is needed.',
        prompt: 'You are a helper agent that only reads and runs the specified skill.',
        skills: ['sdk-agent-marker'],
        maxTurns: 2,
      },
    },
  },
});

この種の skills はその Agent のコンテキストにのみ影響し、メインセッションで同名 skill を有効化することにはなりません——メインセッションのツール許可リストはこの変更の影響を受けません。

Options クイックリファレンス

フィールド（TypeScript / Python）	説明
`skills` / `skills`	リストはメインセッションの skill コンテキストと呼び出しを制限。`[]` で全無効。`'all'` で発見済みの全 skills を有効化
`agents` / `agents`	カスタム Agent。Agent 定義内で独立した `skills` プリロードリストを宣言可能
`allowedTools` / `allowed_tools`	ツール許可リスト。`skills` からコンパイルされた `Skill(...)` エントリとマージ・重複排除される
`settingSources` / `setting_sources`	CLI がユーザー / プロジェクトディレクトリの skills をスキャンするかを決定（デフォルト空 = サンドボックス）
`plugins` / `plugins`	プラグインをロード。プラグイン内の skills が発見集合に入る

settings にはいくつかの skill 関連フィールドもあり、SDK はすべて透過的に渡しますが、実際の効果は CLI バージョンが実装しているかどうかに依存します：

フィールド	作用
`skillOverrides`	skill 名ごとに `'on' \| 'name-only' \| 'user-invocable-only' \| 'off'` を設定；plugin、user、project などのソースがこの override を尊重
`skillListingMaxDescChars`	skill listing 内の各説明の文字数上限。SDK はそのまま渡し、デフォルト値は CLI バージョンに依存します
`skillListingBudgetFraction`	skill listing に割り当てるコンテキストウィンドウの比率。SDK はそのまま渡し、デフォルト値は CLI バージョンに依存します

戻り値リファレンス

type SDKControlInitializeResponse = {
  skills?: Array<{ name: string; description?: string; source?: string }>;
  // ...also returns commands / agents / models and similar fields
};

ここでは skill 関連フィールドのみ示します。完全な型は SDK References を参照してください。Python のストリーミング SystemMessage(subtype="init").data["skills"] は skill 名のリストであり、このメタデータ付き発見リストとは別の構造です。

ベストプラクティス

skills は必要に応じて有効化：'all' は開発とデバッグ向け。エンドユーザー向けプロダクトでは通常、明示的なリストを渡すべきです。
CLI 組み込み skill の動作が欲しければ自前で再現：SDK は simplify / security-review などをセッションに注入しません。必要なら plugin または setting sources の範囲で自前の SKILL.md を提供してください。
skills をサンドボックスとして扱わない：セキュリティ境界はツールの許可/拒否リスト、権限コールバック、権限モード、サンドボックスの組み合わせで制御すべきです。
UI には発見リストを使う：initializationResult().skills / get_server_info()['skills'] は CLI 発見チェーンの安定した入り口です。「発見済み skill」の表示に使い、メインセッションの呼び出し可能セットとしては扱わないでください。
サブ Agent の skills は個別に管理：メインセッションの options.skills とは2つの独立したリストであり、相互に上書きしません。

現在の制限事項

--disable-slash-commands は CLI がすべての slash-command skill を一括無効化する機能ですが、SDK は現在ファーストクラスの option を公開していません。非公開の透過経路への依存は推奨しません。
settings.skillListingMaxDescChars、settings.skillListingBudgetFraction は SDK が透過的に渡す listing 予算制御フィールドです。現在の qodercli ではまだ listing 予算制御が実装されていないため、渡してもエラーにはなりませんが、挙動も変わりません。
Python SDK は現状 client.supported_skills() という便利メソッドを提供していません。get_server_info()['skills'] から読み取る必要があります（バックログに登録済み）。

​SDK は内蔵 skills をロードしない

​CLI デフォルトポリシーの使用

​発見済みの全 skills を有効化

​指定した skills のみ有効化

​プラグイン内 skill の有効化

​明示的なツールホワイトリストとのマージ

​発見済み skills を非表示にする

​現在のセッションで発見された skills の取得

​カスタム Agent への Skills プリロード

​Options クイックリファレンス

​戻り値リファレンス

​ベストプラクティス

​現在の制限事項