The description does the triggering

Start from a concrete skill: a folder named audit-event/ with a SKILL.md inside, frontmatter name: audit-event and a description beginning “Use when recording a significant event through shared-lib’s audit helper - e.g. approval requested or granted” (shared-lib is the course’s illustrative internal library, imported by about a dozen services; the skill was built earlier in this chapter, sitting in a location Copilot scans, such as .github/skills/; the full description adds a second sentence about the required shape and fields). It is on disk and well-formed. Whether Copilot ever reaches for it comes down to a single line: that description. This is the difference between a skill and a manually invoked prompt, and it is easy to write a perfect procedure that never runs - the matcher never recognizes a moment for it.

How a skill gets chosen

Copilot does not load every skill into every request; that would bury the model in irrelevant procedures. It scans the available skills’ descriptions against the task in front of it and pulls in the ones that match (description-based discovery as documented, as of September 2026 - the Agent Skills documentation covers the current behavior). The body of the skill - your five steps - only enters the picture after the description has earned its way in. So the description is not documentation. It is the matcher. It has to say, clearly enough for the model to recognize, “this is the situation I am for.”

That is why the field reads best as a trigger condition, phrased as “use this when”:

Use when recording a significant event through shared-lib’s audit helper - e.g. approval requested or granted.

Compare a description that merely summarizes the skill:

Helper for audit events.

Both describe the same file. Only the first tells Copilot the circumstance - a task about recording an event through the audit helper - in words it can match against a real request like “add an approval.granted event when the second approver signs off.” The vague version names a topic; the good version names a moment. Name the moment.

The contrast with manual invocation

This is the line separating the invoked container from the model-invoked one:

• A prompt file is manually invoked. You type its slash command; nothing happens until you reach for it - you are the trigger. Prompt files run only in VS Code’s Local harness, and skills are the route for other harnesses (as of October 2026; the prompt-files chapter covers it), but the contrast still explains the control difference: good when you know the right moment and want explicit control.
• A skill is model-invoked. You never type its name. Copilot reads the descriptions, recognizes that the task at hand is about recording an audit event, and applies the skill on its own. Good when the agent should recognize the moment - including moments you would forget to flag by hand.

The audit-event convention is squarely the second kind. The problem you started with was re-explaining the convention whenever work touched an audited event; a prompt file would leave you carrying the burden of remembering to invoke it. A skill with a sharp description fixes it for real: when a task in orders-service or shared-lib (the skill is committed to each repo’s .github/skills/) is about recording an event, Copilot can pull the convention in itself, before you have said a word about it - and when it does not, first check the surface supports skills and the folder sits where Copilot scans; only then is the description the suspect.

Seen this before

If you have taken the Claude Code or Codex course on this site, this principle will feel familiar - there too, the skill’s description is what makes the agent reach for it. That is not a coincidence. It is the same standard, which is where this chapter ends.

The test

You will know the description is right when you stop thinking about the skill. Ask Copilot to add the approval.granted event without mentioning the convention, and watch whether the resulting code follows the team’s shape - dotted lowercase name, the helper, the required fields, recorded after success. If it does, the description matched and the skill fired on its own. If it does not - and the skill sits where Copilot scans, on a surface that supports skills - the description was too vague to recognize the moment; sharpen it toward “use this when” and try again.

One skill, two repos, invoked automatically where the current Copilot surface supports it. The last thing to see is how far that one file reaches - because the format is shared beyond Copilot, with support depending on each tool and version. Next: write once, reuse across tools.