gh-m-brady-claude-plugins-plugins-skill-creator-plugin/skills/skill-creator/REFERENCE.md

Skill Creator Reference

Comprehensive reference for creating Claude Code skills.

Table of Contents

• Validation Rules
• YAML Frontmatter Specification
• Description Best Practices
• File Organization
• Tool Restrictions
• Testing Skills

Validation Rules

Name Requirements

Format: ^[a-z0-9-]+$

• Only lowercase letters (a-z)
• Numbers (0-9)
• Hyphens (-)
• No spaces, underscores, or special characters
• Maximum length: 64 characters

Valid examples:

• pdf-processor
• commit-helper
• log-analyzer-2
• api-client-gen

Invalid examples:

• PDF_Processor (uppercase and underscore)
• commit helper (space)
• log.analyzer (period)
• api-client! (special character)

Description Requirements

Length: Maximum 1024 characters

Must include:

1. What the skill does (capabilities)
2. When to use it (triggers)
3. Key terms for discovery

Structure:

[What it does]. [When to use it]. [Optional: Requirements].

Good example:

Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDF files, forms, or document extraction.
Requires pypdf and pdfplumber packages.

Poor example:

Helps with documents.

YAML Frontmatter Rules

Structure:

---
name: skill-name
description: Skill description
allowed-tools: Tool1, Tool2, Tool3  # Optional
---

Rules:

• Must start with --- on line 1
• Must end with --- before content starts
• Use spaces, not tabs
• Required fields: name, description
• Optional fields: allowed-tools
• Follow YAML syntax strictly

Common errors:

# Error: Missing opening ---
name: skill-name
---

# Error: Tab character instead of spaces
---
name:	skill-name  # <- Tab here
---

# Error: Unquoted string with special chars
---
description: It's a skill  # <- Apostrophe breaks YAML
---

# Fix: Quote strings with special chars
---
description: "It's a skill"
---

YAML Frontmatter Specification

Required Fields

name

• Type: String
• Format: ^[a-z0-9-]+$
• Max length: 64 characters
• Must be unique within the skill directory

description

• Type: String
• Max length: 1024 characters
• Should be descriptive and include triggers

Optional Fields

allowed-tools

• Type: String (comma-separated) or Array
• Valid tools: Read, Write, Edit, Glob, Grep, Bash, etc.
• Restricts which tools Claude can use with this skill

String format:

allowed-tools: Read, Grep, Glob

Array format:

allowed-tools:
  - Read
  - Grep
  - Glob

Description Best Practices

Include What and When

Structure: [Capabilities]. [When to use]. [Requirements].

Use Specific Triggers

Include terms users would actually say:

Good:

• "working with Excel files"
• "analyzing log files"
• "creating API clients"
• "when the user mentions PDFs"

Poor:

• "for data"
• "helps with files"
• "general purpose"

Examples by Domain

File Processing

Process and analyze [file type] files, [specific operations].
Use when working with [file extensions], [user terms], or [tasks].

Development Tools

[Action] for [technology/framework], [specific features].
Use when [development task], [user scenario], or [technical context].

Analysis Skills

Analyze [data type] for [patterns/metrics], [output format].
Use when [analysis task], [debugging scenario], or [investigation type].

File Organization

Basic Structure

skill-name/
└── SKILL.md (required)

With Supporting Files

skill-name/
├── SKILL.md (required)
├── REFERENCE.md (optional - detailed docs)
├── EXAMPLES.md (optional - more examples)
├── scripts/
│   ├── helper.py
│   └── validator.js
└── templates/
    ├── template1.txt
    └── template2.md

File Naming Conventions

• Use lowercase
• Use hyphens for spaces
• Use descriptive names
• Group by type in subdirectories

Good:

• scripts/validate-input.py
• templates/api-client-template.ts
• docs/advanced-usage.md

Poor:

• Scripts/ValidateInput.py
• template.txt
• file1.md

Referencing Files

Use relative paths from SKILL.md:

See [detailed documentation](REFERENCE.md).
For examples, check [EXAMPLES.md](EXAMPLES.md).

Run the helper:
```bash
python scripts/helper.py

## Tool Restrictions

Use `allowed-tools` to limit tool access for safety and focus.

### Common Patterns

#### Read-Only Skills
```yaml
allowed-tools: Read, Grep, Glob

Use for:

• Analysis tasks
• Log investigation
• Code review
• Documentation reading

Analysis with Execution

allowed-tools: Read, Grep, Glob, Bash

Use for:

• Data analysis that needs computation
• Test execution
• Build analysis

Limited Write Access

allowed-tools: Read, Write, Grep, Glob

Use for:

• Report generation
• Template expansion
• Safe file creation

Available Tools

Common tools you can restrict to:

• Read: Read file contents
• Write: Create new files
• Edit: Modify existing files
• Glob: Find files by pattern
• Grep: Search file contents
• Bash: Execute shell commands
• WebFetch: Fetch web content
• WebSearch: Search the web

When to Use Tool Restrictions

Use restrictions when:

• Skill should be read-only
• Skill has limited scope
• Security is important
• You want to prevent accidental modifications

Don't restrict when:

• Skill needs full flexibility
• Multiple operations required
• User might need varied access

Testing Skills

Pre-Testing Checklist

Before testing a new skill:

1. Validate YAML:

   head -n 20 SKILL.md
   # Check frontmatter format
   

2. Check file location:

   # Personal
   ls ~/.claude/skills/skill-name/SKILL.md
   
   # Project
   ls .claude/skills/skill-name/SKILL.md
   
   # Plugin
   ls plugin-name/skills/skill-name/SKILL.md
   

3. Verify name format:

   • Lowercase, numbers, hyphens only
   • No spaces or special characters

4. Check description:

   • Includes what and when
   • Contains trigger terms
   • Under 1024 characters

Testing Process

1. Restart Claude Code:

   # Skills load at startup
   claude
   

2. Test with trigger phrases:

   • Use terms from your description
   • Ask questions that match "when to use"
   • Vary phrasing to test discovery

3. Verify activation:

   • Skill should activate automatically
   • Claude should follow instructions
   • Supporting files should load when referenced

4. Test edge cases:

   • Invalid inputs
   • Missing dependencies
   • Error conditions

Debug Mode

Run with debug flag to see skill loading:

claude --debug

Look for:

• Skill discovery messages
• Loading errors
• YAML parse errors
• File not found errors

Common Test Scenarios

Scenario 1: Does it activate?

User: [Use trigger phrase from description]
Expected: Skill activates and provides help

Scenario 2: Are restrictions working?

User: [Request that needs restricted tool]
Expected: Permission denied or alternative approach

Scenario 3: Do supporting files load?

User: [Ask question requiring reference docs]
Expected: Claude references the supporting file

Troubleshooting

Skill Doesn't Activate

Check: Description specificity

• Add more trigger terms
• Be more explicit about when to use
• Include user vocabulary

Check: YAML validity

# View frontmatter
cat SKILL.md | head -n 10

Check: File location

# Verify SKILL.md exists in correct location
ls [path]/SKILL.md

YAML Parse Errors

Common causes:

• Tabs instead of spaces
• Missing quotes around special characters
• Invalid structure
• Missing opening/closing ---

Fix:

# Before (broken)
---
description: It's broken
---

# After (fixed)
---
description: "It's fixed"
---

Tool Restrictions Not Working

Verify syntax:

# Correct
allowed-tools: Read, Grep, Glob

# Also correct
allowed-tools:
  - Read
  - Grep
  - Glob

Check tool names:

• Use exact tool names (case-sensitive)
• Common names: Read, Write, Edit, Bash, Grep, Glob
• Separate with commas in string format

Supporting Files Not Loading

Check paths:

• Use relative paths from SKILL.md
• Use forward slashes (/)
• Don't use absolute paths

Check file exists:

cd skill-directory
ls -la
# Verify all referenced files exist

Best Practices Summary

DO

• Keep skills focused on one capability
• Write specific, detailed descriptions
• Include trigger terms users would say
• Use tool restrictions for safety
• Provide concrete examples
• Test thoroughly before sharing
• Document requirements clearly
• Use progressive disclosure (supporting files)

DON'T

• Create vague, generic descriptions
• Use invalid characters in names
• Make skills too broad
• Forget to include "when to use"
• Skip validation before testing
• Use absolute paths for supporting files
• Mix tabs and spaces in YAML
• Omit error handling guidance

Version History

When documenting skill changes, use semantic versioning:

## Version History
- v2.0.0 (2025-11-07): Breaking changes to API
- v1.1.0 (2025-10-15): Added new features
- v1.0.0 (2025-10-01): Initial release

This helps team members understand what changed between versions.