Skills

​

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

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

​

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

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 を有効化

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

​

指定した skills のみ有効化

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

​

プラグイン内 skill の有効化

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

​

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

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

​

発見済み 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'：完全に非表示。発見リストにもモデルのシステムプロンプトにも現れず、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 はメインセッションのモデルコンテキストを隠せますが、発見リストはフィルタしません。発見リストからも隠す場合は skillOverrides: { name: 'off' } を使ってください。

​

ユーザーが選択した Skills を単一メッセージで有効化

import { query, type SDKUserMessage } from '@qoder-ai/qoder-agent-sdk';

async function* messages(): AsyncGenerator<SDKUserMessage> {
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: [{ type: 'text', text: 'この変更をレビューし、説明は簡潔にしてください。' }],
    },
    parent_tool_use_id: null,
    client_composed: true,
    selected_skills: [
      { name: 'review' },
      { name: 'explain', arguments: '--concise' },
    ],
  };
}

const q = query({
  prompt: messages(),
  options: {
    cwd: '/path/to/project',
    settingSources: ['project'],
  },
});

​

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

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 ツールからも呼び出せませんが、そのファイルはディスク上に残り、通常のファイルツールでアクセスされる可能性があります。

​

実行中の Query で Skills を更新する

const { skills } = await q.reloadSkills();
renderSkills(skills);

​

カスタム Agent への 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 クイックリファレンス

​

戻り値リファレンス

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

​

ベストプラクティス

• skills は必要に応じて有効化：'all' は開発とデバッグ向け。エンドユーザー向けプロダクトでは通常、明示的なリストを渡すべきです。
• CLI 組み込み skill の動作が欲しければ自前で再現：SDK は simplify / security-review などをセッションに注入しません。必要なら plugin または setting sources の範囲で自前の SKILL.md を提供してください。
• skills をサンドボックスとして扱わない：セキュリティ境界はツールの許可/拒否リスト、権限コールバック、権限モード、サンドボックスの組み合わせで制御すべきです。
• UI に適したスナップショットを使う：initializationResult().skills / get_server_info()['skills'] は初期の発見リストであり、メインセッションで現在呼び出せる一覧ではありません。TypeScript では、実行中の Skill UI を q.reloadSkills().skills で置き換え、command UI を commands_changed で更新します。
• サブ Agent の skills は個別に管理：メインセッションの options.skills とは2つの独立したリストであり、相互に上書きしません。

​

現在の制限事項

• --disable-slash-commands は CLI がすべての slash-command skill を一括無効化する機能ですが、SDK は現在ファーストクラスの option を公開していません。非公開の透過経路への依存は推奨しません。
• settings.skillListingMaxDescChars、settings.skillListingBudgetFraction は SDK が透過的に渡す listing 予算制御フィールドです。現在の qodercli ではまだ listing 予算制御が実装されていないため、渡してもエラーにはなりませんが、挙動も変わりません。
• 実行時の Skill 更新は現在 TypeScript 専用です。Python SDK には client.supported_skills() の便利メソッドがないため、get_server_info()['skills'] から初期化時の発見リストを読み取ってください。