--- name: make-skill-template description: 'Create new Agent Skills for GitHub Copilot from user requests or by duplicating this template. Use when asked to "create a skill", "make a new skill", "scaffold a skill", or when building specialized AI capabilities with bundled resources. Generates SKILL.md files with proper frontmatter, directory structure, and optional scripts/references/assets folders.' --- # Make Skill Template A meta-skill for creating new Agent Skills. Use this skill when you need to scaffold a new skill folder, generate a SKILL.md file, or help users understand the Agent Skills specification. ## Contents - [Contents](#contents) - [How to use this skill](#how-to-use-this-skill) - [Related skills](#related-skills) - [When to Use This Skill](#when-to-use-this-skill) - [Prerequisites](#prerequisites) - [Creating a New Skill](#creating-a-new-skill) - [Step 1: Create the Skill Directory](#step-1-create-the-skill-directory) - [Step 2: Generate SKILL.md with Frontmatter](#step-2-generate-skillmd-with-frontmatter) - [Frontmatter Field Requirements](#frontmatter-field-requirements) - [Description Best Practices](#description-best-practices) - [Step 3: Write the Skill Body](#step-3-write-the-skill-body) - [Step 4: Add Optional Directories (If Needed)](#step-4-add-optional-directories-if-needed) - [Skill Body Organization](#skill-body-organization) - [Example: Complete Skill Structure](#example-complete-skill-structure) - [Quick Start: Duplicate This Template](#quick-start-duplicate-this-template) - [Validation Checklist](#validation-checklist) - [Troubleshooting](#troubleshooting) - [References](#references) ## How to use this skill Attach this file to your Copilot Chat context, then invoke it when creating or refining a skill under `.github/skills/`. Use it to scaffold new skills and to check discoverability quality before committing. ## Related skills - [Reviewing Skills](../reviewing-skills/SKILL.md) — audit a skill for quality, discoverability, and best-practice compliance after authoring - [Development Workflow](../development-workflow/SKILL.md) — integrate skill creation changes into the repository workflow - [PR Readiness Review](../pr-readiness-review/SKILL.md) — final validation before opening a pull request with new or updated skills ## When to Use This Skill - User asks to "create a skill", "make a new skill", or "scaffold a skill" - User wants to add a specialized capability to their GitHub Copilot setup - User needs help structuring a skill with bundled resources - User wants to duplicate this template as a starting point ## Prerequisites - Understanding of what the skill should accomplish - A clear, keyword-rich description of capabilities and triggers - Knowledge of any bundled resources needed (scripts, references, assets, templates) ## Creating a New Skill ### Step 1: Create the Skill Directory Create a new folder with a lowercase, hyphenated name: ```text .github/skills// └── SKILL.md # Required ``` ### Step 2: Generate SKILL.md with Frontmatter Every skill requires YAML frontmatter with `name` and `description`: ```yaml --- name: description: '. Use when .' --- ``` #### Frontmatter Field Requirements | Field | Required | Constraints | | ----- | -------- | ----------- | | `name` | **Yes** | 1-64 chars, lowercase letters/numbers/hyphens only, must match folder name | | `description` | **Yes** | 10-1024 chars, must describe WHAT it does AND WHEN to use it | | `license` | No | License name or reference to bundled LICENSE.txt | | `compatibility` | No | 1-500 chars, environment requirements if needed | | `metadata` | No | Key-value pairs for additional properties | | `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental) | #### Description Best Practices **CRITICAL**: The `description` is the PRIMARY mechanism for automatic skill discovery. Include: 1. **WHAT** the skill does (capabilities) 2. **WHEN** to use it (triggers, scenarios, file types) 3. **Keywords** users might mention in requests **Good example:** ```yaml description: 'Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, or view browser console logs. Supports Chrome, Firefox, and WebKit.' ``` **Poor example:** ```yaml description: 'Web testing helpers' ``` ### Step 3: Write the Skill Body After the frontmatter, add markdown instructions. Recommended sections: | Section | Purpose | | ------- | ------- | | `# Title` | Brief overview | | `## When to Use This Skill` | Reinforces description triggers | | `## Prerequisites` | Required tools, dependencies | | `## Step-by-Step Workflows` | Numbered steps for tasks | | `## Troubleshooting` | Common issues and solutions | | `## References` | Links to bundled docs | For standards and review skills, rules are mandatory unless explicitly marked `Optional`. For advisory skills, distinguish requirements, recommendations, and examples with consistent labels. Define named thresholds, modes, phases, or terms before first use, and keep one authoritative definition for each concept. State each policy definition (what the policy is, its exceptions, their criteria) once, in a single designated authority section, and link to that authority by anchor from every other skill or section that needs the policy. Keep role-specific operational instructions (what to do, flag, or test) inline in the document whose role they serve. Restated definitions silently rot when the authority changes, while a link cannot drift and an instruction stated in only one place cannot drift. A reader executing a workflow or checklist must never need the linked definition to perform an action — they follow the link only to understand why. Use real markdown headings for durable rule sections. Avoid bold paragraphs as pseudo-headings when the section may need a table-of-contents entry, deep link, or review reference. ### Step 4: Add Optional Directories (If Needed) | Folder | Purpose | When to Use | | ------ | ------- | ----------- | | `scripts/` | Executable code (Python, Bash, JS) | Automation that performs operations | | `references/` | Documentation agent reads | API references, schemas, guides | | `assets/` | Static files used AS-IS | Images, fonts, templates | | `templates/` | Starter code agent modifies | Scaffolds to extend | ## Skill Body Organization Target `SKILL.md` under 500 lines; review carefully above 600 lines. Exceeding the target is acceptable when splitting always-needed workflow or review rules would make the skill less effective. Split situational references first. Keep these in `SKILL.md`: - Routing, prerequisites, and precedence rules - The main workflow and required feedback loops - Mandatory validation or review checklists - Rules needed on nearly every invocation Move these to reference files: - Element-specific, type-specific, or platform-specific rules - Long examples and templates - Rare edge cases and background material - Appendices or migration notes Each reference file should state its purpose and when the agent should load it. Keep references one level deep from `SKILL.md`. When one skill extends another, state what it inherits, overrides, or adds. Link to the parent skill or reference file and keep child-skill overrides narrow. ## Example: Complete Skill Structure ```text my-awesome-skill/ ├── SKILL.md # Required instructions ├── LICENSE.txt # Optional license file ├── scripts/ │ └── helper.py # Executable automation ├── references/ │ ├── api-reference.md # Detailed docs │ └── examples.md # Usage examples ├── assets/ │ └── diagram.png # Static resources └── templates/ └── starter.ts # Code scaffold ``` ## Quick Start: Duplicate This Template 1. Copy the `make-skill-template/` folder 2. Rename to your skill name (lowercase, hyphens) 3. Update `SKILL.md`: - Change `name:` to match folder name - Write a keyword-rich `description:` - Replace body content with your instructions 4. Add bundled resources as needed 5. Review with the [Reviewing Skills](../reviewing-skills/SKILL.md) skill ## Validation Checklist - [ ] Folder name is lowercase with hyphens - [ ] `name` field matches folder name exactly - [ ] `description` is 10-1024 characters - [ ] `description` explains WHAT and WHEN - [ ] `description` is wrapped in single quotes - [ ] Body content targets under 500 lines and is reviewed carefully above 600 lines - [ ] Always-needed workflow and review rules remain in `SKILL.md` - [ ] Situational details are split into reference files with clear load conditions - [ ] Named thresholds, modes, phases, or terms are defined before first use - [ ] Policy definitions are stated once in a designated authority section and linked from everywhere else; role-specific instructions stay inline - [ ] Standards/review rules are mandatory unless explicitly marked `Optional` - [ ] Deep links, TOC anchors, and referenced files resolve after heading changes - [ ] Bundled assets are under 5MB each ## Troubleshooting | Issue | Solution | | ----- | -------- | | Skill not discovered | Improve description with more keywords and triggers | | Validation fails on name | Ensure lowercase, no consecutive hyphens, matches folder | | Description too short | Add capabilities, triggers, and keywords | | Assets not found | Use relative paths from skill root | ## References - Agent Skills official spec: - Skill authoring best practices: