GitHub Copilot Custom Agents and Skills Extensibility Guide¶

Custom agents, skills, and plugins are GitHub Copilot's three extensibility layers — agents codify team workflows, skills teach Copilot specialized tasks via progressive disclosure, and plugins bundle everything into shareable packages.

Custom Agents¶

Define CUSTOM-AGENT-NAME.md files under .github/agents/ to create specialized agents with their own tools, MCP servers, and instructions. Agents become available in the coding agent on GitHub.com, coding agent in IDEs, and GitHub Copilot CLI.

Agent Skills¶

Agent Skills are SKILL.md folders containing instructions, scripts, and resources. Copilot auto-loads them when relevant using progressive disclosure — it reads skill metadata first, then loads actual scripts and templates only when needed to avoid context window bloat.

Skills surface as slash commands in chat. Available across Copilot coding agent, CLI, and VS Code.

The Agent Skills specification defines the open standard. The microsoft/skills repository provides Azure SDK-specific skills and plugin packages.

Prompt Files¶

Stored in .github/prompts/, prompt files define specialized prompts invocable via / commands. They support YAML frontmatter to specify which model to use and are source-controlled for team sharing.

Plugins¶

Plugins bundle MCP servers, agents, skills, and hooks into installable packages. Install from GitHub repos with npx skills add owner/repo. Plugins extend Copilot's capabilities — skills from plugins appear alongside local skills.

Plugin marketplace management (VS Code 1.113+): The Chat: Manage Plugin Marketplaces command lists configured marketplaces with options to browse, locate directories, and remove plugins. URL handler installation uses the format vscode://chat-plugin/install?source=<source>.

Custom Instructions¶

Repository instructions: copilot-instructions.md in .github/ applies to all requests in that repo
Path-specific instructions: NAME.instructions.md in .github/instructions/ applies only to matching file paths
AGENTS.md: Auto-detected in workspace root; supports subfolder-level instructions

See custom instructions in the GitHub docs.

Limitations¶

The extensibility layers have sharp edges that the official docs flag explicitly:

Skills silently fail to load when the name field contains invalid characters — slashes, colons, dots, or manually-added namespace prefixes like myorg/skillname cause the skill to be dropped without an error (VS Code: Use Agent Skills). The parent directory name must also match the name field exactly or the skill is not loaded.
Activation depends on description quality — Copilot reads the skill description to decide whether to load it, so vague descriptions cause Copilot to miss relevant invocations (VS Code: Use Agent Skills).
Instruction and skill bloat degrades adherence — skills stack on top of base instructions, and practitioners report that once combined instruction context gets long, the agent follows it less reliably (Your Agent Instructions Are Probably Making Things Worse). Keep individual skills narrow and prune instruction files aggressively.

Example¶

The following shows a minimal custom agent definition file and a companion skill, demonstrating how the two layers work together. The agent lives at .github/agents/release-engineer.md and declares which tools and MCP servers it may use; the skill lives at .github/skills/changelog/SKILL.md and is auto-loaded by Copilot when the task is relevant.

.github/agents/release-engineer.md

---
name: release-engineer
description: Automates release tasks — changelog generation, version bumping, and tag creation.
tools:
  - shell
  - file_edit
mcpServers:
  - url: https://mcp.example.com/github
    name: github
---

You are a release engineer agent. When asked to cut a release, you:
1. Run `git log --oneline <prev-tag>..HEAD` to collect commits.
2. Invoke the `/changelog` skill to produce the CHANGELOG entry.
3. Bump the version in `package.json` and commit with `chore(release): vX.Y.Z`.
4. Create and push a git tag.

.github/skills/changelog/SKILL.md

---
name: changelog
description: Generates a CHANGELOG entry from conventional commits.
---

Given a list of commits, group them by type (feat, fix, chore) and output a
Markdown section ready for insertion into CHANGELOG.md.

Scripts: generate-changelog.sh

Copilot reads only the skill metadata until /changelog is invoked, keeping context budget low. The agent's tools list restricts it to shell and file_edit, preventing it from accessing resources outside the release workflow.

Key Takeaways¶

Custom agents (CUSTOM-AGENT-NAME.md at .github/agents/) codify team-specific workflows with dedicated tools and instructions
Skills (SKILL.md) use progressive disclosure to teach Copilot specialized tasks without bloating context
Plugins bundle agents, skills, MCP servers, and hooks into installable packages
Three instruction layers: repository-wide, path-specific, and workspace-level via AGENTS.md