> ## 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 に変換し、`allowed_tools` とマージして qodercli に透過的に渡します。

<div id="sdk-は内蔵-skills-をロードしない" />

<div id="sdkは内蔵skillsをロードしない" />

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

SDK は CLI を起動するときに**常に** `--disable-builtin-skills` を追加します。したがってセッションは CLI の出荷時内蔵 skill（`simplify`、`debug`、`security-review`、`quest`、`batch`、`agent-creator`、`hook-config`、`mcp-config`、`skill-creator` など）を受け取りません。`get_server_info()['skills']` に `source: 'built-in'` のエントリは現れず、モデルのシステムプロンプトにも表示されません。

これは SDK の固定動作で、オプトインのスイッチはありません。CLI 内蔵 skill の機能が必要な場合は、plugin / ユーザーディレクトリ / プロジェクトディレクトリのいずれかに自前で SKILL.md を用意するか、CLI のデフォルトシナリオを直接使ってください。

セッションは以下のソースから提供される skills を引き続き利用できます。

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

現在のセッションで発見された skills を確実に確認するには、ランタイムで `client.get_server_info()['skills']` を読み取ってください。コード内でこの集合をハードコードしないでください。

<div id="cli-デフォルトポリシーの使用" />

<div id="cliデフォルトポリシーの使用" />

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

`skills` を渡さない場合、SDK は追加の `Skill` allowlist を注入せず、完全に CLI 自身のポリシーに委ねます。内蔵 skill が無効化されているため、`setting_sources` / `plugins` のないセッションでは `get_server_info()['skills']` は空配列になります。

```python theme={null}
from qoder_agent_sdk import query, QoderAgentOptions

async for msg in query(
    prompt="このプロジェクトのテストカバレッジを分析して",
    options=QoderAgentOptions(cwd="/path/to/project"),
):
    print(msg)
```

<div id="発見済みの全-skills-を有効化" />

<div id="発見済みの全skillsを有効化" />

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

```python theme={null}
async for msg in query(
    prompt="適切な skill を使ってコードレビューを実施して",
    options=QoderAgentOptions(
        cwd="/path/to/project",
        setting_sources=["project"],
        skills="all",
    ),
):
    print(msg)
```

`skills="all"` は `Skill` ツールが現在 CLI で発見されたすべての skill を呼び出すことを許可します（ソースは `setting_sources` / `plugins` で決まり、内蔵は含まれなくなりました）。

<div id="指定した-skills-のみ有効化" />

<div id="指定したskillsのみ有効化" />

## 指定した skills のみ有効化

```python theme={null}
async for msg in query(
    prompt="review skill で最近の変更をチェックして",
    options=QoderAgentOptions(
        cwd="/path/to/project",
        setting_sources=["project"],
        skills=["review"],
    ),
):
    print(msg)
```

<div id="プラグイン内-skill-の有効化" />

<div id="プラグイン内skillの有効化" />

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

プラグイン内の skill はプラグイン修飾名 `plugin:skill` を使用します。プラグインのロード方法については [Plugins ドキュメント](/ja/cli/sdk/python/plugins) を参照してください。

```python theme={null}
async for msg in query(
    prompt="プラグインが提供する echo skill でこの入力を処理して",
    options=QoderAgentOptions(
        plugins=[{"type": "local", "path": "/path/to/sdk-test-plugin"}],
        skills=["sdk-test-plugin:sdk-echo"],
    ),
):
    print(msg)
```

<div id="明示的なツールホワイトリストとのマージ" />

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

```python theme={null}
async for msg in query(
    prompt="ソースコードを読み、review skill を使って問題のリストを返して",
    options=QoderAgentOptions(
        cwd="/path/to/project",
        setting_sources=["project"],
        allowed_tools=["FileRead", "Grep"],
        skills=["review"],
    ),
):
    print(msg)
```

上記の設定は最終的に `FileRead`、`Grep`、`Skill(review)` を許可します。SDK はマージと重複排除を行い、同名のエントリを重複して書き込むことはありません。

<div id="発見済み-skills-を非表示にする" />

<div id="発見済みskillsを非表示にする" />

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

`options.skills` はツール許可であり、発見フィルタではありません。特定の plugin / user / project skill を init レスポンスに表示させず、モデルのシステムプロンプトにも含めないようにするには、`settings.skillOverrides` を使用する必要があります。

```python theme={null}
options = QoderAgentOptions(
    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 の発見/コンテキスト露出を非表示にするためには使用できません**。

<div id="現在のセッションで発見された-skills-の取得" />

<div id="現在のセッションで発見されたskillsの取得" />

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

初期化結果には、CLI が今回のセッションで発見した skills が含まれます。ホスト UI で「現在利用可能な機能」を表示するのに適しています。`query()` は使い切りのストリームのため、便利な取得インターフェースはありません。`QoderSDKClient` を使うことでハンドシェイク後に読み取ることができます。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, QoderSDKClient

options = QoderAgentOptions(
    cwd="/path/to/project",
    setting_sources=["project"],
    skills="all",
)

async with QoderSDKClient(options) as client:
    info = await client.get_server_info()
    if info:
        for skill in info.get("skills", []):
            print(skill["name"], skill.get("source"))
```

> `skills` はコンテキストとツール可視性の制御であり、セキュリティ境界ではありません。リストされていない skill は `Skill` ツールを通じてモデルに公開されませんが、skill ファイルはディスク上に存在し続け、通常のファイル読み取りツールでアクセスされる可能性があります。

<div id="カスタム-agent-への-skills-プリロード" />

<div id="カスタムagentへのskillsプリロード" />

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

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

```python theme={null}
from qoder_agent_sdk import AgentDefinition, QoderAgentOptions

options = QoderAgentOptions(
    cwd="/path/to/project",
    allowed_tools=["Agent"],
    agents={
        "sdk-skill-helper": AgentDefinition(
            description="sdk-agent-marker skill を使用する必要があるときに呼び出してください。",
            prompt="あなたは指定された skill を読み取り実行することだけを担当する helper agent です。",
            skills=["sdk-agent-marker"],
            maxTurns=2,
        ),
    },
)
```

この種類の `skills` は該当 Agent のコンテキストにのみ影響し、メインセッションで同名の skill を有効化することとは同等ではありません。メインセッションの `allowed_tools` はこの変更の影響を受けません。

<div id="options-クイックリファレンス" />

<div id="optionsクイックリファレンス" />

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

| フィールド             | 型                                                   | 説明                                                               |
| ----------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
| `skills`          | `list[str] \| Literal["all"] \| None`               | メインセッションが `Skill` ツールで呼び出せる skills を制御                           |
| `agents`          | `dict[str, AgentDefinition] \| None`                | カスタム Agent。`AgentDefinition.skills` はその Agent の独立したプリロードリスト      |
| `allowed_tools`   | `list[str]`                                         | ツールホワイトリスト。`skills` が変換した `Skill(...)` エントリとマージ・重複排除されます         |
| `setting_sources` | `list[Literal["user", "project", "local"]] \| None` | CLI がユーザー / プロジェクトディレクトリ内の skills をスキャンするかを制御（デフォルトは空 = サンドボックス） |
| `plugins`         | `list[PluginSpec] \| None`                          | プラグインをロード。プラグイン内の skills は発見集合に加わります                             |

`settings`（dict / path / JSON 文字列）にはいくつかの skill 関連フィールドがあり、SDK はすべて辞書として透過的に渡しますが、実際の効果は CLI バージョンが実装しているかどうかに依存します。

| フィールド                           | 作用                                                                                                                |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `skillOverrides`                | skill 名ごとに `"on" \| "name-only" \| "user-invocable-only" \| "off"` を設定。plugin、user、project などのソースがこの override を尊重 |
| `skillListingMaxDescChars`      | skill listing 内の各説明の文字数上限（cc-sdk デフォルト 1536）、超過すると切り詰められます                                                        |
| `skillListingBudgetFraction`    | skill listing に予約するコンテキストウィンドウの比率（cc-sdk デフォルト 0.01 = 1%）、超過すると説明が圧縮されます                                          |
| `strictPluginOnlyCustomization` | `skills`、`agents`、`hooks`、`mcp` のいずれかまたは複数をプラグインソースからの貢献のみに制限                                                     |

<div id="戻り値リファレンス" />

## 戻り値リファレンス

`client.get_server_info()` が返す dict には以下が含まれます。

```python theme={null}
{
    "commands": [{"name": str, "description": str, ...}, ...],
    "agents": [{"name": str, "description": str, "model": str | None}, ...],
    "skills": [{"name": str, "description": str | None, "source": str | None}, ...],
    "plugins": [{"name": str, "path": str, "source": str | None}, ...],
    # models / account / output_style などのフィールドも含まれます
}
```

<div id="ベストプラクティス" />

## ベストプラクティス

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

<div id="現在の制限事項" />

## 現在の制限事項

* 一部の qodercli バージョンでは、ローカルプラグインの skills が `get_server_info()['skills']` に表示されません。これは CLI 側の発見パスの問題で、SDK の呼び出し方を変更する必要はありません。
* `--disable-slash-commands` は CLI が一括ですべての slash-command skill を無効化する機能ですが、SDK は現状、第一級の option を公開していません。`extra_args` のような非公開経路に依存することは推奨しません。
* `settings.skillListingMaxDescChars`、`settings.skillListingBudgetFraction` は SDK が透過的に渡す listing 予算制御フィールドです。現在の qodercli ではまだ listing 予算制御が実装されていないため、渡してもエラーにはなりませんが、挙動も変わりません。
* Python SDK は現状 `client.supported_skills()` という便利メソッドを提供していません。`get_server_info()['skills']` から読み取る必要があります（バックログに登録済み）。