Agent skills are a practical way to capture reusable engineering judgement for AI coding agents, whether that judgement relates to reviewing Terraform, creating architecture diagrams, writing API Management policies, checking pull requests or following a migration approach.
A skill does not guarantee a correct answer, and it should not be treated as a shortcut around engineering review. What it does is give the agent more relevant context before it starts producing or changing output, which can make repeated tasks more consistent and reduce the amount of guidance that needs to be repeated in every prompt.
One small part of the skill has more influence than it first appears to: the description.
It is easy to treat the description as a tidy sentence for someone browsing the repository, but in practice it is closer to selection metadata. The agent uses the name and description to decide whether the skill is relevant enough to load before it reads the detailed instructions, examples, scripts or supporting files behind it.
A skill can therefore contain excellent guidance and still have little effect if its description does not give the agent a clear reason to select it.
The description affects selection
Agent skills generally rely on progressive disclosure because loading every available skill and all of its supporting content for every task would add noise, consume context and make the final output harder to reason about.
Instead, the agent begins with lightweight metadata and tries to identify which skills are likely to help with the request. The description is part of that decision, so it affects how the agent behaves rather than simply documenting what the skill contains.
A vague description may cause a useful skill to be skipped, while an overly broad description may cause it to load for work it was never designed to support. As the library grows, broad and overlapping descriptions can also cause several skills to compete for the same request, which is often where behaviour starts to feel inconsistent.
When an agent selects the wrong skill, it is tempting to blame the model immediately. Sometimes that is fair, but sometimes the skill description never gave the model a clear enough selection boundary.
Vague descriptions create vague behaviour
Consider a description such as:
Helps with Azure.
Although technically accurate, it gives the agent almost no practical signal because Azure could refer to networking, identity, Kubernetes, Terraform, monitoring, API Management, governance, cost management, application hosting or AI services.
The same problem appears with descriptions such as:
Use this skill for platform engineering tasks.
Platform engineering covers too much ground for that to be a useful boundary. Depending on the organisation, it might include golden paths, service onboarding, deployment workflows, internal developer platforms, observability, security controls, live service operations or infrastructure modules.
A more useful description would be:
Use this skill when reviewing Azure API Management policies for authentication, authorisation, rate limiting, quota controls, header handling, backend routing, and observability.
This version gives the agent a recognisable task area and enough technical detail to compare the skill with an actual request. The description does not need to explain everything the skill knows, but it does need to describe the work precisely enough for selection to be meaningful.
Describe the trigger, not only the topic
The strongest descriptions usually explain when the skill should be used rather than merely naming the subject it relates to.
Starting with “Use this skill when…” is useful because it forces the description to define a scenario. For example, a description that says:
Creates diagrams.
does not explain what kind of diagrams the skill creates, which technical domains it supports or what the output should look like.
A better version would be:
Use this skill when creating Excalidraw-style architecture diagrams for Azure platforms, CI/CD flows, ingress, egress, authentication or deployment processes. Produce simple, clearly labelled diagrams that make the flow easy to follow. Do not use this skill for Terraform generation or detailed cost analysis.
That description gives the agent a specific task, a technical domain, an expected output and a boundary. Those boundaries are important because a useful skill should be easy to select when its guidance applies and equally easy to ignore when it does not.
If every skill attempts to cover its own task and several adjacent tasks, the agent receives more context than it needs and its output becomes less predictable.
Keep the description aligned with the skill
The description should reflect what the skill genuinely contains rather than what the author hopes it might eventually support.
If a skill reviews Terraform module structure, describing it as a general Terraform implementation skill will cause it to be selected for work it cannot properly handle. A skill that creates Excalidraw diagrams should not imply that it performs a complete architecture review, while an APIM policy-authoring skill should not claim responsibility for wider API strategy or application design.
An overstated description creates a mismatch between selection and execution. The agent may choose the skill based on the description, only to discover that the detailed instructions do not contain enough guidance for the task.
For most skills, the description should make four things clear: the work it supports, the situations in which it should be selected, the output it should help produce and the work that sits outside its scope.
For example:
Use this skill when creating or reviewing Terraform changes for AzureRM provider upgrades. It helps with breaking-change analysis, version constraint updates, provider syntax changes, plan review and migration guidance. Produce practical upgrade steps, identified risks and suggested code changes. Do not use it for general application code reviews.
This is more useful than “Helps with Terraform” because it describes the actual job performed by the skill rather than the broad technology it happens to involve.
Broad descriptions become harder to manage at scale
Poor descriptions are less noticeable when a repository contains only one or two skills because there is little competition during selection. A broad description may appear to work simply because the agent has very few alternatives.
The problem becomes clearer as the skill library grows. Descriptions begin to overlap, several skills appear relevant to the same request, and guidance written for one context can be loaded into another. The resulting output may become heavier, less relevant or shaped by standards that were never intended for the task.
The objective should not be to make a skill load as often as possible. It should load when it contains judgement that is genuinely useful for the work being requested.
For example:
Helps with DevOps.
could match almost any task in an engineering repository, whereas:
Use this skill when creating or reviewing GitHub Actions workflows for Terraform deployments. It covers OIDC authentication, environment promotion, plan and apply separation, reusable workflows, matrix strategies and pull-request feedback.
gives the agent a much clearer selection boundary. The narrower description is easier to maintain, easier to test and less likely to interfere with unrelated work.
Test descriptions using real requests
Skill descriptions should be tested against the prompts engineers are likely to write rather than only being reviewed as documentation.
For an API Management policy skill, I would test requests such as:
Review this APIM policy for missing AI gateway controls.
Add rate limiting and token observability to this shared AI API. Check whether this product-level quota design works across multiple teams.
If the skill is not selected for those requests, the description probably needs stronger task-specific language. If it loads for every generic Azure API question, its scope is probably too broad.
A diagramming skill should be tested in the same way with realistic requests such as:
Create a diagram showing APIM routing requests to private AI services.
Draw the ingress path from Front Door through the platform boundary.
The user should not need to mention the exact skill name every time they want it to be used. When explicit naming is the only reliable trigger, the description is not giving the agent enough information to make the decision itself.
Negative testing is equally useful. Try requests where the skill should remain unloaded and check whether the boundary holds, because a skill that triggers for everything can be just as disruptive as one that never triggers at all.
A useful pattern to follow
Most skills do not need a complicated metadata framework. A simple structure is usually enough:
Use this skill when [specific task or scenario]. It helps with [main capabilities]. It should produce [expected output]. Do not use it for [boundary].
Example:
Use this skill when reviewing Terraform pull requests for Azure platform infrastructure. It covers provider usage, module structure, naming, security, reliability and maintainability. Produce specific review comments, identified risks and suggested changes. Do not use it for application code reviews.
The wording does not need to follow this structure exactly, but the underlying information should be present. The description needs to explain which engineering judgement the skill contains, where that judgement applies and where it stops.
Treating the description as decoration misses its real purpose. It is part of the skill’s selection mechanism, and if that selection metadata is unclear, the quality of everything behind it may not matter because the agent may never load it.