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 AI assistant 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

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 prompts

Good example:

description: 'Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.'

Poor example:

description: 'Helps with PDFs.'

Advanced Frontmatter Example

For skills with specific compatibility needs or metadata:

---
name: database-optimizer
description: 'Analyzes SQL queries, suggests indexes, and optimizes database schema. Use when working with databases, SQL, performance issues, slow queries, or when the user mentions database optimization, indexing, or query tuning.'
compatibility: 'Requires PostgreSQL 12+, MySQL 8+, or SQLite 3.35+'
metadata:
  version: '1.2.0'
  author: 'Database Team'
  last-updated: '2026-01-15'
allowed-tools: 'read_file run_in_terminal grep_search'
---

Step 3: Write the Skill Body

After the frontmatter, add markdown instructions. Recommended sections:

Step 4: Add Optional Directories (If Needed)

Best Practices for Bundled Resources:

• •Keep total skill size under 10MB for performance
• •Use references/ for content loaded on-demand via explicit file references
• •Place frequently needed content directly in SKILL.md
• •Store binary files (images, PDFs) in assets/ only when essential
• •Scripts should be self-contained with clear usage comments

Example: Complete Skill Structure

my-awesome-skill/
├── SKILL.md                    # Required instructions
├── LICENSE.txt                 # Optional license file
├── scripts/
│   └── helper.py               # Executable automation
├── references/
│   ├── REFERENCE.md            # Detailed technical reference
│   └── examples.md             # Usage examples
├── assets/
│   ├── diagram.png             # Static resources
│   └── template.json           # Configuration templates

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 (scripts, references, assets)
5. •Test the skill with a real prompt to verify it triggers correctly
6. •Validate with skills-ref validate ./your-skill-name/ (if available)

Testing Your Skill

Before deploying a new skill, verify it works correctly:

1. •

   Trigger Test: Create a prompt that should activate the skill

   • •Example: For a PDF skill, try "extract text from this PDF"
   • •Verify the AI assistant loads and uses your skill
2. •

   Resource Test: If you have bundled resources, reference them explicitly

   • •Example: "Use the template in assets/config.json"
   • •Confirm the assistant can access and use the resources
3. •

   Edge Case Test: Try ambiguous prompts to ensure proper skill selection

   • •Test with similar but different requests
   • •Verify your skill only triggers for appropriate scenarios
4. •

   Validation: Run formal validation if tools are available

   bash

   skills-ref validate ./your-skill-name/
   

Validation Checklist

• • Folder name is lowercase with hyphens, no special characters
• • name field matches folder name exactly (case-sensitive)
• • description is 1-1024 characters with WHAT, WHEN, and keywords
• • description explains WHAT it does and WHEN to use it
• • description includes specific keywords and trigger phrases
• • Body content is under 500 lines (recommended for performance)
• • File references are one level deep from SKILL.md
• • Tested with real prompts that should trigger the skill
• • No sensitive information or credentials in skill files
• • All bundled scripts have clear usage documentation

Concrete Example: Creating a JSON Formatter Skill

Here's a complete example of creating a simple skill:

1. Create folder:

mkdir -p skills/json-formatter

2. Create SKILL.md:

---
name: json-formatter
description: 'Formats, validates, and minifies JSON data. Use when working with JSON files, formatting JSON, validating JSON syntax, or when the user mentions JSON, formatting, or prettifying data.'
---

# JSON Formatter

Formats and validates JSON data with proper indentation and error checking.

## When to Use This Skill

- User asks to format, prettify, or validate JSON
- Working with JSON configuration files
- Debugging malformed JSON

## Capabilities

- Format JSON with proper indentation
- Validate JSON syntax and report errors
- Minify JSON for production use
- Convert between JSON and other formats

## Usage Examples

**Format JSON:**
```bash
python scripts/format.py input.json --indent 2

Validate JSON:

python scripts/validate.py input.json

**3. Add script (optional):**
```python
# scripts/format.py
import json
import sys

with open(sys.argv[1], 'r') as f:
    data = json.load(f)
    print(json.dumps(data, indent=2))

Troubleshooting

Skill Lifecycle & Maintenance

Versioning

Track skill versions in metadata:

metadata:
  version: '1.0.0'  # MAJOR.MINOR.PATCH
  last-updated: '2026-01-21'

Version Guidelines:

• •MAJOR: Breaking changes to skill behavior or required inputs
• •MINOR: New capabilities or significant enhancements
• •PATCH: Bug fixes, documentation updates, minor improvements

Updating Skills

When modifying existing skills:

1. •Test changes with previous working prompts to ensure backward compatibility
2. •Update last-updated in metadata
3. •Increment version appropriately
4. •Document changes in skill body or changelog
5. •Re-validate if making structural changes

Deprecating Skills

To retire a skill:

1. •Update description to note deprecation and suggest alternative
2. •Keep skill functional but add deprecation notice in body
3. •After transition period, remove skill folder

References

• •Agent Skills Specification - Official spec and schema
• •Agent Skills Home - Documentation and guides
• •skills-ref validation library - CLI validation tool
• •Example skills - Reference implementations

See Also

• •Other skills in this workspace for pattern examples
• •Project-specific AGENTS.md files for integration guidance