メインコンテンツへスキップ

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

options.skills は、現在のセッションで Skill ツールがどの skill を呼び出せるかを制御します。SDK はこれを CLI の Skill allowlist に変換し、allowedTools とマージして qodercli に透過的に渡します。

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

SDK は CLI を起動するときに常に --disable-builtin-skills を追加します。したがってセッションは CLI の出荷時内蔵 skill（simplify、debug、security-review、quest、batch、agent-creator、hook-config、mcp-config、skill-creator など）を受け取りません。init.skills に source: 'built-in' のエントリは現れず、モデルのシステムプロンプトにも表示されません。 これは SDK の固定動作で、オプトインのスイッチはありません。CLI 内蔵 skill の機能が必要な場合は、plugin / ユーザーディレクトリ / プロジェクトディレクトリのいずれかに自前で SKILL.md を用意するか、SDK を使わずに CLI を直接実行してください。 セッションは以下のソースから提供される skills を引き続き利用できます：
  • plugin skills：options.plugins でロードし、プラグイン修飾名（plugin:skill）でアドレスします。
  • user / project skills：options.settingSources で user / project / local を明示的に有効化すると発見されます。
  • Agent プリロード skills：options.agents[name].skills で宣言し、対象のサブ Agent のみに作用します。
現在のセッションで発見された skills を確実に確認するには、一度 query() を実行して init.skills を読み取ってください。コード内でこの集合をハードコードしないでください。

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

skills を渡さない場合、SDK は追加の Skill allowlist を注入せず、完全に CLI 自身のポリシーに委ねます。内蔵 skill が無効化されているため、settingSources / plugins のないセッションでは init.skills は空配列になります。 
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 を呼び出すことを許可します（ソースは settingSources / 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 はプラグイン修飾名を使用します。プラグインのロード方法については 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'],
  },
});
上記の設定は最終的に Read、Grep、Skill(review) を許可します。

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

options.skills はツール許可であり、発見フィルタではありません。特定の plugin / user / project skill を init.skills に表示させず、モデルのシステムプロンプトにも含めないようにするには、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'：完全に非表示。init.skills に入らず、モデルのシステムプロンプトにも入らず、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 はツール呼び出し許可のみを制御し、skill の発見/コンテキスト露出を非表示にするためには使用できません。

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

初期化結果には、CLI が今回のセッションで発見した skills が含まれます。ホスト UI で「現在利用可能な機能」を表示するのに適しています。 
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 クイックリファレンス

フィールド型説明
skillsstring[] | 'all'メインセッションが Skill ツールで呼び出せる skills を制御
agentsRecord<string, AgentDefinition>カスタム Agent；Agent 内で独立した skills プリロードリストを宣言可能
allowedToolsstring[]ツールホワイトリスト；skills が変換した Skill(...) エントリとマージ・重複排除されます
settingSources('user' | 'project' | 'local')[]CLI がユーザー / プロジェクトディレクトリ内の skills をスキャンするかを制御（デフォルトは空 = サンドボックス）
pluginsPluginSpec[]プラグインをロード；プラグイン内の skills は発見集合に加わります
settings にはいくつかの skill 関連フィールドもあり、SDK はすべて透過的に渡しますが、実際の効果は CLI バージョンが実装しているかどうかに依存します：
フィールド作用
skillOverridesskill 名ごとに 'on' | 'name-only' | 'user-invocable-only' | 'off' を設定；plugin、user、project などのソースがこの override を尊重
skillListingMaxDescCharsskill listing 内の各説明の文字数上限（SDK デフォルト 1536）、超過すると切り詰められます
skillListingBudgetFractionskill listing に予約するコンテキストウィンドウの比率（SDK デフォルト 0.01 = 1%）、超過すると説明が圧縮されます
strictPluginOnlyCustomizationskills、agents、hooks、mcp のいずれかまたは複数をプラグインソースからの貢献のみに制限

​
戻り値リファレンス

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

​
ベストプラクティス

  • 必要に応じて skills を有効化：skills: 'all' は開発とデバッグに適しています。エンドユーザー向けの製品では通常、明確なリストを渡すべきです。
  • CLI 内蔵 skill の動作が欲しいなら自前で複製する：SDK は simplify / security-review などをセッションに注入しません。必要であれば plugin または settingSources で見える範囲に自前の SKILL.md を提供してください。
  • skills をサンドボックスとして使用しない：セキュリティ境界は allowedTools、disallowedTools、canUseTool、パーミッションモード、サンドボックスによって共同で制御すべきです。
  • UI には initializationResult().skills を使用：これは CLI 発見パスの安定したエントリポイントで、「現在利用可能な skill」を表示するために使用します。
  • サブ Agent の skills は個別に管理：メインセッションの options.skills とは2つの独立したリストであり、相互に上書きしません。