Skip to content

Commit 16c1c01

Browse files
aaronpowellaaronpowell
authored
Merge branch 'main' into all-contributors/add-shibicr93
2 parents 1797b6a + 86f78ee commit 16c1c01

3 files changed

Lines changed: 149 additions & 0 deletions

File tree

‎.github/workflows/validate-readme.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ on:
1111
- "*.js"
1212
- "README.md"
1313
- "docs/**"
14+
- "skills/**"
1415

1516
jobs:
1617
validate-readme:

‎docs/README.skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
2727
| [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
2828
| [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md) | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None |
2929
| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` |
30+
| [make-skill-template](../skills/make-skill-template/SKILL.md) | Create new Agent Skills for GitHub Copilot from prompts 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. | None |
3031
| [microsoft-code-reference](../skills/microsoft-code-reference/SKILL.md) | Look up Microsoft API references, find working code samples, and verify SDK code is correct. Use when working with Azure SDKs, .NET libraries, or Microsoft APIs—to find the right method, check parameters, get working examples, or troubleshoot errors. Catches hallucinated methods, wrong signatures, and deprecated patterns by querying official docs. | None |
3132
| [microsoft-docs](../skills/microsoft-docs/SKILL.md) | Query official Microsoft documentation to understand concepts, find tutorials, and learn how services work. Use for Azure, .NET, Microsoft 365, Windows, Power Platform, and all Microsoft technologies. Get accurate, current information from learn.microsoft.com and other official Microsoft websites—architecture overviews, quickstarts, configuration guides, limits, and best practices. | None |
3233
| [nuget-manager](../skills/nuget-manager/SKILL.md) | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None |

‎skills/make-skill-template/SKILL.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
name: make-skill-template
3+
description: 'Create new Agent Skills for GitHub Copilot from prompts 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.'
4+
---
5+
6+
# Make Skill Template
7+
8+
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.
9+
10+
## When to Use This Skill
11+
12+
- User asks to "create a skill", "make a new skill", or "scaffold a skill"
13+
- User wants to add a specialized capability to their GitHub Copilot setup
14+
- User needs help structuring a skill with bundled resources
15+
- User wants to duplicate this template as a starting point
16+
17+
## Prerequisites
18+
19+
- Understanding of what the skill should accomplish
20+
- A clear, keyword-rich description of capabilities and triggers
21+
- Knowledge of any bundled resources needed (scripts, references, assets, templates)
22+
23+
## Creating a New Skill
24+
25+
### Step 1: Create the Skill Directory
26+
27+
Create a new folder with a lowercase, hyphenated name:
28+
29+
```
30+
skills/<skill-name>/
31+
└── SKILL.md # Required
32+
```
33+
34+
### Step 2: Generate SKILL.md with Frontmatter
35+
36+
Every skill requires YAML frontmatter with `name` and `description`:
37+
38+
```yaml
39+
---
40+
name: <skill-name>
41+
description: '<What it does>. Use when <specific triggers, scenarios, keywords users might say>.'
42+
---
43+
```
44+
45+
#### Frontmatter Field Requirements
46+
47+
| Field | Required | Constraints |
48+
|-------|----------|-------------|
49+
| `name` | **Yes** | 1-64 chars, lowercase letters/numbers/hyphens only, must match folder name |
50+
| `description` | **Yes** | 1-1024 chars, must describe WHAT it does AND WHEN to use it |
51+
| `license` | No | License name or reference to bundled LICENSE.txt |
52+
| `compatibility` | No | 1-500 chars, environment requirements if needed |
53+
| `metadata` | No | Key-value pairs for additional properties |
54+
| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental) |
55+
56+
#### Description Best Practices
57+
58+
**CRITICAL**: The `description` is the PRIMARY mechanism for automatic skill discovery. Include:
59+
60+
1. **WHAT** the skill does (capabilities)
61+
2. **WHEN** to use it (triggers, scenarios, file types)
62+
3. **Keywords** users might mention in prompts
63+
64+
**Good example:**
65+
66+
```yaml
67+
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.'
68+
```
69+
70+
**Poor example:**
71+
72+
```yaml
73+
description: 'Web testing helpers'
74+
```
75+
76+
### Step 3: Write the Skill Body
77+
78+
After the frontmatter, add markdown instructions. Recommended sections:
79+
80+
| Section | Purpose |
81+
|---------|---------|
82+
| `# Title` | Brief overview |
83+
| `## When to Use This Skill` | Reinforces description triggers |
84+
| `## Prerequisites` | Required tools, dependencies |
85+
| `## Step-by-Step Workflows` | Numbered steps for tasks |
86+
| `## Troubleshooting` | Common issues and solutions |
87+
| `## References` | Links to bundled docs |
88+
89+
### Step 4: Add Optional Directories (If Needed)
90+
91+
| Folder | Purpose | When to Use |
92+
|--------|---------|-------------|
93+
| `scripts/` | Executable code (Python, Bash, JS) | Automation that performs operations |
94+
| `references/` | Documentation agent reads | API references, schemas, guides |
95+
| `assets/` | Static files used AS-IS | Images, fonts, templates |
96+
| `templates/` | Starter code agent modifies | Scaffolds to extend |
97+
98+
## Example: Complete Skill Structure
99+
100+
```
101+
my-awesome-skill/
102+
├── SKILL.md # Required instructions
103+
├── LICENSE.txt # Optional license file
104+
├── scripts/
105+
│ └── helper.py # Executable automation
106+
├── references/
107+
│ ├── api-reference.md # Detailed docs
108+
│ └── examples.md # Usage examples
109+
├── assets/
110+
│ └── diagram.png # Static resources
111+
└── templates/
112+
└── starter.ts # Code scaffold
113+
```
114+
115+
## Quick Start: Duplicate This Template
116+
117+
1. Copy the `make-skill-template/` folder
118+
2. Rename to your skill name (lowercase, hyphens)
119+
3. Update `SKILL.md`:
120+
- Change `name:` to match folder name
121+
- Write a keyword-rich `description:`
122+
- Replace body content with your instructions
123+
4. Add bundled resources as needed
124+
5. Validate with `npm run skill:validate`
125+
126+
## Validation Checklist
127+
128+
- [ ] Folder name is lowercase with hyphens
129+
- [ ] `name` field matches folder name exactly
130+
- [ ] `description` is 10-1024 characters
131+
- [ ] `description` explains WHAT and WHEN
132+
- [ ] `description` is wrapped in single quotes
133+
- [ ] Body content is under 500 lines
134+
- [ ] Bundled assets are under 5MB each
135+
136+
## Troubleshooting
137+
138+
| Issue | Solution |
139+
|-------|----------|
140+
| Skill not discovered | Improve description with more keywords and triggers |
141+
| Validation fails on name | Ensure lowercase, no consecutive hyphens, matches folder |
142+
| Description too short | Add capabilities, triggers, and keywords |
143+
| Assets not found | Use relative paths from skill root |
144+
145+
## References
146+
147+
- Agent Skills official spec: <https://agentskills.io/specification>

0 commit comments

Comments
 (0)