Skill Creation Guide Template

This guide provides a structured approach for building a new skill from scratch, including proper structure, frontmatter, and best practices.

Overview

Creating a skill involves defining its purpose, structuring the files correctly, writing clear instructions, and ensuring the skill is safe and useful. This guide walks through each step of the creation process.

Skill Details

Before creating a skill, define:

• Name: A clear, descriptive identifier (lowercase, hyphenated)
• Description: A concise explanation of what the skill does
• Purpose: The problems this skill solves
• Target Users: Who will benefit from this skill

Directory Structure

Create the following structure for your skill:

skill-name/
  SKILL.md           # Main skill file (required)
  references/        # Reference documentation (optional)
  scripts/           # Executable scripts (optional)
  assets/            # Images, data files (optional)

Directory Descriptions

| Directory | Purpose | Contents | |-----------|---------|----------| | SKILL.md | Main entry point | Instructions, examples, metadata | | references/ | Supporting docs | Detailed guides, API references | | scripts/ | Automation | Shell scripts, Python scripts | | assets/ | Static files | Images, templates, data files |

Step 1: Create the SKILL.md

The SKILL.md file is the heart of your skill. It must have YAML frontmatter followed by markdown content.

SKILL.md Template

---
name: skill-name
description: A brief description of what this skill does
version: 1.0.0
author: your-name
license: MIT
---

# Skill Name

Brief description of what this skill does.

## Overview

Describe the skill's purpose, capabilities, and when it should be used. This section helps users quickly understand if this skill is relevant to their needs.

## Usage

### When to Use This Skill

- Scenario 1 where this skill is helpful
- Scenario 2 where this skill is helpful
- Specific problems it solves

### Prerequisites

- Required tool or dependency
- Required knowledge or setup
- Any system requirements

## Instructions

### Step 1: [First Step Title]

Describe the first step in using this skill. Be specific and actionable.

### Step 2: [Second Step Title]

Continue with subsequent steps. Include code examples where helpful.

```bash
# Example command
example-command --flag value

Examples

Example 1: [Basic Usage]

Show a simple, common use case:

# Code or command example
example here

Expected output:

# What the user should see
output here

Example 2: [Advanced Usage]

Show a more complex scenario:

# More advanced example
complex example here

References

Link to reference documentation:

• Reference Name - What this reference covers

Scripts

Document available scripts:

• Script Name - What this script does

Notes

Any additional notes, warnings, or tips:

• Important consideration 1
• Warning about common mistake
• Tip for better results

### Frontmatter Requirements

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill identifier (lowercase, hyphenated) |
| `description` | Yes | Brief description (1-2 sentences) |
| `version` | No | Semantic version (e.g., 1.0.0) |
| `author` | No | Creator's name or handle |
| `license` | No | License type (e.g., MIT, Apache-2.0) |

## Step 2: Add Reference Documentation (Optional)

Create files in the `references/` directory for detailed information.

### Reference File Guidelines

- Use markdown format (.md)
- One topic per file
- Include practical examples
- Link from SKILL.md

### Example Reference Structure

references/ api-reference.md # API documentation configuration.md # Configuration options troubleshooting.md # Common issues and solutions advanced-usage.md # Advanced patterns

### Reference Template

```markdown
# [Topic Name]

## Overview
Brief introduction to this topic.

## Details

### [Subtopic 1]
Detailed explanation...

### [Subtopic 2]
Detailed explanation...

## Examples

### Example 1
```code
example

See Also

• Links to related references

## Step 3: Create Scripts (Optional)

Create executable scripts in the `scripts/` directory for automation.

### Script Requirements

1. **Shebang Line**: Start with appropriate interpreter
   ```bash
   #!/bin/bash
   # or
   #!/usr/bin/env python3

2. Help/Usage: Include help information

   if [[ "$1" == "-h" || "$1" == "--help" ]]; then
       echo "Usage: script-name.sh [options] <args>"
       echo "Description of what the script does"
       exit 0
   fi
   

3. Input Validation: Validate all inputs

   if [[ -z "$1" ]]; then
       echo "Error: Missing required argument"
       exit 1
   fi
   

4. Error Handling: Handle errors gracefully

   set -euo pipefail  # Exit on error, undefined var, pipe failure
   

Script Security Guidelines

| Do | Don't | |----|-------| | Validate all inputs | Use eval with user input | | Quote variables | Hardcode secrets | | Use full paths | Ignore error codes | | Limit file access | Write outside skill directory | | Log actions | Trust external input |

Example Script Template

#!/bin/bash
# Script: script-name.sh
# Description: What this script does
# Usage: script-name.sh [options] <required-arg>

set -euo pipefail

# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Help function
show_help() {
    cat << EOF
Usage: $(basename "$0") [options] <required-arg>

Description:
    What this script does in detail.

Arguments:
    required-arg    Description of the argument

Options:
    -h, --help      Show this help message
    -v, --verbose   Enable verbose output

Examples:
    $(basename "$0") example-value
    $(basename "$0") -v example-value
EOF
}

# Parse arguments
VERBOSE=false
while [[ $# -gt 0 ]]; do
    case "$1" in
        -h|--help)
            show_help
            exit 0
            ;;
        -v|--verbose)
            VERBOSE=true
            shift
            ;;
        *)
            break
            ;;
    esac
done

# Validate required argument
if [[ $# -lt 1 ]]; then
    echo "Error: Missing required argument" >&2
    show_help
    exit 1
fi

ARG="$1"

# Main logic
main() {
    if $VERBOSE; then
        echo "Processing: $ARG"
    fi

    # Your code here
    echo "Result for: $ARG"
}

main

Step 4: Add Assets (Optional)

Add supporting files to the assets/ directory:

• Images: Diagrams, screenshots for documentation
• Templates: Starter files users can copy
• Data Files: JSON schemas, configuration examples
• Other: Any static files the skill needs

Asset Organization

assets/
  images/
    diagram.png
    screenshot.png
  templates/
    config-template.yaml
    starter-file.txt
  data/
    schema.json

Step 5: Test the Skill

Before publishing, verify your skill works correctly.

Testing Checklist

SKILL.md Validation

• [ ] Frontmatter parses correctly (valid YAML)
• [ ] Name and description are present
• [ ] All internal links work
• [ ] Code blocks are properly formatted
• [ ] Instructions are clear and complete

Script Testing

• [ ] Scripts execute without errors
• [ ] Help flag works (-h, --help)
• [ ] Invalid input is handled gracefully
• [ ] Edge cases are handled
• [ ] Output matches documentation

Reference Validation

• [ ] All referenced files exist
• [ ] Links from SKILL.md work
• [ ] Content is accurate and helpful

Discovery Testing

• [ ] Skill appears in skill list
• [ ] Description is displayed correctly
• [ ] Skill can be activated

Step 6: Final Validation

Complete final validation before release.

Validation Checklist

• [ ] Valid YAML frontmatter with name and description
• [ ] Clear instructions for use
• [ ] All scripts documented
• [ ] Examples provided where helpful
• [ ] No broken internal links
• [ ] Scripts handle errors gracefully
• [ ] No hardcoded secrets or credentials
• [ ] Appropriate license declared

Skill Locations

Skills can be installed in these locations:

| Location | Scope | Priority | |----------|-------|----------| | ./.claude/skills/ | Project | Highest | | ~/.claude/skills/ | User | High | | ~/.codex/skills/ | User (Codex) | Medium | | ~/.cursor/skills/ | User (Cursor) | Medium |

Installation Commands

# Project-level installation
mkdir -p ./.claude/skills/skill-name
cp -r skill-name/* ./.claude/skills/skill-name/

# User-level installation
mkdir -p ~/.claude/skills/skill-name
cp -r skill-name/* ~/.claude/skills/skill-name/

Best Practices

Writing Quality

• Be Concise: Don't over-explain simple concepts
• Be Complete: Cover all necessary steps
• Be Practical: Include real-world examples
• Be Consistent: Use consistent formatting and terminology

Maintenance

• Version Updates: Increment version for changes
• Changelog: Document what changed
• Compatibility: Note breaking changes
• Testing: Re-test after updates

Security

• Review Scripts: Audit all script code
• Minimal Permissions: Request only what's needed
• No Secrets: Never include credentials
• Safe Defaults: Default to safe behavior

Creation Workflow Summary

1. PLAN
   ├── Define purpose
   ├── Identify use cases
   └── Plan structure

2. CREATE
   ├── Write SKILL.md
   ├── Add references
   └── Create scripts

3. TEST
   ├── Validate SKILL.md
   ├── Test scripts
   └── Verify links

4. VALIDATE
   ├── Complete checklist
   ├── Security review
   └── Documentation review

5. INSTALL
   ├── Choose location
   └── Copy files