chat-participant-patterns

name	chat-participant-patterns
description	VS Code Chat API patterns.
lastReviewed	2026-04-30T00:00:00.000Z

Chat Participant Patterns Skill

VS Code Chat API patterns.

⚠️ Staleness Warning

Chat APIs evolve with VS Code releases. Last validated: March 2026 (VS Code 1.111+)

Check: Chat API, LM API, Tools API, AI Extensibility Overview, EXTERNAL-API-REGISTRY.md

---

When to Use Chat Participant vs. Skills/Tools

Approach	Use When	VS Code API
Chat Participant	Need full control of prompt + response, domain-specific @-mention	vscode.chat.createChatParticipant
LM Tool	Domain capability invoked automatically in agent sessions	vscode.lm.registerTool
Agent Skill (SKILL.md)	Domain knowledge embedded into any agent session (no code)	chat.useAgentSkills + SKILL.md file
MCP Server	Cross-platform tool providing data/actions to any MCP client	MCP SDK

→ Prefer Skills for domain knowledge. Reserve participants for full prompt orchestration.

---

Create Participant

// package.json contribution
"contributes": {
    "chatParticipants": [{
        "id": "my-ext.participant",
        "name": "myparticipant",
        "fullName": "My Participant",
        "description": "What can I help with?",
        "isSticky": true,
        "commands": [{ "name": "help", "description": "Get help" }]
    }]
}

// In activate()
const participant = vscode.chat.createChatParticipant('my-ext.participant', handler);
participant.iconPath = vscode.Uri.joinPath(context.extensionUri, 'icon.png');

Handler Signature

const handler: vscode.ChatRequestHandler = async (
    request: vscode.ChatRequest,
    context: vscode.ChatContext,
    stream: vscode.ChatResponseStream,
    token: vscode.CancellationToken
): Promise<IChatResult> => {
    // Handle request
};

Key Operations

Operation	Method
Stream text	stream.markdown()
Show progress	stream.progress()
Add button	stream.button()
File tree	stream.filetree()
Reference	stream.reference()
Inline anchor	stream.anchor()
Access history	context.history
Get references	request.references
Get model	request.model
Check command	request.command
Chat location	request.location

Response Types

// Markdown (supports CommonMark)
stream.markdown('# Title\n**bold** and _italic_');

// Code block with IntelliSense
stream.markdown('```typescript\nconst x = 1;\n```');

// Progress message
stream.progress('Processing...');

// Button (invokes VS Code command)
stream.button({ command: 'my.command', title: 'Run' });

// Command link in markdown
const md = new vscode.MarkdownString('[Run](command:my.command)');
md.isTrusted = { enabledCommands: ['my.command'] };
stream.markdown(md);

// File tree
stream.filetree([{ name: 'src', children: [{ name: 'app.ts' }] }], baseUri);

// Reference
stream.reference(vscode.Uri.file('/path/to/file.ts'));
stream.reference(new vscode.Location(uri, range));

LM Integration

const models = await vscode.lm.selectChatModels({ vendor: 'copilot' });
const response = await models[0].sendRequest(messages, {}, token);
for await (const chunk of response.text) {
    stream.markdown(chunk);
}

Tool Calling

// Using @vscode/chat-extension-utils library (recommended)
import * as chatUtils from '@vscode/chat-extension-utils';

const tools = vscode.lm.tools.filter(t => t.tags.includes('my-tag'));
const result = chatUtils.sendChatParticipantRequest(request, context, {
    prompt: 'System instructions here',
    responseStreamOptions: { stream, references: true, responseText: true },
    tools
}, token);
return await result.result;

Tool Registration

vscode.lm.registerTool('tool_name', {
    async invoke(options, token) {
        return new vscode.LanguageModelToolResult([
            new vscode.LanguageModelTextPart('result text')
        ]);
    }
});

Participant Detection (Auto-routing)

"chatParticipants": [{
    "id": "my-ext.participant",
    "disambiguation": [{
        "category": "my-domain",
        "description": "Questions about X domain",
        "examples": ["How do I do X?", "Explain Y concept"]
    }]
}]

Follow-up Provider

participant.followupProvider = {
    provideFollowups(result, context, token) {
        return [{ prompt: 'Tell me more', label: 'More details' }];
    }
};

Message History

// Get previous requests to this participant
const previousRequests = context.history.filter(
    h => h instanceof vscode.ChatRequestTurn
);

Best Practices

Do	Don't
Stream responses incrementally	Block until complete
Handle cancellation via token	Ignore cancellation token
Catch and handle errors	Let exceptions crash
Use progress for long operations	Leave user waiting silently
Limit to one participant per extension	Create multiple participants
Ask consent for costly operations	Auto-execute destructive actions

Chat Intent Routing QA Decision Table (PL2)

When a chat participant routes user intent to an action (muscle execution, file modification, or LLM judgment), evaluate the routing decision against this table. The goal: never silently auto-decide between a mechanical action and a semantic follow-up.

#	Check	Pass	Fail	Action on Fail
1	Mechanical vs semantic classification — handler knows whether the request needs script execution, LLM judgment, or both	Request classified as M (muscle), S (LLM-only), or H (hybrid with handoff)	Handler treats all requests the same way	Classify intent; route M to muscle, S to LLM, H to muscle-then-prompt
2	Hybrid handoff signal — when a muscle runs and produces artifacts, the chat response references the decision table for Phase 2	Response includes skill reference + table rows the LLM should evaluate	Muscle result returned as plain text with no follow-up guidance	Use skillPrompt() helper from muscleRunner.ts to generate Phase 2 prompt
3	No silent auto-decision — when multiple valid actions exist, participant surfaces the choice to the user	QuickPick, follow-up buttons, or explicit question before acting	Handler picks one action without user input	Add follow-up provider or QuickPick for ambiguous intents
4	Cancellation respected — long-running operations check CancellationToken	Token checked before each phase; early exit on cancellation	Operation runs to completion ignoring cancel	Add token.isCancellationRequested checks between phases
5	Error context preserved — when an operation fails, the error includes enough context for the user to retry or escalate	Error message includes: what was attempted, what failed, suggested next step	Generic "something went wrong" or raw exception text	Wrap errors with action context; suggest concrete recovery steps
6	Decision table reference in response — when the LLM makes a judgment, the response cites which decision table row matched	"Based on row N of [table name]: [rationale]"	LLM responds with freeform judgment and no table reference	Reference the specific skill + decision table in the system prompt

Current state of handler.ts: Minimal stub — delegates entirely to Copilot via workspace context. This is architecturally correct (Cardinal Rule I6: architecture doesn't depend on extension). The decision table applies when/if the handler gains intent-routing logic in the future.