plugin-structure

Plugin Structure for Copilot CLI

Copilot CLI plugins follow a directory-based convention with automatic component discovery. No manifest file is required — understanding this structure enables creating well-organized, maintainable plugins.

Key concepts:

• Convention-based directory layout for automatic discovery
• Component-based organization (skills, agents, hooks, extensions)
• Relative path references
• Auto-discovered component loading

Directory Structure

Every Copilot CLI plugin follows this organizational pattern:

plugin-name/
├── skills/                   # Skills (files or subdirectories with SKILL.md)
│   └── skill-name/
│       └── SKILL.md         # Required for rich skills
├── agents/                   # Agent definitions (.agent.md files)
├── hooks/
│   └── hooks.json           # Event handler configuration
├── extensions/              # Extensions
└── README.md

Critical rules:

1. No manifest file: Copilot CLI plugins use directory conventions, not a plugin.json manifest
2. Component locations: All component directories (skills, agents, hooks) MUST be at plugin root level
3. Optional components: Only create directories for components the plugin actually uses
4. Naming convention: Use kebab-case for all directory and file names

Component Organization

Skills

Location: skills/ directory Format: .md files (simple) or subdirectories with SKILL.md (rich skills) Auto-discovery: All skill files and SKILL.md files load automatically

Example structure:

skills/
├── quick-lint.md             # Simple skill (single file)
├── api-testing/              # Rich skill (directory)
│   ├── SKILL.md
│   ├── scripts/
│   │   └── test-runner.py
│   └── references/
│       └── api-spec.md
└── database-migrations/
    ├── SKILL.md
    └── examples/
        └── migration-template.sql

SKILL.md format:

---
description: When to use this skill
version: 1.0.0
---

Skill instructions and guidance...