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):

{ "operation": "write", "todoList": [{ "id": 1, "title": "Phase 1: ...", "status": "not-started" }] }

Per-phase updates:

{ "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