> ## 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. # Skills `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` は空配列になります。 ```typescript theme={null} 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 を有効化 ```typescript theme={null} 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 のみ有効化 ```typescript theme={null} const q = query({ prompt: 'Use the review skill to inspect recent changes', options: { cwd: '/path/to/project', settingSources: ['project'], skills: ['review'], }, }); ```
## プラグイン内 skill の有効化 プラグイン内の skill はプラグイン修飾名を使用します。プラグインのロード方法については [Plugins ドキュメント](/ja/cli/sdk/plugins) を参照してください。 ```typescript theme={null} 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'], }, }); ```
## 明示的なツールホワイトリストとのマージ ```typescript theme={null} 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` を使用する必要があります。 ```typescript theme={null} 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 で「現在利用可能な機能」を表示するのに適しています。 ```typescript theme={null} 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 を持って実行されます。 ```typescript theme={null} 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 クイックリファレンス | フィールド | 型 | 説明 | | ---------------- | ------------------------------------ | ---------------------------------------------------------------- | | `skills` | `string[] \| 'all'` | メインセッションが `Skill` ツールで呼び出せる skills を制御 | | `agents` | `Record` | カスタム Agent；Agent 内で独立した `skills` プリロードリストを宣言可能 | | `allowedTools` | `string[]` | ツールホワイトリスト；`skills` が変換した `Skill(...)` エントリとマージ・重複排除されます | | `settingSources` | `('user' \| 'project' \| 'local')[]` | CLI がユーザー / プロジェクトディレクトリ内の skills をスキャンするかを制御（デフォルトは空 = サンドボックス） | | `plugins` | `PluginSpec[]` | プラグインをロード；プラグイン内の skills は発見集合に加わります | `settings` にはいくつかの skill 関連フィールドもあり、SDK はすべて透過的に渡しますが、実際の効果は CLI バージョンが実装しているかどうかに依存します： | フィールド | 作用 | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `skillOverrides` | skill 名ごとに `'on' \| 'name-only' \| 'user-invocable-only' \| 'off'` を設定；plugin、user、project などのソースがこの override を尊重 | | `skillListingMaxDescChars` | skill listing 内の各説明の文字数上限（SDK デフォルト 1536）、超過すると切り詰められます | | `skillListingBudgetFraction` | skill listing に予約するコンテキストウィンドウの比率（SDK デフォルト 0.01 = 1%）、超過すると説明が圧縮されます | | `strictPluginOnlyCustomization` | `skills`、`agents`、`hooks`、`mcp` のいずれかまたは複数をプラグインソースからの貢献のみに制限 | ***
## 戻り値リファレンス ```typescript theme={null} 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つの独立したリストであり、相互に上書きしません。