fabioc-aloha 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.