跳转到主要内容

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）。
  • 用户 / 项目 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。关于 plugin 加载方式见 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 / 用户 / 项目 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 触发）。
  • 影响范围：plugin、user、project 等所有 SDK 可见来源都尊重该 override；CLI 内置 skill 已经被 --disable-builtin-skills 拦在外面，写不写 override 都不会出现。
  • key 命名规则：插件 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"]] | None决定 CLI 是否扫描用户 / 项目目录里的 skills（默认空 = 沙箱）
pluginslist[PluginSpec] | None加载插件，插件里的 skills 会进入发现集合
settings（dict / path / JSON 字符串）有几个 skill 相关字段，SDK 都是字典透传，实际效果取决于 CLI 版本是否实现：
字段作用
skillOverrides按 skill 名设置 "on" | "name-only" | "user-invocable-only" | "off"；plugin、user、project 等来源都尊重该 override
skillListingMaxDescCharsskill listing 里每条描述的字符上限（cc-sdk 默认 1536），超过会被截断
skillListingBudgetFraction给 skill listing 预留的上下文窗口比例（cc-sdk 默认 0.01 = 1%），超出后描述会被压缩
strictPluginOnlyCustomization把 skills、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 是两套独立的列表，互不覆盖。

​
当前限制

  • 部分 qodercli 版本下，本地 plugin 的 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'] 读取（已列入 backlog）。