make-skill-template

SKILL.md

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.

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:

skills/<skill-name>/
└── SKILL.md          # Required

Step 2: Generate SKILL.md with Frontmatter

Every skill requires YAML frontmatter with name and description:

---
name: <skill-name>
description: '<What it does>. Use when <specific triggers, scenarios, keywords users might say>.'
---

Frontmatter Field Requirements

Field
Required
Constraints

name
Yes
1-64 chars, lowercase letters/numbers/hyphens only, must match folder name

description
Yes
1-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:

WHAT the skill does (capabilities)

WHEN to use it (triggers, scenarios, file types)

Keywords users might mention in prompts

Good example:

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:

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

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

Example: Complete Skill Structure

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

Copy the make-skill-template/ folder

Rename to your skill name (lowercase, hyphens)

Update SKILL.md:

Change name: to match folder name

Write a keyword-rich description:

Replace body content with your instructions

Add bundled resources as needed

Validate with npm run skill:validate

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 is under 500 lines

 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: https://agentskills.io/specification