Create, update, review, and validate GitHub Copilot agent skills (SKILL.md files). Use this skill whenever someone wants to create a new skill, build a skill from scratch, package domain knowledge into a reusable agent skill, turn a workflow into a skill, or asks "how do I teach Copilot to do X consistently". Also use when updating or improving an existing SKILL.md, writing the description field for better triggering, or designing the folder structure and bundled resources for a skill. Do NOT use for general coding questions, runtime debugging, or MCP server configuration.
Create, update, review, and validate GitHub Copilot agent skills (SKILL.md files). Use this skill whenever someone wants to create a new skill, build a skill from scratch, package domain knowledge into a reusable agent skill, turn a workflow into a skill, or asks "how do I teach Copilot to do X consistently". Also use when updating or improving an existing SKILL.md, writing the description field for better triggering, or designing the folder structure and bundled resources for a skill. Do NOT use for general coding questions, runtime debugging, or MCP server configuration.
Do NOT include: setup guides, changelogs, or user-facing documentation — skills are instructions for the agent, not onboarding docs for humans.
When to Use
The user wants to create a new skill ("create a skill", "build a skill", "make a skill for X").
The user wants to turn a workflow into a reusable skill ("turn this into a skill", "capture what we just did").
The user wants to update or improve an existing SKILL.md.
The user asks how to teach Copilot to do something consistently.
The user wants to write the description field, plan the folder structure, or design bundled resources for a skill.
Is a Skill the Right Vehicle?
Not every workflow needs a skill. Before creating one, choose the right tool:
Situation
Use instead
A rule that applies to ALL Copilot interactions in this repo
copilot-instructions.md entry
A rule scoped to specific file types (e.g., always use kebab-case for Bicep variable names)
.github/instructions/*.instructions.md with applyTo glob
A one-off prompt you run occasionally
.github/prompts/*.prompt.md
A multi-step workflow with domain knowledge that benefits from on-demand loading
Skill
A complex workflow with a dedicated agent persona
.github/agents/*.agent.md
A skill is the right choice when: the workflow is too detailed for copilot-instructions.md, it should only load for relevant requests (not every conversation), and it encapsulates reusable domain knowledge or a repeatable process.
If the user's need is better served by a simpler vehicle, say so and use that instead. Not everything needs to be a skill.
Creation Process
Phase 1 — Discovery
Understand the problem before writing a single line. Ask conversationally:
What workflow do you want to make consistent? Walk through the steps you do today.
What goes wrong without the skill? (Inconsistency, forgotten steps, repeated explanation, wrong outputs)
Who will use this skill? (Just you, your team, public)
What tools or services are involved?
Collect 2–3 concrete use cases. For each, capture:
Trigger: What the user says/does
Steps: Sequence of actions
Tools: Built-in or MCP tools needed
Result: What success looks like (specific output)
Choose the primary pattern — Sequential workflow, iterative refinement, domain-specific intelligence, or multi-tool coordination. Read references/workflows.md for structure templates and the pattern-selection guide — load it now if you are unsure which pattern fits.
Plan the folder structure — Only add scripts/, references/, or assets/ when there is a clear reason:
Same code rewritten repeatedly → scripts/
Reference material > ~100 lines → references/
Output uses templates/images → assets/
Draft the description — This is the most important piece. See Writing the Description below.
Map content to disclosure levels — What goes in SKILL.md body vs. reference files?
name: kebab-case only, matches the folder name exactly
description: primary trigger mechanism — include trigger phrases, what it does, what it does NOT do
No other frontmatter fields needed
Body writing guidelines:
Use imperative form: "Search for...", "Create the...", "Validate..."
Explain WHY behind instructions rather than just MUST/NEVER
Include 2–3 realistic examples of user inputs and expected outputs
Put critical instructions at the top, not buried in the middle
Never wrap prose lines at arbitrary column widths — let paragraphs flow naturally
Reference bundled files clearly and state exactly WHEN the agent should read them
Write for coexistence — this skill loads alongside other skills in .github/skills/. Never assume it is the only skill in context. Avoid generic section headings like "## Overview" that could conflict, and don't claim to handle tasks that belong to another skill in this repo.
Read references/output-patterns.md for patterns on specifying output format (Template, Examples, Scope Communication, Validation Gate) — load it when deciding how to structure the skill's output expectations or examples.
Then work through the full references/quality-checklist.md for description quality scoring, instruction quality scoring, trigger testing, and final sign-off.
Quick structure checks (also caught by the script):
SKILL.md exists with correct casing (not skill.md or SKILL.MD)
Frontmatter has name and description, correct YAML delimiters (---)
Folder name is kebab-case matching name field
No README.md or extra docs in the skill folder
Description does NOT contain XML angle brackets < >
Trigger checks — propose 3–5 test phrases and verify mentally:
Should trigger: obvious requests, paraphrased versions, informal requests
Should NOT trigger: unrelated topics, tasks better handled by other skills
Quality checks:
Every instruction is unambiguous — an agent reading it fresh can follow it without guessing
Examples are realistic and complete
Referenced files have clear load conditions stated in SKILL.md
SKILL.md body is under 500 lines
Phase 5 — Deliver
If starting a new skill from scratch, scaffold the folder first:
This creates the folder and a template SKILL.md with TODO placeholders. Then fill in the skill content and run the validator before presenting to the user.
Place the completed skill at .github/skills/<skill-name>/SKILL.md.
Present a brief summary:
What the skill does
Suggested test phrase to try first
Any bundled resources and when they load
Writing the Description
The description field is the primary mechanism that determines whether Copilot invokes the skill. A well-written description is specific, includes trigger phrases, and leans slightly "pushy" — agents tend to undertrigger.
Structure:[What it does] + [When to use it — include actual phrases users would say] + [What NOT to use it for if overlap risk exists]
Good example:
Analyze Azure architectures for cost optimization opportunities and provide savings recommendations. Use when reviewing Azure spending, asked to reduce costs, optimize resources, right-size VMs, or find savings across subscriptions. Do NOT use for general architecture design (use architecture-design skill instead).
Bad example:
Helps with Azure cost analysis.
Rules:
Include actual phrases users would say, including variations ("create skill", "build a skill", "turn this into a skill", "teach Copilot to do X")
Include relevant file types or formats if applicable
Add negative triggers (Do NOT use for...) when overlap with other skills is likely
Keep under 200 words — it loads in every conversation
Progressive Disclosure Patterns
Pattern 1 — High-level guide with references
Keep core workflow in SKILL.md; move detailed docs to references/. For each reference file, state exactly when the agent should load it — e.g. "read when the user asks about X" or "read when diagnosing Y".
Pattern 2 — Domain-specific organization
Organize by domain to avoid loading irrelevant context. When a skill spans multiple environments or tool variants, keep only the selection logic in SKILL.md and move per-variant detail into separate files:
iac-generator/
├── SKILL.md (format selection + shared standards)
└── references/
├── bicep.md (read when user chooses Bicep)
├── terraform.md (read when user chooses Terraform)
├── arm.md (read when user chooses ARM templates)
└── pulumi.md (read when user chooses Pulumi)
Another example — an APIM skill covering multiple environments:
apim-deployment/
├── SKILL.md (shared pipeline and APIOps steps)
└── references/
├── github-actions.md (read when deploying via GitHub Actions)
└── azure-devops.md (read when deploying via Azure DevOps)
Pattern 3 — Conditional details
Show core content in SKILL.md and load a reference file only when an advanced scenario is triggered. State the load condition inline next to the link.
Key rule: Keep reference links one level deep from SKILL.md. For files over 100 lines, add a table of contents at the top.
Bundled Resources Guide
scripts/
Use when the same code is written repeatedly across invocations, or when deterministic reliability is critical.
Token-efficient: scripts can be executed without loading into context
Test scripts by actually running them — don't assume they work
This skill bundles: scripts/init_skill.py (scaffold a new skill folder from template) and scripts/quick_validate.py (validate structure, frontmatter, and body against this repo's conventions)
references/
Use for domain knowledge, API specs, schemas, or detailed guides that exceed what fits cleanly in SKILL.md.
Load only when needed — always state the condition in SKILL.md
Avoid duplicating content between SKILL.md and reference files
This skill bundles: references/workflows.md (workflow pattern templates — read during Phase 2), references/output-patterns.md (output formatting patterns — read during Phase 3), and references/quality-checklist.md (pre-delivery quality checks — read during Phase 4)
assets/
Use for files that appear in the output Claude produces (not loaded into context, but used in final output).
When the user says "turn this into a skill" or "capture what we just did", the conversation history is the primary source — mine it before asking a single question.
Step 1 — Mine the history first. Read back through the conversation and extract:
Every tool invoked and in what order
Each correction or course-change the user made (these are the most valuable signal — they reveal where a naive agent would go wrong)
Inputs provided and the final output format the user accepted
Anything the agent had to discover or infer mid-conversation that a fresh agent starting cold would not know
Step 2 — Identify what's missing. After mining, you'll have gaps. Common ones:
Trigger phrases: what would someone say to invoke this workflow?
Edge cases: what variations of the input exist that the conversation didn't cover?
Success criteria: how does the user know the output is correct?
Scope boundaries: what should this skill explicitly NOT handle?
Step 3 — Ask only targeted gap-filling questions. Don't dump a full Discovery interview on the user — they just finished the work and want it captured. Ask one or two focused questions maximum, with a suggested default for each: "I'm going to use X as the trigger phrase — does that sound right, or would you phrase it differently?"
Step 4 — Confirm before writing. Present a concise summary of what you're going to encode: the workflow steps, the trigger phrases, the success criteria, any bundled resources you plan to create. Get a yes before writing the SKILL.md.
Step 5 — Generalise, don't transcribe. The biggest risk here is writing a skill that only works for the exact example in the conversation. Before writing each instruction, ask: "If a different user gives a slightly different input, does this still hold?" Strip out specifics (file names, literal values, one-off workarounds) unless they're universally needed. Encode the pattern, not the instance.
Step 6 — Proceed through Phases 2–5 — architecture, craft, validate, deliver as normal.
Updating an Existing Skill
When improving rather than creating:
Preserve the original name field and folder name — do not rename
Identify what failed: wrong triggers, missing steps, incorrect outputs, outdated info
Edit the minimum necessary — don't refactor surrounding content
Generalize from failures rather than adding narrow fixes (avoid overfitting to one example)
Re-validate trigger phrases after editing the description
Principles for Writing Effective Instructions
Drawn from AI coding agent best practices:
Smallest change that works — don't add steps or context that don't pull their weight
Explain the why — "Use DefaultAzureCredential so credentials are never hardcoded" beats "ALWAYS use DefaultAzureCredential"
Concrete over abstract — give exact file paths, command names, expected outputs
Prove it works — after writing a skill, mentally walk through it with a real user prompt
Incremental delivery — if a skill is complex, split it with clear references rather than one monolithic file
Read before write — if the skill involves a codebase or service, instruct the agent to locate existing patterns first
