| name | skill-creator |
| description | 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. |
| metadata | {"author":"Thomas Thornton","version":"1.0.0","last-updated":"2026-05-19"} |
Skill Creator
Create high-quality GitHub Copilot agent skills (SKILL.md) that transform the general-purpose agent into a specialized expert.
What Is a Skill
A skill is a modular, self-contained knowledge package stored in .github/skills/<skill-name>/SKILL.md. It provides:
- Specialized workflows — Multi-step procedures for a specific domain
- Domain expertise — Company-specific schemas, patterns, business logic
- Tool integrations — Instructions for APIs, file formats, or services
- Bundled resources — Scripts, reference docs, and templates for reuse
Skills load in three levels (progressive disclosure):
- Metadata (
name + description) — Always in context (~100 words). This is the trigger mechanism.
- SKILL.md body — Loaded when the skill triggers. Keep under 500 lines.
- Bundled resources — Loaded on demand (scripts/, references/, assets/).
Skill Anatomy
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter name + description (required)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ Executable code for deterministic/repetitive tasks
├── references/ Docs loaded into context as needed
└── assets/ Output files (templates, icons, boilerplate)
Do NOT include: setup guides, changelogs, or user-facing documentation — skills are instructions for the agent, not onboarding docs for humans.
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)
Exit criteria: 2–3 use cases defined, success criteria agreed, tools/dependencies identified.
Phase 2 — Architecture
Make structural decisions before writing:
- 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?
Exit criteria: Pattern selected, folder structure planned, description drafted, content mapped.
Phase 3 — Craft
Write SKILL.md with precision.
Frontmatter rules:
---
name: kebab-case-name
description: [What + When + optional Not-when — single line, under 200 words]
---
name: kebab-case only, matches the folder name exactlydescription: 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.
Phase 4 — Validate
Run the automated validator first:
python .github/skills/skill-creator/scripts/quick_validate.py .github/skills/<skill-name>
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):
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:
Phase 5 — Deliver
If starting a new skill from scratch, scaffold the folder first:
python .github/skills/skill-creator/scripts/init_skill.py <skill-name>
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/:
## Advanced Features
- **Streaming**: See [references/streaming.md](references/streaming.md) — read when user requests real-time output
- **Error handling**: See [references/errors.md](references/errors.md) — read when diagnosing failures
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, reference advanced content:
## Basic usage
[Core instructions here]
## Advanced: tracked changes
See [references/redlining.md](references/redlining.md) — read only for tracked-change workflows.
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).
- Example:
assets/template.docx, assets/logo.png, assets/hello-world/
Anti-Patterns
| Anti-pattern | Why it hurts |
|---|
| Vague description ("helps with X") | Undertriggering — Copilot won't invoke the skill |
| "When to use" in the body | Body only loads AFTER triggering — too late |
| Wall-of-text instructions | Agent skims and misses critical steps |
| No examples | Agents need concrete input/output pairs |
| README.md inside skill folder | Clutter — agents don't need meta-docs |
| Hardcoded credentials in scripts | Security risk |
| Deeply nested references | Increases cognitive load; keep one level deep |
| SKILL.md over 500 lines | Context bloat on every invocation |
| Overly rigid MUST/NEVER rules | Explain the WHY instead; agents respond better |
Extracting a Skill from an Existing Conversation
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
