Authoring Guide

Build skills and agents that work across Claude Code and Copilot CLI

Platforms

Two Agent Systems

One plugin, two platforms -- Claude Code and VS Code Copilot consume the same files differently.

Aspect	Claude Code	Copilot CLI
File naming	`kebab-case.md`	`PascalCase.agent.md`
Invocation	`Task(subagent_type: “name”)`	`@AgentName` in chat
Tools format	`Read, Glob, Grep, Bash`	`read, search, codebase, agent`
MCP format	`mcp__server__tool_name`	`’server/tool_name’`
Model	`sonnet / opus / haiku`	Full model string or array
Sub-agents	Flat (Task tool)	`agents:` field (nested, VS Code 1.113+)
Handoffs	N/A	`handoffs:` buttons
Model format	`sonnet / opus / haiku`	String or array (fallback chain)
Memory	`memory: project`	Not supported

Key Insight

VS Code reads Claude’s formats (.claude/agents/, .claude/skills/). Claude does NOT read VS Code’s formats. Put shared agents in .claude/agents/ for both platforms.

Skills

Skill Authoring

YAML frontmatter + markdown body = a reusable command.

Complete skill frontmatter

---
name: my-skill                    # Required. Becomes /plugin:my-skill command
description: What it does...      # Required. Used for auto-invocation matching
argument-hint: "<expected args>"  # Optional. UI placeholder text
context: fork                     # Optional. "fork" = isolated subagent execution
agent: my-agent                   # Optional. Agent for the fork
disable-model-invocation: false   # Optional. Prevent auto-invocation
---

Inline Skill

No context: or agent:. Runs directly in the user’s conversation. Good for most skills.

Forked Skill

Uses context: fork + agent:. Creates an isolated subagent. Main context stays clean from large MCP output.

Coordinator Skill

Uses Task tool in the body. Delegates to executor agents. Should ONLY delegate — never implement directly.

$ARGUMENTS

$ARGUMENTS is replaced with whatever the user typed after the command. Example: /dx-req 2416553 sets $ARGUMENTS = “2416553”.

Agents

Agent Authoring

Define who does the work -- model tier, tools, and permissions.

Claude Code agent frontmatter

---
name: my-agent
description: What it does
model: sonnet              # sonnet | opus | haiku | inherit
tools: Read, Write, Bash   # OMIT to inherit ALL tools (recommended for MCP)
disallowedTools: Write     # Block specific tools while inheriting rest
permissionMode: default    # default | acceptEdits | bypassPermissions
maxTurns: 30
memory: project            # user | project | local
isolation: worktree        # Isolated git worktree
---

The #1 Gotcha: Tool Inheritance

If you specify tools:, the agent can ONLY use those listed tools. MCP tools are BLOCKED unless explicitly listed. Either omit tools: entirely to inherit everything (recommended for MCP-dependent agents), or use disallowedTools: to block specific tools while keeping everything else.

Model Tier Strategy

Opus -- Deep Reasoning

Architecture, planning, code review, security analysis, root cause diagnosis. Cost: ≈15x haiku.

Sonnet -- Standard Work

Implementation, MCP coordination, PR review, AEM inspection. Cost: ≈5x haiku.

Haiku -- Fast Ops

File lookups, doc search, git commits, config reads. Cost: 1x (baseline).

Structure

File Structure and Naming

Where files live and how they are discovered.

Plugin directory layout

plugin/
├── .claude-plugin/plugin.json   # Plugin manifest (both platforms)
├── .mcp.json                    # MCP server config
├── agents/                      # Agent definitions (*.md with YAML frontmatter)
├── skills/                      # Skill directories (*/SKILL.md)
├── rules/                       # Default prompt templates
├── hooks/                       # Plugin hooks (hooks.json)
├── data/                        # Seed files copied to project by init
├── shared/                      # Reference files read by skills
└── templates/                   # Init-time file templates
  ├── rules/                   #   Convention rules -> .claude/rules/
  ├── instructions/            #   Detailed docs -> .github/instructions/
  └── agents/                  #   Copilot agents -> .github/agents/

Agent File Naming

Claude Code: agents/dx-code-reviewer.md
Copilot (.github): DxCodeReview.agent.md
Copilot CLI (plugin): Reads Claude format directly

Plugin Manifest

Never add agents or skills fields for default directories — this breaks Claude Code with a Zod validation error. Both platforms auto-discover agents/ and skills/ when these fields are omitted.

Config

Config-Driven Development

Skills never hardcode project-specific values.

Instead of	Use
`https://myorg.visualstudio.com/`	`scm.org` from config
`mvn clean install`	`build.command` from config
`/apps/myproject/components/`	`aem.component-path` from config
`http://localhost:4502`	`aem.author-url` from config
`develop`	`scm.base-branch` from config

Three-Layer Override System

.ai/rules/<topic>.md (full replacement) > config.yaml overrides: (quick tweaks) > plugin defaults (rules/*.md). Projects can also shadow entire skills by creating .claude/skills/<name>/SKILL.md.

Copilot

Copilot Agent Templates

Translating Claude agents for VS Code Chat.

Claude Code	Copilot Template
`name: dx-code-reviewer`	`name: DxCodeReview` (PascalCase)
`model: opus`	Omit (VS Code selects model)
`tools: Read, Glob, Grep, Bash`	`tools: [read, search, search/codebase]`
`mcp__ado__search_code`	`’ado/search_code’`
Task tool delegation	`agents: [‘sub-agent-name’]` + `tools: [agent]`
`ToolSearch(“+AEM”)`	Remove — Copilot auto-loads MCP tools
`model: opus`	`model: [‘claude-opus-4-5’, ‘claude-sonnet-4-5’]` (fallback array)

Handoffs

Copilot agents support handoffs: for workflow navigation buttons. Design them to follow natural workflow progression. Cross-plugin handoffs are supported — AEM agents can hand off to DX agents.

Checklist

PR Checklist

Verify before merging a new skill or agent.

Before You Merge

Skill has SKILL.md with proper frontmatter
No hardcoded project values (grep for org URLs, paths, names)
Config fields documented if new ones are introduced
Skill/agent catalog docs updated
Shell scripts are executable (chmod +x)
Tested with a real project
Copilot template added if user-facing