--- name: make-custom-agent description: 'Create custom GitHub Copilot agents. Use when asked to create, scaffold, or configure a custom agent, declarative agent, or @-invokable chat participant for GitHub Copilot.' --- # Create Custom Agent This skill guides you through creating a custom GitHub Copilot agent — an `@`-invokable chat participant that extends Copilot with domain-specific expertise. Custom agents are distinct from Agent Skills: skills provide reusable instructions loaded on demand, while agents own the full conversational interaction and can orchestrate tools, call APIs, and maintain their own prompt strategies. ## When Not to Use - Adding reusable, invokable workflows — use Agent Skills (`.agents/skills/`) instead - Adding background coding guidelines — use file-based instructions (`.github/instructions/`) instead - Adding project-wide context for Copilot — use `.github/copilot-instructions.md` instead - Creating reusable prompts — use .prompt.md instead ## Workflow ### Step 1: Choose the agent type | Type | Location | Best for | |---|---|---| | Declarative (prompt file) | `.github/agents/.md` | Simple prompt-driven cross-surface agents with no code | | Extension-based (chat participant) | VS Code extension project | Full control, tool calling, VS Code API access | | GitHub App (Copilot Extension) | Hosted service + GitHub App | Cross-surface agents (github.com, VS Code, Visual Studio) | If the agent only needs a scoped system prompt and doesn't require custom code, start with a declarative agent. ### Step 2: Create a declarative agent (prompt file) Declarative agents are Markdown files in `.github/agents/`. VS Code and GitHub Copilot discover them automatically. ``` .github/agents/ └── .md # Agent definition ``` Template: ```markdown --- name: my-agent description: A short description of what this agent does and when to use it. --- # You are an expert in . Your job is to: - - ## Guidelines - - ## Workflow 1. 2. ## Constraints - - ``` Supported frontmatter fields: | Field | Required | Description | |---|---|---| | `name` | Yes | Lowercase, hyphens allowed. Used for `@`-mention. | | `description` | Yes | What the agent does and when to use it. Shown in the participant list. | | `target` | No | Target environment: `vscode` or `github-copilot` (defaults to both) | | `tools` | No | List of allowed tools/tool sets | | `model` | No | LLM name or prioritized array of models | | `user-invocable` | No | Show in agents dropdown (default: true) | | `disable-model-invocation` | No | Prevent subagent invocation (default: false) | | `mcp-servers` | No | MCP server configs for GitHub Copilot target | | `metadata` | No | Key-value mapping for additional arbitrary metadata. | | `argument-hint` | No | Hint text guiding user interaction (VS Code only) | | `agents` | No | List of allowed subagents (`*` for all, `[]` for none, VS Code only) | | `handoffs` | No | List of next-step agent transitions (VS Code only) | Tips for instructions: - Use Markdown links to reference other files - Reference tools with `#tool:` syntax - Be specific about agent behavior and constraints ### Step 3: Configure tools Specify which tools the agent can use: ```yaml tools: - search # Built-in tool - fetch # Built-in tool - codebase # Tool set - myServer/* # All tools from MCP server ``` Common tool patterns: - **Read-only agents**: `['search', 'fetch', 'codebase']` - **Full editing agents**: `['*']` or specific editing tools - **Specialized agents**: Cherry-pick specific tools ### Step 4: Add handoffs (optional, VS Code only) Configure transitions to other agents: ```yaml handoffs: - label: Start Implementation agent: implementation prompt: Implement the plan outlined above. send: false model: GPT-5.2 (copilot) ``` Handoff fields: - `label`: Button text displayed to user - `agent`: Target agent identifier - `prompt`: Pre-filled prompt for target agent - `send`: Auto-submit prompt (default: false) - `model`: Optional model override for handoff ### Step 5: Create an extension-based chat participant (VS Code only) For full control, implement a VS Code extension with a chat participant: 1. **Define the participant** in `package.json`: ```json "contributes": { "chatParticipants": [ { "id": "my-extension.my-agent", "name": "my-agent", "fullName": "My Agent", "description": "Short description shown in chat input", "isSticky": false, "commands": [ { "name": "explain", "description": "Explain the selected code" } ] } ] } ``` 2. **Register and implement the request handler** in `extension.ts`: ```typescript export function activate(context: vscode.ExtensionContext) { const agent = vscode.chat.createChatParticipant('my-extension.my-agent', handler); agent.iconPath = vscode.Uri.joinPath(context.extensionUri, 'icon.png'); } const handler: vscode.ChatRequestHandler = async ( request: vscode.ChatRequest, context: vscode.ChatContext, stream: vscode.ChatResponseStream, token: vscode.CancellationToken ) => { const model = request.model; const messages = [ vscode.LanguageModelChatMessage.User(request.prompt) ]; const response = await model.sendRequest(messages, {}, token); for await (const fragment of response.text) { stream.markdown(fragment); } }; ``` 3. **Declare the extension dependency** in `package.json`: ```json "extensionDependencies": ["github.copilot-chat"] ``` 4. **Add tool calling (optional)** Agents can invoke language model tools registered by other extensions: ```typescript const tools = vscode.lm.tools.filter(tool => tool.tags.includes('my-domain')); const result = await chatUtils.sendChatParticipantRequest(request, context, { prompt: 'You are an expert in .', tools, responseStreamOptions: { stream, references: true, responseText: true } }, token); return await result.result; ``` ### Step 6: Create a GitHub App (Copilot Extension) for cross-surface availability (optional) If the agent should be available on GitHub.com, Visual Studio, JetBrains, and VS Code simultaneously, implement a GitHub App that acts as a Copilot Extension. The app registers a webhook endpoint, receives chat requests, and streams responses back. Key considerations: - The GitHub App must be installed on the user's account or organization - Responses are streamed via Server-Sent Events (SSE) - Use the [GitHub Copilot Extensions documentation](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions) for the full integration guide - For VS Code-specific features (editor access, file trees, command buttons), prefer an extension-based participant instead ### Step 7: Validate After creating or modifying an agent, verify: - [ ] `name` is lowercase, uses hyphens (no spaces), and is unique - [ ] `description` clearly describes what the agent does and when to invoke it - [ ] Frontmatter YAML is valid (no syntax errors) - [ ] Declarative agent file is in `.github/agents/` - [ ] Tools list contains only available tools - [ ] Extension-based agent: participant ID matches in `package.json` and `createChatParticipant` call - [ ] Agent does not duplicate functionality of built-in agents (`@workspace`, `@vscode`, `@terminal`) - [ ] Handoff agent names match existing agents - [ ] Agent instructions don't include secrets, tokens, or internal URLs ## Common Pitfalls | Pitfall | Solution | |---------|----------| | Agent name conflicts with built-in participants | Use a unique prefix (domain name) | | Description is too vague | Include specific keywords users would naturally say | | System prompt is too long | Keep instructions to essential behaviors; move reference material to Agent Skills | | Agent requires VS Code API but is authored as declarative | Switch to extension-based participant | | Using `isSticky: true` unnecessarily | Only set sticky if the agent should persist between turns by default | | No `extensionDependencies` on `github.copilot-chat` | Add it; otherwise the contribution point may not be available | | Agent invoked as subagent unexpectedly | Set `disable-model-invocation: true` | | Subagent appears in the dropdown | Set `user-invocable: false` | ## References - [VS Code Chat Participant API](https://code.visualstudio.com/api/extension-guides/ai/chat) - [VS Code AI Extensibility Overview](https://code.visualstudio.com/api/extension-guides/ai/ai-extensibility-overview) - [VS Code Extension Samples – chat-sample](https://github.com/microsoft/vscode-extension-samples/tree/main/chat-sample) - [GitHub Copilot Extensions documentation](https://docs.github.com/en/copilot/building-copilot-extensions/about-building-copilot-extensions) - [GitHub Copilot Custom agents configuration](https://docs.github.com/en/copilot/reference/custom-agents-configuration) - [Agent Skills Specification](https://agentskills.io/specification) - [make-skill](../make-skill/SKILL.md) - [make-instructions](../make-instructions/SKILL.md)

make-custom-agent

Install this skill

Comments