SKILL: Create Skill

Last Updated: February 5, 2026

Table of Contents

• •SKILL: Create Skill
  • •Table of Contents
  • •1. Overview
  • •2. Required Components
    • •2.1 YAML Frontmatter
    • •2.2 Document Structure
    • •2.3 Optional Directories
  • •3. Execution Workflow
  • •4. Best Practices
  • •5. Self-Assessment Protocol
  • •6. Variable Reference

1. Overview

Guides creation of SKILL files per the agentskills.io specification. A SKILL file defines a repeatable task for AI agents: YAML frontmatter (metadata), body content (instructions), and optional directories (scripts, references, assets).

Use when: Task is repeatable, multiple users benefit, requires domain knowledge, output should be standardized.

Do NOT use when: One-time task, existing skills cover it, task too simple, no structured output needed.

2. Required Components

2.1 YAML Frontmatter

🚨 CRITICAL: Must comply with agentskills.io specification.

Name Rules: Must start with verb (validate, process, analyze, create, review), match parent directory name.

Example:

---
name: validate-order
description: Validates restaurant order data against menu and inventory constraints. Use when processing customer orders.
metadata:
  author: example-org
  version: 1.0
  display-name: Validate Order
  keywords: [order, validate, menu]
  example-prompt:
    - Validate the order data in OrderController.cs
---

2.2 Document Structure

Keep under 500 lines per RULE_Document.md. Move detailed references to references/ directory.

2.3 Optional Directories

.ai-toolbox/skills/{skill_name}/
├── SKILL.md       # Required
├── scripts/       # Executable code (Python, Bash, JS)
├── references/    # Additional documentation
└── assets/        # Templates, images, data files

3. Execution Workflow

Step 1: Gather Requirements

1. •Identify repeatable task to automate
2. •List inputs, outputs, decision points
3. •Review existing SKILL files for patterns

Step 2: Define Metadata

1. •Choose name (lowercase, hyphens, verb-first, max 64 chars)
2. •Write description (max 1024 chars, what AND when)
3. •Add optional fields under metadata

Step 3: Write Content

1. •Overview section (one-liner intro + purpose)
2. •Execution Workflow (4-6 steps)
3. •Self-Assessment Protocol with 🚨 CRITICAL marker

Step 4: Optimize and Validate

1. •Remove redundant words, use tables for structured data
2. •Verify frontmatter complies with spec
3. •Confirm under 500 lines

Step 5: Finalize

1. •Run format-markdown skill
2. •Verify all changes applied correctly

Output (File): .ai-toolbox/skills/{skill_name}/SKILL.md (template: assets/TEMPLATE_Skill.md)

4. Best Practices

Workflow Format:

Progressive Disclosure: Metadata (~100 tokens) loaded at startup, full body (<5000 tokens) when activated, resources loaded on demand.

Common Mistakes:

Token Optimization: Use tables over prose, prefer bullets over paragraphs, replace "it/this/that" with specific nouns.

5. Self-Assessment Protocol

🚨 CRITICAL: Before presenting results, verify:

Frontmatter:

• • name is 1-64 chars, lowercase, hyphens, starts with verb
• • name has no --, doesn't start/end with hyphen
• • description is 1-1024 chars, explains what AND when
• • Custom fields placed under metadata

Structure:

• • H1 follows # SKILL: {topic_name} format
• • Last Updated date present
• • TOC includes all H2/H3 sections
• • Overview, Execution Workflow, Self-Assessment present

Quality:

• • SKILL.md under 500 lines
• • Steps are specific and actionable
• • Run format-markdown skill validation
• • No redundant words or filler phrases

6. Variable Reference