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

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

​
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'] を読み取ってください。コード内でこの集合をハードコードしないでください。

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

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

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

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

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 で決まり、内蔵は含まれなくなりました）。

​
指定した skills のみ有効化

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

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

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

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

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 はマージと重複排除を行い、同名のエントリを重複して書き込むことはありません。

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

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

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

初期化結果には、CLI が今回のセッションで発見した skills が含まれます。ホスト UI で「現在利用可能な機能」を表示するのに適しています。query() は使い切りのストリームのため、便利な取得インターフェースはありません。QoderSDKClient を使うことでハンドシェイク後に読み取ることができます。 
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 ファイルはディスク上に存在し続け、通常のファイル読み取りツールでアクセスされる可能性があります。

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

options.agents でカスタムサブ Agent を定義する場合、AgentDefinition 内で skills を宣言できます。メインセッションが Agent ツールを呼び出すと、サブ Agent は指定された skill を持って実行されます。 
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 はこの変更の影響を受けません。

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

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

​
戻り値リファレンス

client.get_server_info() が返す dict には以下が含まれます。 
{
    "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 などのフィールドも含まれます
}

​
ベストプラクティス

  • 必要に応じて 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つの独立したリストであり、相互に上書きしません。

​
現在の制限事項

  • 一部の 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'] から読み取る必要があります（バックログに登録済み）。