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: | 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: 1. **Choose the primary pattern** — Sequential workflow, iterative refinement, domain-specific intelligence, or multi-tool coordination. Read [references/workflows.md](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](#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:** ```yaml --- 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](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: ```bash python .github/skills/skill-creator/scripts/quick_validate.py .github/skills/<skill-name> ``` Then work through the full [references/quality-checklist.md](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: ```bash 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: 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