agent-skills.instructions.md
1 --- 2 description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot' 3 applyTo: '**/.github/skills/**/SKILL.md, **/.claude/skills/**/SKILL.md' 4 --- 5 6 # Agent Skills File Guidelines 7 8 Instructions for creating effective and portable Agent Skills that enhance GitHub Copilot with specialized capabilities, workflows, and bundled resources. 9 10 ## What Are Agent Skills? 11 12 Agent Skills are self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities. Unlike custom instructions (which define coding standards), skills enable task-specific workflows that can include scripts, examples, templates, and reference data. 13 14 Key characteristics: 15 - **Portable**: Works across VS Code, Copilot CLI, and Copilot coding agent 16 - **Progressive loading**: Only loaded when relevant to the user's request 17 - **Resource-bundled**: Can include scripts, templates, examples alongside instructions 18 - **On-demand**: Activated automatically based on prompt relevance 19 20 ## Directory Structure 21 22 Skills are stored in specific locations: 23 24 | Location | Scope | Recommendation | 25 |----------|-------|----------------| 26 | `.github/skills/<skill-name>/` | Project/repository | Recommended for project skills | 27 | `.claude/skills/<skill-name>/` | Project/repository | Legacy, for backward compatibility | 28 | `~/.github/skills/<skill-name>/` | Personal (user-wide) | Recommended for personal skills | 29 | `~/.claude/skills/<skill-name>/` | Personal (user-wide) | Legacy, for backward compatibility | 30 31 Each skill **must** have its own subdirectory containing at minimum a `SKILL.md` file. 32 33 ## Required SKILL.md Format 34 35 ### Frontmatter (Required) 36 37 ```yaml 38 --- 39 name: webapp-testing 40 description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers. 41 license: Complete terms in LICENSE.txt 42 --- 43 ``` 44 45 | Field | Required | Constraints | 46 |-------|----------|-------------| 47 | `name` | Yes | Lowercase, hyphens for spaces, max 64 characters (e.g., `webapp-testing`) | 48 | `description` | Yes | Clear description of capabilities AND use cases, max 1024 characters | 49 | `license` | No | Reference to LICENSE.txt (e.g., `Complete terms in LICENSE.txt`) or SPDX identifier | 50 51 ### Description Best Practices 52 53 **CRITICAL**: The `description` field is the PRIMARY mechanism for automatic skill discovery. Copilot reads ONLY the `name` and `description` to decide whether to load a skill. If your description is vague, the skill will never be activated. 54 55 **What to include in description:** 56 1. **WHAT** the skill does (capabilities) 57 2. **WHEN** to use it (specific triggers, scenarios, file types, or user requests) 58 3. **Keywords** that users might mention in their prompts 59 60 **Good description:** 61 ```yaml 62 description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers. 63 ``` 64 65 **Poor description:** 66 ```yaml 67 description: Web testing helpers 68 ``` 69 70 The poor description fails because: 71 - No specific triggers (when should Copilot load this?) 72 - No keywords (what user prompts would match?) 73 - No capabilities (what can it actually do?) 74 75 ### Body Content 76 77 The body contains detailed instructions that Copilot loads AFTER the skill is activated. Recommended sections: 78 79 | Section | Purpose | 80 |---------|---------| 81 | `# Title` | Brief overview of what this skill enables | 82 | `## When to Use This Skill` | List of scenarios (reinforces description triggers) | 83 | `## Prerequisites` | Required tools, dependencies, environment setup | 84 | `## Step-by-Step Workflows` | Numbered steps for common tasks | 85 | `## Troubleshooting` | Common issues and solutions table | 86 | `## References` | Links to bundled docs or external resources | 87 88 ## Bundling Resources 89 90 Skills can include additional files that Copilot accesses on-demand: 91 92 ### Supported Resource Types 93 94 | Folder | Purpose | Loaded into Context? | Example Files | 95 |--------|---------|---------------------|---------------| 96 | `scripts/` | Executable automation that performs specific operations | When executed | `helper.py`, `validate.sh`, `build.ts` | 97 | `references/` | Documentation the AI agent reads to inform decisions | Yes, when referenced | `api_reference.md`, `schema.md`, `workflow_guide.md` | 98 | `assets/` | **Static files used AS-IS** in output (not modified by the AI agent) | No | `logo.png`, `brand-template.pptx`, `custom-font.ttf` | 99 | `templates/` | **Starter code/scaffolds that the AI agent MODIFIES** and builds upon | Yes, when referenced | `viewer.html` (insert algorithm), `hello-world/` (extend) | 100 101 ### Directory Structure Example 102 103 ``` 104 .github/skills/my-skill/ 105 ├── SKILL.md # Required: Main instructions 106 ├── LICENSE.txt # Recommended: License terms (Apache 2.0 typical) 107 ├── scripts/ # Optional: Executable automation 108 │ ├── helper.py # Python script 109 │ └── helper.ps1 # PowerShell script 110 ├── references/ # Optional: Documentation loaded into context 111 │ ├── api_reference.md 112 │ ├── step1-setup.md # Detailed workflow (>3 steps) 113 │ └── step2-deployment.md 114 ├── assets/ # Optional: Static files used AS-IS in output 115 │ ├── baseline.png # Reference image for comparison 116 │ └── report-template.html 117 └── templates/ # Optional: Starter code the AI agent modifies 118 ├── scaffold.py # Code scaffold the AI agent customizes 119 └── config.template # Config template the AI agent fills in 120 ``` 121 122 > **LICENSE.txt**: When creating a skill, download the Apache 2.0 license text from https://www.apache.org/licenses/LICENSE-2.0.txt and save as `LICENSE.txt`. Update the copyright year and owner in the appendix section. 123 124 ### Assets vs Templates: Key Distinction 125 126 **Assets** are static resources **consumed unchanged** in the output: 127 - A `logo.png` that gets embedded into a generated document 128 - A `report-template.html` copied as output format 129 - A `custom-font.ttf` applied to text rendering 130 131 **Templates** are starter code/scaffolds that **the AI agent actively modifies**: 132 - A `scaffold.py` where the AI agent inserts logic 133 - A `config.template` where the AI agent fills in values based on user requirements 134 - A `hello-world/` project directory that the AI agent extends with new features 135 136 **Rule of thumb**: If the AI agent reads and builds upon the file content → `templates/`. If the file is used as-is in output → `assets/`. 137 138 ### Referencing Resources in SKILL.md 139 140 Use relative paths to reference files within the skill directory: 141 142 ```markdown 143 ## Available Scripts 144 145 Run the [helper script](./scripts/helper.py) to automate common tasks. 146 147 See [API reference](./references/api_reference.md) for detailed documentation. 148 149 Use the [scaffold](./templates/scaffold.py) as a starting point. 150 ``` 151 152 ## Progressive Loading Architecture 153 154 Skills use three-level loading for efficiency: 155 156 | Level | What Loads | When | 157 |-------|------------|------| 158 | 1. Discovery | `name` and `description` only | Always (lightweight metadata) | 159 | 2. Instructions | Full `SKILL.md` body | When request matches description | 160 | 3. Resources | Scripts, examples, docs | Only when Copilot references them | 161 162 This means: 163 - Install many skills without consuming context 164 - Only relevant content loads per task 165 - Resources don't load until explicitly needed 166 167 ## Content Guidelines 168 169 ### Writing Style 170 171 - Use imperative mood: "Run", "Create", "Configure" (not "You should run") 172 - Be specific and actionable 173 - Include exact commands with parameters 174 - Show expected outputs where helpful 175 - Keep sections focused and scannable 176 177 ### Script Requirements 178 179 When including scripts, prefer cross-platform languages: 180 181 | Language | Use Case | 182 |----------|----------| 183 | Python | Complex automation, data processing | 184 | pwsh | PowerShell Core scripting | 185 | Node.js | JavaScript-based tooling | 186 | Bash/Shell | Simple automation tasks | 187 188 Best practices: 189 - Include help/usage documentation (`--help` flag) 190 - Handle errors gracefully with clear messages 191 - Avoid storing credentials or secrets 192 - Use relative paths where possible 193 194 ### When to Bundle Scripts 195 196 Include scripts in your skill when: 197 - The same code would be rewritten repeatedly by the agent 198 - Deterministic reliability is critical (e.g., file manipulation, API calls) 199 - Complex logic benefits from being pre-tested rather than generated each time 200 - The operation has a self-contained purpose that can evolve independently 201 - Testability matters — scripts can be unit tested and validated 202 - Predictable behavior is preferred over dynamic generation 203 204 Scripts enable evolution: even simple operations benefit from being implemented as scripts when they may grow in complexity, need consistent behavior across invocations, or require future extensibility. 205 206 ### Security Considerations 207 208 - Scripts rely on existing credential helpers (no credential storage) 209 - Include `--force` flags only for destructive operations 210 - Warn users before irreversible actions 211 - Document any network operations or external calls 212 213 ## Common Patterns 214 215 ### Parameter Table Pattern 216 217 Document parameters clearly: 218 219 ```markdown 220 | Parameter | Required | Default | Description | 221 |-----------|----------|---------|-------------| 222 | `--input` | Yes | - | Input file or URL to process | 223 | `--action` | Yes | - | Action to perform | 224 | `--verbose` | No | `false` | Enable verbose output | 225 ``` 226 227 ## Validation Checklist 228 229 Before publishing a skill: 230 231 - [ ] `SKILL.md` has valid frontmatter with `name` and `description` 232 - [ ] `name` is lowercase with hyphens, ≤64 characters 233 - [ ] `description` clearly states **WHAT** it does, **WHEN** to use it, and relevant **KEYWORDS** 234 - [ ] Body includes when to use, prerequisites, and step-by-step workflows 235 - [ ] SKILL.md body kept under 500 lines (split large content into `references/` folder) 236 - [ ] Large workflows (>5 steps) split into `references/` folder with clear links from SKILL.md 237 - [ ] Scripts include help documentation and error handling 238 - [ ] Relative paths used for all resource references 239 - [ ] No hardcoded credentials or secrets 240 241 ## Workflow Execution Pattern 242 243 When executing multi-step workflows, create a TODO list where each step references the relevant documentation: 244 245 ```markdown 246 ## TODO 247 - [ ] Step 1: Configure environment - see [workflow-setup.md](./references/workflow-setup.md#environment) 248 - [ ] Step 2: Build project - see [workflow-setup.md](./references/workflow-setup.md#build) 249 - [ ] Step 3: Deploy to staging - see [workflow-deployment.md](./references/workflow-deployment.md#staging) 250 - [ ] Step 4: Run validation - see [workflow-deployment.md](./references/workflow-deployment.md#validation) 251 - [ ] Step 5: Deploy to production - see [workflow-deployment.md](./references/workflow-deployment.md#production) 252 ``` 253 254 This ensures traceability and allows resuming workflows if interrupted. 255 256 ## Related Resources 257 258 - [Agent Skills Specification](https://agentskills.io/) 259 - [VS Code Agent Skills Documentation](https://code.visualstudio.com/docs/copilot/customization/agent-skills) 260 - [Reference Skills Repository](https://github.com/anthropics/skills) 261 - [Awesome Copilot Skills](https://github.com/github/awesome-copilot/blob/main/docs/README.skills.md)