convert-to-copilot · git:20260923.b8444e7 · 2026-09-23 · sha256 688b86a895639182
convert-to-copilot git:20260923.b8444e7A
Immutable. This exact content is served forever at /api/v1/blob/688b86a895639182.
---
name: convert-to-copilot
description: "This skill should be used when converting a Claude Code agent (+ its launch command + its skills) into a single GitHub Copilot agent (.github/agents/*.agent.md) with supporting context files under .copilot_utils/{agent_name}/. Load when someone says 'convert to copilot', 'make copilot agent', 'copilot version of this agent', 'port this agent to copilot', or when /convert-to-copilot is invoked with an agent file path."
---
# Convert Claude Code → GitHub Copilot Agent
Converts a Claude Code agent + command + skills into a `.github/agents/*.agent.md` with supporting
files in a per-agent `.copilot_utils/{agent_name}/` directory.
---
## Canonical Output Structure
```
.github/
└── agents/
└── {agent_name}.agent.md ← single merged file (agent + command)
.copilot_utils/
└── {agent_name}/
├── context/ ← WHAT to use (knowledge, conventions, reference)
│ └── {skill}.md
└── trees/ ← HOW to decide (branching, if/else logic)
└── {skill}.md
```
**External guide:** https://github.com/endorphin-ai/vs-code-copilot-agents/blob/main/COPILOT_AGENTS_GUIDE.md
---
## Three-File Separation Principle
Every file has exactly one role:
| File Type | Location | Contains | Example |
| ----------- | -------------------------------------- | --------------------------------------------- | ------------------------------------------------ |
| **Agent** | `.github/agents/` | WHAT to do — workflow, phases, orchestration | "Read file, apply tree, validate, create output" |
| **Tree** | `.copilot_utils/{agent_name}/trees/` | HOW to decide — if/else branching logic | "If label contains X → use path Y" |
| **Context** | `.copilot_utils/{agent_name}/context/` | WHAT to use — reference info, patterns, rules | "Available scaffolds: A, B, C" |
**NEVER embed knowledge or decision logic in the agent body.** Reference files instead:
- Decisions → `**Apply tree:** .copilot_utils/{agent_name}/trees/{file}.md`
- Reference → `**Reference:** .copilot_utils/{agent_name}/context/{file}.md`
---
## Variables
```
{agent_file} = $ARGUMENTS (path to Claude agent .md file)
{command_file} = (path to Claude command .md — ask if not provided)
{agent_name} = (extracted from agent frontmatter `name` field)
{output_agent} = .github/agents/{agent_name}.agent.md
{output_dir} = .copilot_utils/{agent_name}
{trees_dir} = .copilot_utils/{agent_name}/trees
{knowledge_dir} = .copilot_utils/{agent_name}/context
{output_folder} = .copilot-convert-results
```
---
## External Reference (fetch first)
```
WebFetch https://raw.githubusercontent.com/endorphin-ai/vs-code-copilot-agents/main/COPILOT_AGENTS_GUIDE.md
```
Authoritative Copilot spec. If anything in this skill conflicts with the guide, the guide wins.
---
## ALWAYS_DO
- **ALWAYS** fetch the external guide before starting conversion
- **ALWAYS** read the full agent, command, and every linked skill before writing any output
- **ALWAYS** merge command description triggers and `argument-hint` into the Copilot agent `description` field
- **ALWAYS** use `manage_todo_list` with `"operation": "write"` + full todoList before any work starts — bare JSON arrays fail
- **ALWAYS** drop `color`, `memory`, `isolation`, `skills`, `allowed-tools` from converted frontmatter
- **ALWAYS** validate every `.copilot_utils/{agent_name}/` path referenced in the body resolves to a real file
## NEVER_DO
- **NEVER** create `.prompt.md`, `.instructions.md`, or `.github/skills/` — Copilot uses a single merged agent file
- **NEVER** use `"fetch"` in `tools[]` — the correct alias is `"web"`
- **NEVER** embed decision logic or knowledge reference content inline in the agent body — always reference the file
- **NEVER** call `manage_todo_list` with a bare JSON array — always include `"operation": "write"`
- **NEVER** preserve `color`, `memory`, `isolation`, `skills`, `allowed-tools` fields in converted frontmatter
---
## Progress Tracking (mandatory)
```
TaskCreate(subject="Phase 1: Read all source files", status="pending")
TaskCreate(subject="Phase 2: Scaffold output directories", status="pending")
TaskCreate(subject="Phase 3: Build agent frontmatter", status="pending")
TaskCreate(subject="Phase 4: Convert agent body", status="pending")
TaskCreate(subject="Phase 5: Write output files", status="pending")
TaskCreate(subject="Phase 6: Validate", status="pending")
TaskCreate(subject="Phase 7: Conversion report", status="pending")
```
---
## Phase Overview
| Phase | Action | Output |
| ----- | ----------------------------------------------------------------- | ------------------------------------- |
| 1 | Read agent, command, all skills | `{output_folder}/1-source-context.md` |
| 2 | Create `.copilot_utils/{agent_name}/` directories | directories on disk |
| 3 | Build Copilot frontmatter | `{output_folder}/3-frontmatter.md` |
| 4 | Convert body: tracking, references, skill refs, memory | `{output_folder}/4-body.md` |
| 5 | Write `{output_agent}` + all `.copilot_utils/{agent_name}/` files | final output files |
| 6 | Validate against checklist | `{output_folder}/6-validation.md` |
| 7 | Print conversion report | console |
Phases 1–3: `references/conversion-phases.md`
Phase 4: `references/conversion-body.md`
Phases 5–7: `references/conversion-output.md`
---
## Key Conversion Rules
### Skill → copilot_utils Mapping
| Skill content type | Destination |
| ---------------------------------------------- | -------------------------------------- |
| SKILL.md — knowledge, conventions, reference | `{knowledge_dir}/{skill}.md` |
| SKILL.md — decision trees, "if X then Y" logic | `{trees_dir}/{skill}.md` |
| templates, schemas, output formats | `{knowledge_dir}/{skill}-templates.md` |
| example files | `{knowledge_dir}/{skill}-examples.md` |
| shell scripts (`.sh`), python (`.py`) | project `scripts/` or tool call inline |
**Classification rule:**
- "When you see X, do Y" / branching / diagnosis → **trees/**
- "Here is how things work, here are conventions" → **context/** (knowledge)
- Skill has both → copy full file to **context/**, extract decision sections to **trees/**
### Tool Mapping (quick reference)
| Claude | Copilot `tools[]` |
| ----------------------- | ---------------------------------- |
| Read | `"read"` |
| Write / Edit | `"edit"` |
| Bash | `"execute"` |
| Grep / Glob | `"search"` |
| WebFetch / WebSearch | `"web"` ⚠️ NOT `"fetch"` |
| TaskCreate / TaskUpdate | `"todo"` |
| Agent (sub-agent) | `"agent"` |
| Jira MCP | `"atlassian/*"` or explicit mcp ID |
| GitHub MCP | `"github/*"` |
Full table + wildcards + execute variants: `references/tool-mapping.md`
### Model Expansion
| Claude | Copilot |
| --------- | ------------------------ |
| `opus` | `"Claude Opus 4.5"` |
| `sonnet` | `"Claude Sonnet 4.5"` |
| `haiku` | `"Claude Haiku 4.5"` |
| `inherit` | omit or use most capable |
### manage_todo_list Format
Initial setup (one call before any work):
```json
{ "operation": "write", "todoList": [{ "id": 1, "title": "Phase 1: ...", "status": "not-started" }] }
```
Per-phase updates:
```json
{ "operation": "update", "updates": [{ "id": 1, "status": "in-progress" }] }
{ "operation": "update", "updates": [{ "id": 1, "status": "completed" }] }
```
### `handoffs` — VS Code sub-agent delegation
When Claude agent spawns sub-agents (`Task(subagent_type=...)`), convert based on `target`:
- `target: 'vscode'` → use `handoffs` in frontmatter
- `target: 'github-copilot'` → use `runSubagent()` in body
Full patterns: `references/advanced-patterns.md` and `references/advanced-subagents.md`
---
## Frontmatter Rules
| Field | Required | Notes |
| --------------- | ----------- | ------------------------------------------ |
| `description` | **Yes** | Single-quoted, 50–150 chars |
| `tools` | Optional | Omit = all tools; list for least-privilege |
| `model` | Recommended | Full name: `'Claude Sonnet 4.5'` |
| `name` | Optional | Defaults to filename |
| `target` | Optional | `'vscode'` or `'github-copilot'` |
| `infer` | Optional | `false` to require explicit argument |
| `argument-hint` | Optional | VS Code only |
| `handoffs` | Optional | VS Code only — sub-agent delegation |
Drop from Claude: `color`, `memory`, `isolation`, `skills`, `allowed-tools`
---
## Validation Checklist
Before writing any output file, verify:
- [ ] `{output_agent}` exists with `description` (50-150 chars, single-quoted)
- [ ] `tools` array uses correct aliases (`"web"` not `"fetch"`, `"todo"` not `"task"`)
- [ ] `description` contains trigger phrases from original command
- [ ] No separate command / prompt / instruction file was created
- [ ] Progress tracking uses `manage_todo_list` with `operation: write` format
- [ ] Every `.copilot_utils/{agent_name}/` path referenced in body resolves to a real file
- [ ] Agent body references knowledge via `**Reference:**` syntax (not embedded inline)
- [ ] Agent body references trees via `**Apply tree:**` syntax (not embedded inline)
- [ ] `handoffs` present when VS Code + sub-agents; `runSubagent()` when GitHub Copilot + sub-agents
- [ ] Agent body ≤ 30,000 characters
---
## References
- `references/conversion-phases.md` — phases 1–3: reading sources, scaffold, frontmatter build
- `references/conversion-body.md` — phase 4: full body conversion rules (task tracking, skill refs, memory)
- `references/conversion-output.md` — phases 5–7: write files, validate, conversion report
- `references/tool-mapping.md` — full tool/model tables, frontmatter fields, wildcards
- `references/advanced-patterns.md` — reference syntax, dynamic params, variable flow, execution strategy
- `references/advanced-subagents.md` — handoffs, runSubagent, parallel ops, return format, manage_todo_list
- `examples/pr-reviewer.md` — complete worked example
- `scripts/convert-agents.sh` — scaffold script (structure only, no content transformation)
- `assets/copilot-agent-template.md` — Copilot agent frontmatter template
- External: https://github.com/endorphin-ai/vs-code-copilot-agents/blob/main/COPILOT_AGENTS_GUIDE.md