💡 ProTip: GitHub’s docs on agent skills and Claude Code’s skills docs are worth reviewing if you want the official mechanics behind activation.
Skill Structure and Activation 🪛
A Copilot skill is defined by a SKILL.md file. For repo-level skills, the structure looks like this:
.github/
|-- skills/
| `-- your-skill-name/
| `-- SKILL.md
The directory tree itself doesn't matter as much as when the agent activates it.
Only the skill’s metadata is evaluated initially. If the description matches the task, then the agent loads only the SKILL.md file and treats its contents as procedural guidance.
If you extend a skill with additional files, they are invisible unless explicitly referenced and deliberately loaded.
This separation is the entire value proposition of a skill:
| Before activation |
After activation |
| Operates on inferred repository patterns |
Executes defined procedural rules |
| Uses baseline instructions only |
Uses baseline instructions + skill guidance |
| Optimizes for general applicability |
Optimizes for task-specific behavior |
💡 ProTip: Copilot also checks .agents/skills and .claude/skills (globally and per repo). That makes cross-tool skill reuse feasible without duplicating logic unnecessarily.
Anatomy of SKILL.md 🧬
The SKILL.md file defines both activation metadata and execution guidance. The name and description are always visible to the agent. The rest of the file becomes active only after invocation.
Skills can mirror:
- a custom agent
- a reusable prompt
- a custom instruction
- or a hybrid of all three
Below is a simplified example designed to activate only when editing a CHANGELOG.md file:
---
name: changelog-writer
description: Rewrite changelog entries with cheeky, narrative flair following project conventions. Use this when asked to rewrite or update CHANGELOG.md entries.
---
## Execution Workflow
When invoked to rewrite a changelog entry:
1. **Read CHANGELOG.md** to extract tone and structure
2. **Identify release type and breaking changes**
3. **Select emoji(s)** appropriate to release theme
4. **Craft italicized opening quote**
5. **Write body content**
6. **Validate links, formatting, and breaking-change visibility**
The key observation here isn’t the workflow itself. It’s the activation boundary. Without activation, none of that logic exists in the agent’s working memory.
🦄 The full version lives in my awesome-github-copilot repo if you want to inspect it more closely.
One Sentence Version 🐎
If a behavior must apply consistently, it belongs in repository or global instructions.
If a behavior is conditional, procedural, or task-specific, it belongs in a skill.
A skill should feel like a tool you occasionally reach for—not a consistent rule the agent has to rediscover on its own every session. However, once instructions grow large enough, they stop acting like baseline context and start acting like noise. At that point trimming becomes more valuable than adding.
In case it helps, this is the prompt I use when reducing instruction bloat for newer LLMs:
Review #copilot-instructions.md and optimize for AI consumption. Remove information that can be inferred from repository structure or code usage. Eliminate duplication and anything that does not improve clarity or reduce ambiguity. Preserve personality and tone directives. The final file should prioritize agent understanding over human readability.
💡 ProTip: Back up the original first. Agents are confident editors and occasionally confident editors erase the one line that mattered most.
🛡️ Behind the Curtain
I wrote this post, and ChatGPT helped like a well-defined skill. I made the final calls—it activated when needed and stayed out of the way otherwise.