Skill Creator

Create comprehensive Agent Skills for Claude Code plugins with proper structure, YAML frontmatter, progressive disclosure, and all necessary bundled resources.

When to Use This Skill

Use this skill when:

• Creating a new Agent Skill for a plugin
• User requests "create a skill", "add a skill", or "build a skill"
• Adding specialized capabilities to a plugin
• Need to author SKILL.md files with proper format
• Setting up skill directories with scripts, references, and assets

What This Skill Does

Creates complete Agent Skill including:

• SKILL.md with proper YAML frontmatter and instructions
• scripts/ directory for executable code (optional)
• references/ directory for documentation (optional)
• assets/ directory for templates and resources (optional)
• Validation of SKILL.md format and structure

Core Skill Structure

Every skill consists of a directory containing:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded as needed
    └── assets/           - Files used in output (templates, etc.)

Bundled Tools

This skill provides two scripts to streamline skill creation:

scripts/init_skill.py - Scaffold new skill directory structure

• Creates SKILL.md template with TODO placeholders
• Creates optional resource directories (scripts/, references/, assets/)
• Generates example files demonstrating proper structure
• Supports flags: --all, --with-scripts, --with-references, --with-assets, --dry-run, --json
• --dry-run: Preview structure without creating files (useful in planning mode)
• --json: Output result as JSON for programmatic parsing

scripts/validate_skill.py - Validate skill compliance

• Checks YAML frontmatter format and required fields
• Validates naming conventions and file structure
• Reports errors (must fix) and warnings (should address)
• Run before completing skill creation

See the Instructions section below for the complete skill creation workflow.

Instructions

Step 1: Understand the Skill Requirements

Gather information about the skill to create:

• Purpose: What problem does this skill solve?
• When to trigger: When should Claude use this skill?
• Functionality: What specific actions should it perform?
• Resources needed: Scripts, references, assets required?
• Tool requirements: Which tools must the skill use?

Ask clarifying questions if needed to fully understand the skill's scope.

Step 2: Design the Skill Structure

Determine what components are needed:

Always required:

• SKILL.md with frontmatter and instructions

Optional components:

1. scripts/ - For executable code when:

   • Code is repeatedly rewritten
   • Deterministic reliability is needed
   • Logic is complex or procedural

2. references/ - For documentation when:

   • Additional reference material is needed
   • Documentation should be loaded on-demand
   • Information is detailed (schemas, APIs, guides)

3. assets/ - For templates/files when:

   • Templates are used in output
   • Images/fonts/resources are needed
   • Boilerplate code is provided

Step 3: Initialize the Skill Directory

Run the init_skill.py script to create the skill structure:

python scripts/init_skill.py <skill-name> --path <plugin-skills-directory>

Optional flags:

• --with-scripts: Create scripts/ directory
• --with-references: Create references/ directory
• --with-assets: Create assets/ directory
• --all: Create all optional directories
• --dry-run: Preview what will be created without creating files
• --json: Output result as JSON format

The script creates:

• Skill directory
• SKILL.md template with TODO placeholders
• Optional resource directories
• Example files demonstrating structure

Preview before creating:

Use --dry-run to see what will be created without making changes:

python scripts/init_skill.py my-skill --path ./skills --all --dry-run

Combine with --json for programmatic parsing (useful for AI assistants in planning mode):

python scripts/init_skill.py my-skill --path ./skills --all --dry-run --json

This outputs structured JSON:

{
  "success": true,
  "skill_path": "/path/to/skills/my-skill",
  "files_created": ["SKILL.md", "scripts/example_script.py", ...],
  "directories_created": ["my-skill/", "scripts/", ...],
  "next_steps": ["edit_skill_md", "update_frontmatter", ...]
}

Step 4: Author the SKILL.md File

Create comprehensive SKILL.md with:

1. YAML Frontmatter (required)

---
name: skill-name
description: Clear description of what the skill does and when to use it
allowed-tools: Tool1, Tool2, Tool3  # Optional: restrict tool access
---

Frontmatter requirements:

• name: Lowercase letters, numbers, hyphens only (max 64 chars)
• description: Specific description including triggers (max 1024 chars)
• allowed-tools: Optional comma-separated tool list

2. Skill Instructions (required)

Write instructions using imperative/infinitive form (verb-first):

✓ Correct: "To accomplish X, do Y" ✗ Wrong: "You should do X"

Include:

• Clear purpose statement
• When to use the skill
• Step-by-step instructions
• Examples and use cases
• References to bundled resources

3. Progressive Disclosure

Keep SKILL.md lean by referencing detailed information (examples):

Example 1 - Link to additional documentation bundled within the skill:

For complete API documentation, see [references/api-docs.md](references/api-docs.md).

Example 2 - Run the processing script bundled with the skill:

python scripts/process.py input.txt

Step 5: Create Bundled Resources

scripts/ - Executable code

Create scripts for:

• Deterministic operations
• Complex procedural logic
• Tasks repeatedly rewritten

Example:

#!/usr/bin/env python3
# scripts/process.py
# Script functionality here

Make executable: chmod +x scripts/process.py

references/ - Documentation

Create reference docs for:

• Database schemas
• API specifications
• Domain knowledge
• Detailed workflows

Example:

# references/schema.md

## Database Schema

Tables and relationships...

assets/ - Output templates

Create assets for:

• Templates (HTML, config files)
• Images (logos, icons)
• Boilerplate code
• Sample documents

Step 6: Validate the Skill

Run validation to ensure correctness:

python scripts/validate_skill.py <path/to/skill-directory>

The validator checks:

• YAML frontmatter format
• Required fields present
• Name follows conventions
• Description is specific
• File organization
• Resource references

Fix any validation errors before completing.

Step 7: Test the Skill

After creation:

1. Install the plugin containing the skill
2. Ask questions that should trigger the skill
3. Verify Claude uses the skill autonomously
4. Check that resources load correctly
5. Iterate on description if skill doesn't trigger

YAML Frontmatter Quick Reference

Every SKILL.md begins with YAML frontmatter:

---
name: skill-name                    # Required: lowercase, hyphens only
description: What and when to use   # Required: <1024 chars, specific
allowed-tools: Read, Write, Bash    # Optional: restrict tool access
---

Required fields:

• name: Lowercase letters, numbers, hyphens only (max 64 chars)
• description: Specific description with triggers and file types (max 1024 chars)

Optional fields:

• allowed-tools: Comma-separated tool list to restrict access

For complete frontmatter guidance, including examples, validation rules, and description writing tips, see references/yaml-frontmatter-guide.md.

Progressive Disclosure Pattern

Skills use three-level loading:

1. Metadata (always loaded): ~100 words
2. SKILL.md body (when triggered): <5k words
3. Bundled resources (as needed): Unlimited

Keep SKILL.md focused on workflow. Move detailed reference material to references/ files.

Examples of references:

# SKILL.md
To process PDFs, use the rotation script.

For form field mappings, see [references/form-fields.md](references/form-fields.md).

Run the script:
```bash
python scripts/rotate_pdf.py input.pdf 90
```

Examples

Simple commit-helper Skill example (single file)

commit-helper/
└── SKILL.md

SKILL.md:

```yaml
---
name: commit-helper
description: Generate clear git commit messages from staged changes. Use when writing commits or reviewing diffs.
---
```

# Commit Helper

Generate clear, conventional commit messages following best practices.

## When to Use This Skill

Use this skill when:
- Writing commit messages for staged changes
- User asks to "commit" or "create a commit"
- Reviewing what will be committed

## Instructions

### Step 1: Review Staged Changes

Run `git diff --staged` to see all changes that will be committed.

### Step 2: Generate Commit Message

Create a commit message with:
- **Summary line**: Under 50 characters, imperative mood
- **Blank line**: Separate summary from body
- **Detailed description**: Explain what changed and why
- **Affected components**: List modified areas

### Step 3: Format the Commit

Follow conventional commit format:

```text
type(scope): brief summary

- Detailed change 1
- Detailed change 2
- Why these changes were needed
```

Common types: feat, fix, docs, refactor, test, chore

Skill with Scripts

pdf-processor/
├── SKILL.md
└── scripts/
    ├── rotate_pdf.py
    └── extract_text.py

SKILL.md references scripts for PDF operations.

Multi-file Skill

bigquery-analyst/
├── SKILL.md
├── references/
│   ├── schema.md
│   └── best-practices.md
└── scripts/
    └── query_helper.py

SKILL.md references schema.md for table structures.

Progressive Disclosure Example

This example demonstrates proper use of bundled resources:

api-tester/
├── SKILL.md
├── scripts/
│   └── send_request.py
├── references/
│   └── http-methods.md
└── assets/
    └── request-template.json

SKILL.md (excerpt):

## Instructions

### Step 1: Choose HTTP Method

Common methods: GET, POST, PUT, DELETE, PATCH

For complete HTTP method documentation and use cases, see [references/http-methods.md](references/http-methods.md).

### Step 2: Build Request

Use the template in `assets/request-template.json` as a starting point.

### Step 3: Send Request

Run the request script:
```bash
python scripts/send_request.py --url <url> --method <method> --data <data>
```

The script handles authentication, headers, and error handling automatically.

Why this works:

• SKILL.md stays focused on workflow
• Detailed HTTP method docs in references/ (loaded only when needed)
• Template in assets/ (used as needed)
• Script handles complex logic deterministically

Validation Rules

The validate_skill.py script checks:

Structure:

• SKILL.md exists
• YAML frontmatter present
• Required fields populated

Naming:

• name uses lowercase, numbers, hyphens only
• No reserved words
• No XML tags

Description:

• Not empty
• Under 1024 characters
• Specific and actionable

Files:

• Resources properly organized
• Scripts are executable
• References exist if mentioned

Troubleshooting

Skill doesn't trigger:

• Make description more specific
• Include trigger keywords
• Add file types or domains
• Test with direct questions

Validation errors:

• Check YAML syntax
• Verify name follows rules
• Ensure description is complete
• Confirm file structure

Resources not loading:

• Use relative paths
• Reference from SKILL.md
• Check file exists
• Verify markdown links

Best Practices

1. Start simple: Begin with SKILL.md only, add resources as needed
2. Specific descriptions: Include triggers and file types
3. Imperative voice: Use verb-first instructions
4. Progressive disclosure: Keep SKILL.md lean, use references
5. Scripts for repetition: Code that's repeatedly rewritten
6. Test thoroughly: Verify skill triggers correctly
7. Validate early: Run validation before completion

Reference Documentation

For complete skill authoring guidance, see:

• references/skill-best-practices.md - Comprehensive best practices
• Official Claude Code docs at https://code.claude.com/docs/en/skills

Version History

• v1.0.0 - 2025-11-15 - Initial release of Skill Creator skill