Skill Format

Skills are defined in SKILL.md files with YAML frontmatter and markdown content.

File Structure

my-skill/
  SKILL.md      # Required: skill definition
  examples/     # Optional: example files
  templates/    # Optional: code templates

Frontmatter

Required and optional fields in the YAML frontmatter:

---
name: my-skill           # Required: unique identifier
description: Brief desc  # Required: one-line summary
version: 1.0.0          # Optional: semver version
author: Your Name       # Optional: skill author
tags:                   # Optional: categorization
  - code-review
  - security
---

Required Fields

| Field | Description | |-------|-------------| | name | Unique skill identifier (lowercase, hyphens) | | description | Brief one-line description |

Optional Fields

| Field | Description | |-------|-------------| | version | Semantic version (e.g., 1.0.0) | | author | Skill creator name or handle | | tags | Array of category tags |

Content Sections

Title

Start with a level-1 heading matching the skill name:

# My Skill

Description

One or two paragraphs explaining what the skill does:

This skill helps developers write consistent commit messages
following the Conventional Commits specification.

When to Use

Describe scenarios when this skill applies:

## When to Use
 
Use this skill when:
- Creating git commits
- Writing changelog entries

Instructions

Detailed instructions for the AI agent:

## Instructions
 
1. Analyze the staged changes
2. Determine the commit type (feat, fix, docs, etc.)
3. Generate a commit message in format: type(scope): description

Examples

Concrete examples of expected behavior:

## Examples
 
Input: Added new login button
Output: feat(auth): add login button to header

Best Practices

Keep instructions clear and concise
Use bullet points and numbered lists
Provide concrete examples
Define scope boundaries (what to do and not do)
Test with your target AI agent before sharing