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

1. Metadata (name + description) — Always in context (~100 words). This is the trigger mechanism.
2. SKILL.md body — Loaded when the skill triggers. Keep under 500 lines.
3. 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:

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:

1. 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.
2. 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/
3. Draft the description — This is the most important piece. See Writing the Description below.
4. 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

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:

1. Preserve the original name field and folder name — do not rename
2. Identify what failed: wrong triggers, missing steps, incorrect outputs, outdated info
3. Edit the minimum necessary — don't refactor surrounding content
4. Generalize from failures rather than adding narrow fixes (avoid overfitting to one example)
5. 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