Keep GitHub Copilot Agent Skills Small and Focused

One of the easiest mistakes to make with GitHub Copilot Agent Skills is treating them as somewhere to store every useful instruction you have ever written.

It usually starts well, you create a Terraform module skill, an Azure architecture skill, a pull request review skill, or a cost optimisation skill. It helps, so you add a little more. Another rule, another example, another edge case, another reminder.

After a while, the skill stops being guidance for a specific task and becomes a long instruction file with overlapping advice and competing priorities. Some of it still makes sense, but not all of it applies every time. That is normally when the output becomes less predictable.

A good skill should capture reusable engineering judgement for a specific type of work. It should help the agent make better decisions for that task. It should not become a mega-prompt trying to cover every possible scenario.

This also fits how Agent Skills are loaded. The agent first sees the skill name and description, then loads the full SKILL.md when the task appears to match. From there, it can use supporting material such as references/, scripts/, or assets/ if the skill needs them.

That loading model is worth designing for. A vague description can activate the wrong skill. An overloaded SKILL.md gives the agent too much to interpret at once. If every bit of guidance is crammed into one file, you lose the benefit of progressive disclosure.

Smaller, focused skills are easier to understand, easier to review, and easier to improve.

One skill, one behaviour

The best skills tend to have one clear behaviour behind them.

A Terraform module skill might guide the agent to follow the existing repository structure, keep naming consistent, use validation where it prevents common misuse, expose useful outputs, and avoid unnecessary abstraction.

A Terraform provider upgrade skill needs different guidance. It needs to check current and target versions, review changelogs, identify breaking changes, handle deprecations, update lock files where needed, and produce a pull request summary that reviewers can trust.

Both are Terraform-related, but they are not the same job.

At first, combining them feels sensible. They use the same tooling, may apply to the same repositories, and probably share some standards. The problem is that module authoring and provider upgrades require different judgement.

Module authoring is mostly about interface design, maintainability, reuse, naming, examples, and how easy the module is for other teams to consume. Provider upgrades are about change control, compatibility, risk, deprecated behaviour, and making the upgrade safe to review.

When those instructions live in one large skill, the agent has to work out which guidance applies to the task in front of it. Sometimes it will. Sometimes it will pull in guidance that does not belong.

A focused skill should be easy to describe in one sentence, especially in the description field where the agent decides whether to load it.

For example:

• Use this skill when creating or updating Terraform modules and you need consistent structure, inputs, outputs, validation, and examples.
• Use this skill when upgrading Terraform providers and you need version discovery, changelog review, breaking change analysis, migration notes, and pull request output.
• Use this skill when assessing Azure cost optimisation opportunities and you need practical recommendations with trade-offs, confidence, and operational impact.

Those descriptions are more useful than broad labels like “Terraform skill” or “Azure skill”. They tell the agent when the skill is relevant.

If the description needs a long list of exceptions, the skill probably wants splitting.

Avoiding mega-prompts

Mega-prompts are tempting because they feel complete. There is a sense that if enough rules are added, the agent will have everything it needs.

In practice, long instruction files often hide weak guidance behind volume. They repeat the same point in slightly different ways, mix hard requirements with personal preferences, and include examples that were useful for one project but accidentally become global advice.

They are also harder to maintain. Nobody wants to review a wall of instructions every time the behaviour needs to change.

I prefer keeping the core SKILL.md small. It should contain the behaviour, priorities, and decision rules. Longer examples, patterns, checklists, and implementation notes can live in supporting files.

That is where references/ becomes useful.

A Terraform module skill might keep the main guidance in SKILL.md, then link to supporting files such as:

• references/module-structure.md
• references/variable-validation.md
• references/examples.md

A provider upgrade skill could do the same with references/provider-upgrade-checklist.md or references/breaking-change-notes.md.

The question is not “have I written down everything I know?” The better question is “have I given the agent enough judgement to do this task well?”

For a module authoring skill, that might mean guidance like:

• follow the existing repository structure
• prefer simple inputs over clever nested objects unless the complexity is justified
• include validation where it prevents common misuse
• expose outputs that consumers are likely to need
• avoid abstractions for hypothetical future requirements

For a provider upgrade skill, the guidance will look different:

• check the current and target provider versions
• review changelogs and upgrade guides before changing code
• identify breaking changes early
• handle deprecated resources explicitly
• document migration decisions in the pull request
• avoid unrelated refactoring during the upgrade

Both sets of guidance are useful. Combining them into one general Terraform skill makes the behaviour broader and less precise. The agent may still produce a good result, but there is more room for it to wander.

Good guidance gives the agent a useful constraint. Bad guidance gives it another thing to interpret.

Use scripts when the workflow needs more than judgement

Not every skill needs scripts. Most skills should probably start without them.

But there are times when a written instruction is not enough. If the task needs repeatable validation, file inspection, formatting, data extraction, or comparison logic, a script can make the skill more reliable.

For example, a Terraform provider upgrade skill might include a script to inspect provider versions across a repository, check lock files, or produce a basic upgrade summary. A module authoring skill might include validation scripts for examples, documentation checks, or naming conventions.

The point is not to turn every skill into a toolchain. The point is to avoid asking the agent to manually perform brittle work that a small script can do better.

If you do use scripts/, keep them boring:

• make the script easy to run
• document the expected inputs and outputs
• avoid interactive prompts
• return clear errors
• prefer structured output where useful
• pin versions where behaviour matters

A script should reduce ambiguity. If it adds a second layer of mystery, it probably does not belong in the skill yet.

When to split a skill

I usually split a skill when the behaviour, audience, or output type changes.

Terraform is a good example because it is easy to assume everything belongs together. It does not.

A skill for writing Terraform modules is different from a skill for upgrading providers. A Terraform review skill is different again. It may care about security, naming, cost, operational risk, and whether the code matches platform standards. That is review behaviour. It should not also try to generate the module, perform the provider upgrade, write the README, and produce the pull request summary.

Some overlap is fine. Skills do not need to be artificially isolated. Shared principles around consistency, simplicity, and maintainability can appear in more than one place.

The important part is that each skill has a clear job.

A useful test is whether two tasks would produce different review comments from an experienced engineer. If they would, they probably need different guidance.

Examples beat more rules

Examples are often more useful than another page of instructions.

Agents respond well to concrete patterns. If Terraform variables should be written in a certain way, show a realistic variable example. If module outputs should follow a convention, show the convention. If provider upgrade pull requests should include risk notes, migration details, and testing evidence, show the expected shape.

The example does not need to cover every edge case. It needs to anchor the output.

Rules often sound clear until they are applied. “Use sensible variable names” is fine, but sensible depends on the module. “Avoid over-engineering” is also fine, but it becomes more useful when paired with an example of a simple input structure and a nested object that adds no value.

Provider upgrades are similar. Telling the agent to “document breaking changes” helps. Showing the expected format is better. For example, the output might separate confirmed breaking changes, code changes made, manual follow-up required, and testing performed.

Good examples carry judgement. They show what good looks like for the task.

Predictable output is the real value

The value of a good skill is not one impressive answer. It is consistent output across repeated use.

That matters when teams start relying on agent-assisted work. A one-off prompt can be messy because the person driving it can correct the output as they go. A shared skill needs more care because it becomes part of the team’s working pattern.

If the skill is vague, overloaded, or full of competing instructions, every use becomes a negotiation with the agent.

Focused skills reduce that negotiation. They make it clearer what the agent should optimise for, make changes easier to review, and make the behaviour easier to test. They also make it easier for other engineers to understand why the skill exists.

This fits naturally with platform engineering. The goal is not to build a giant central brain that knows everything. The goal is to package useful engineering judgement in a way teams can reuse without rediscovering the same standards each time.

Keep the skill close to the task. Make the description specific enough that the agent knows when to load it. Keep the main SKILL.md readable. Move deeper material into references/ when it does not need to be in the main context every time. Use scripts/ where repeatable validation or inspection makes the output safer.

A skill should feel like a good engineer giving clear direction on a specific job. If it starts to feel like a policy document, style guide, checklist, training manual, and toolchain all at once, it is probably doing too much.