Skip to content

endorphin-ai/hasbrains-agent-kit / agent-engineering/skills/convert-to-copilot

convert-to-copilot

Verified

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 TypeLocationContainsExample
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

PhaseActionOutput
1Read agent, command, all skills{output_folder}/1-source-context.md
2Create .copilot_utils/{agent_name}/ directoriesdirectories on disk
3Build Copilot frontmatter{output_folder}/3-frontmatter.md
4Convert body: tracking, references, skill refs, memory{output_folder}/4-body.md
5Write {output_agent} + all .copilot_utils/{agent_name}/ filesfinal output files
6Validate against checklist{output_folder}/6-validation.md
7Print conversion reportconsole

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

ClaudeCopilot 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

ClaudeCopilot
opus"Claude Opus 4.5"
sonnet"Claude Sonnet 4.5"
haiku"Claude Haiku 4.5"
inheritomit 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

FieldRequiredNotes
descriptionYesSingle-quoted, 50–150 chars
toolsOptionalOmit = all tools; list for least-privilege
modelRecommendedFull name: 'Claude Sonnet 4.5'
nameOptionalDefaults to filename
targetOptional'vscode' or 'github-copilot'
inferOptionalfalse to require explicit argument
argument-hintOptionalVS Code only
handoffsOptionalVS 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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall