# Skills in Copilot CLI

Package the add-migration procedure as a Copilot CLI agent skill with a bundled check script and a reference file, invoked automatically or with /add-migration.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/skills/copilot-cli

This page covers Copilot CLI. The same skill folders also work in the Copilot cloud agent, code review and agent mode in some IDEs.

## At a glance

| | Copilot CLI |
|---|---|
| Term | Agent skills |
| Configured in | `.github/skills/<name>/SKILL.md` (project), `~/.copilot/skills/<name>/SKILL.md` (personal) |
| Loads / runs | Copilot picks a skill from its name and description, or you call `/skill-name`; then `SKILL.md` is injected into context |
| Scope & precedence | Project, personal, plugin and more; first found wins for duplicate names |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Create the skill folder | `.github/skills/add-migration/` |
| 2 | Write `SKILL.md` (below) | `.github/skills/add-migration/SKILL.md` |
| 3 | Add the check script (shown on the [example scenario](https://ai-sw-factory.mellicci.dev/fundamentals/skills/example-scenario)) | `scripts/check-migration.sh` |
| 4 | Add the Drizzle conventions | `references/drizzle-conventions.md` |
| 5 | Run `/skills reload`, then `/skills info add-migration` | Terminal |

```markdown
---
name: add-migration
description: "Change the ticket-service database schema safely: edit src/db/schema.ts, generate a migration with pnpm db:generate, and verify it. Use for any new table, column or index."
---

1. Run `ls src/db/migrations` to see the existing migrations.
2. Read `references/drizzle-conventions.md`.
3. Edit `src/db/schema.ts` for the change requested in the prompt.
4. Run `pnpm db:generate`. Never edit files in `src/db/migrations/`.
5. Run `scripts/check-migration.sh` from this skill's directory and fix what it reports.
6. Summarize the new migration file and its SQL.
```

Invoke it with `Use the /add-migration skill to add a priority column to tickets`, or describe the task and let Copilot choose.

## Specifics

### Locations and discovery

| Location | Kind |
|---|---|
| `.github/skills/` | Project |
| `.agents/skills/`, `.claude/skills/` | Project (alternative and Claude-compatible) |
| Parent `.github/skills/` | Inherited (monorepo) |
| `~/.copilot/skills/`, `~/.agents/skills/` | Personal |
| Plugin directories | Plugin |
| `COPILOT_SKILLS_DIRS`, `skillDirectories` setting | Extra directories |
| `.github/skills/` under `--add-dir` / `/add-dir` | Added root (trusted like project skills) |
| Bundled with the CLI, org/enterprise | Built-in (lowest priority), remote |

Order is top to bottom: the first skill found wins. `ignoredSkillsLocations` excludes directories. Each skill is a subdirectory with a file named `SKILL.md`; use lowercase names with hyphens.

| Command | What it does |
|---|---|
| `/skills list`, `/skills info NAME` | List skills; show details and location |
| `/skills add`, `/skills remove` | Add or remove a skill or skill directory |
| `/skills reload` | Pick up new files without restarting |
| `/skills` | Opens the skills view to enable or disable a skill |
| `copilot skill list\|add\|remove\|enable\|disable` | Same operations outside a session |

Relations: a plugin can ship skills, removed by managing the plugin. The documentation doesn't specify how custom agents use skills.

### SKILL.md fields

| Field | Required | Notes |
|---|---|---|
| `name` | Yes | Max 64 characters; letters, numbers, hyphens, underscores, dots, colons, spaces. Usually matches the directory |
| `description` | Yes | What it does and when to use it; max 1024 characters |
| `argument-hint` | No | Hint shown in the skill picker, for example `"[target] [mode]"` |
| `allowed-tools` | No | Tools allowed without asking while the skill is active; `"*"` for all |
| `user-invocable` | No | Allow `/name`; default `true` |
| `disable-model-invocation` | No | Stop automatic use; default `false` |
| `license` | No | License that applies to the skill |

### Invocation and arguments

| Mode | How |
|---|---|
| Automatic | Copilot matches your prompt to the skill description |
| Explicit | `/add-migration ...` or name it in a prompt: `Use the /add-migration skill to ...` |

The documentation doesn't specify argument placeholders (nothing like `$ARGUMENTS`); `argument-hint` only labels the picker. The requested change comes from your prompt text, which is why the skill says "the change requested in the prompt".

### Scripts and pre-injected data

| Topic | Behavior |
|---|---|
| Bundled files | All files in the skill directory are made available when the skill runs; the instructions reference them |
| Running `check-migration.sh` | A shell call; Copilot asks for approval unless the tool is allowed |
| Pre-approval | `allowed-tools: shell` skips the prompt for this skill; only for reviewed skills |
| Pre-injection | The documentation doesn't specify command pre-injection |

Fallback: step 1 tells the model to run `ls src/db/migrations` itself, so it decides when to fetch live data.

### Context cost and visibility

| Item | Detail |
|---|---|
| Matching | Name and description decide whether Copilot uses the skill, so keep the description short |
| On use | The `SKILL.md` body, injected when the skill is invoked |
| Size limit | The documentation doesn't specify one for `SKILL.md`; only `description` is capped |
| Inspect | `/skills list`, `/env`, `/context` |
| Turn off | `/skills` or `copilot skill disable NAME`; `disabledSkills` setting |
| Retrieval | `dynamicRetrieval.skills: false` disables embeddings-based retrieval of skills |

## Gotchas

- Explicit calls are `/name`, not `$name`; the automatic path depends entirely on the description, so write "Use for any new table, column or index" into it.
- `allowed-tools: shell` removes the approval step for every terminal command while the skill is active. Review the skill and its scripts before granting it.
- New skills are not seen by a running session until `/skills reload`.
- Project skills win over personal skills of the same name, and a `.claude/skills` folder is read too, so duplicates across locations can shadow each other.
- Skills guide the model; they don't enforce. To guarantee `src/db/migrations/` stays untouched, add a [hook](https://ai-sw-factory.mellicci.dev/fundamentals/hooks/copilot-cli) or a `--deny-tool` rule.