skill-creator

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.

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)

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 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.

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):

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:

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/. 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).

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