Skills

​

SDK Does Not Load Built-in Skills

• plugin skills: loaded via options.plugins, addressed with the plugin-qualified name (plugin:skill).
• User / project skills: discovered after explicitly enabling user / project / local via the setting sources option.
• agent-preloaded skills: declared on options.agents[name].skills, scoped to that sub-agent only.

​

Using CLI Default Policy

import { query } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: 'Analyze the test coverage of this project',
  options: {
    cwd: '/path/to/project',
  },
});

​

Enabling All Discovered Skills

const q = query({
  prompt: 'Use an appropriate skill to perform a code review',
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
    skills: 'all',
  },
});

​

Enabling Only Specific Skills

const q = query({
  prompt: 'Use the review skill to inspect recent changes',
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
    skills: ['review'],
  },
});

​

Enabling Plugin Skills

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'],
  },
});

​

Merging with Explicit Tool Allowlist

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'],
  },
});

​

Hiding Discovered Skills

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': fully hidden—absent from the discovery list and the model system prompt, and Skill tool calls are rejected.
• Other values: 'on' (default), 'name-only' (only shows name, not description), 'user-invocable-only' (invisible to model, user can still trigger via /name).
• Scope of effect: every SDK-visible source (plugin, user, project, …) respects this override; CLI built-ins are already blocked by --disable-builtin-skills, so overrides for them have nothing to act on.
• Key naming rules: Plugin skills use the plugin-qualified name plugin:skill; non-plugin skills use bare names. Both forms can be written simultaneously; matching is attempted against the fully qualified name first, then falls back to the bare name.

options.skills can hide the main session's model context but doesn't filter the discovery list; to hide from the discovery list too, use skillOverrides: { name: 'off' }.

​

Reading Skills Discovered in the Current Session

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));

A string-list skills controls main-session context and tool visibility; it is not a security boundary. Unlisted skills do not appear in the model's skill listing and cannot be invoked through the Skill tool, but their files remain on disk and can still be accessed by regular file tools.

​

Custom Agent Preloading Skills

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,
      },
    },
  },
});

​

Options Reference

​

Return Value Reference

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

​

Best Practices

• Enable skills deliberately: 'all' suits development and debugging; end-user products should usually pass an explicit list.
• Recreate built-in skill behavior yourself if you want it: the SDK won't inject simplify / security-review into sessions; provide your own SKILL.md within plugin or setting-sources scope.
• Don't treat skills as a sandbox: security boundaries belong to tool allow/deny lists, the permission callback, permission modes, and sandboxing combined.
• Use the discovery list for UIs: initializationResult().skills / get_server_info()['skills'] is the stable entry into CLI discovery—use it to show "discovered skills", not as the main session's invocable set.
• Manage sub-Agent skills separately: They are independent lists from the main session's options.skills and do not override each other.

​

Current Limitations

• --disable-slash-commands is the CLI's switch to disable all slash-command skills at once; the SDK currently exposes no first-class option—avoid relying on non-public passthrough paths.
• settings.skillListingMaxDescChars and settings.skillListingBudgetFraction are listing-budget control fields that the SDK passes through; the current qoderclicn has not implemented listing budget control, so passing them does not raise an error but also does not change behavior.
• The Python SDK does not yet provide a client.supported_skills() convenience method; read from get_server_info()['skills'] instead (already on the backlog).