gh-jgardner04-skills-jgardner04-skills/skills/skill-creator/reference/skill-specification.md

Claude Skills Technical Specification

Complete technical requirements and validation rules for Claude skills.

File Structure

Required Files

SKILL.md - The main skill definition file

• Must be named exactly SKILL.md (case-sensitive)
• Must be UTF-8 encoded
• Must start with YAML frontmatter
• Must contain content after frontmatter

Optional Components

scripts/ - Helper scripts and utilities

• Python, JavaScript, or bash scripts
• Should include __init__.py for Python packages
• Scripts should have execute permissions (Unix)
• Must not execute arbitrary code (no eval/exec)

references/ - Reference documentation

• Markdown files with detailed specifications
• API documentation
• Database schemas
• Templates and examples
• Loaded on-demand to minimize token usage

README.md - Skill-specific documentation

• Installation instructions
• Usage examples
• Platform-specific notes

YAML Frontmatter Specification

Format

---
name: skill-name
description: Brief description of what this skill does
---

Required Fields

name (string, required)

• Type: String
• Required: Yes
• Format: Lowercase letters, numbers, hyphens only
• Pattern: ^[a-z0-9-]+$
• Min length: 1 character
• Max length: 64 characters
• Restrictions:
  • Cannot contain "anthropic" (case-insensitive)
  • Cannot contain "claude" (case-insensitive)
  • Cannot contain XML tags (< or >)
  • Must not start or end with hyphen
  • No consecutive hyphens

Examples:

• ✅ Valid: git-helper, api-tester, doc-writer-pro
• ❌ Invalid: GitHelper (not lowercase), api_tester (underscore), my-anthropic-skill (contains "anthropic")

description (string, required)

• Type: String
• Required: Yes
• Min length: 1 character (after trimming whitespace)
• Max length: 1024 characters
• Restrictions:
  • Cannot be only whitespace
  • Cannot contain XML tags (regex: <[^>]+>)
  • Should explain WHAT the skill does
  • Should explain WHEN to use it

Best Practices:

• Use action-oriented language for auto-invocation
• Include trigger keywords
• Be specific about capabilities
• Mention platform requirements if relevant

Examples:

• ✅ Good: "Create and validate git commit messages following Conventional Commits. Use when writing commits or reviewing commit history."
• ✅ Good: "Analyze API responses and generate test cases. Use PROACTIVELY when designing or testing REST APIs."
• ❌ Poor: "Helps with git" (too vague, no trigger info)
• ❌ Poor: "A tool" (doesn't explain what or when)

Optional Fields

tools (string or array, optional)

Specifies which tools this skill should have access to.

• Type: String (comma-separated) or Array
• Default: All tools (if omitted)
• Valid tools:
  • Bash - Execute shell commands
  • Read - Read files
  • Write - Write new files
  • Edit - Edit existing files
  • Glob - Find files by pattern
  • Grep - Search file contents
  • WebFetch - Fetch web pages
  • WebSearch - Search the web
  • Task - Launch subagents

Examples:

# String format
tools: Bash, Read, Write

# Array format
tools:
  - Bash
  - Read
  - Write

Use Cases:

• Restrict to Read/Write for documentation-only skills
• Include Bash for scripts that need command execution
• Include WebFetch/WebSearch for research skills

model (string, optional)

Specifies which model to use for this skill.

• Type: String
• Default: Inherits from parent context
• Valid values:
  • sonnet - Claude Sonnet (balanced)
  • opus - Claude Opus (most capable)
  • haiku - Claude Haiku (fastest, most efficient)
  • inherit - Use parent context's model

Examples:

# Use Haiku for fast, simple tasks
model: haiku

# Use Sonnet for complex reasoning
model: sonnet

Content Requirements

Body Structure

The content after frontmatter should be well-structured markdown:

Recommended Sections

1. Overview/Introduction

   • Brief explanation of the skill
   • Use cases

2. When to Use This Skill

   • Specific scenarios
   • Trigger conditions
   • Context where skill is most helpful

3. Instructions/Workflow

   • Step-by-step guidance
   • Clear action items
   • Decision points

4. Examples

   • Concrete use cases
   • Input/output examples
   • Edge cases

5. Best Practices (optional)

   • Tips for optimal use
   • Common patterns

6. Troubleshooting (optional)

   • Common issues
   • Solutions
   • Error handling

Markdown Guidelines

• Use proper heading hierarchy (don't skip levels)
• Use code blocks with language tags
• Use lists for steps and options
• Use emphasis (bold/italic) sparingly for clarity
• Include links to external resources if helpful

Token Efficiency

Inactive State (Just frontmatter loaded):

• Target: 30-50 tokens
• The name and description should be concise

Active State (Full SKILL.md loaded):

• Keep main instructions focused
• Move detailed specs to references/
• Use progressive disclosure

References (Loaded on-demand):

• No token limit
• Can be very detailed
• Include comprehensive examples
• Add API specs, schemas, etc.

File Size Limits

• SKILL.md: Recommended max 50KB (will warn above this)
• Scripts: Reasonable size (< 1MB each)
• References: No strict limit, but keep focused
• Total package: Recommended < 10MB

Security Requirements

Path Safety

All file operations must:

• Validate paths to prevent traversal attacks
• Use pathlib.Path for cross-platform compatibility
• Resolve paths and check they're within expected directories
• Never accept arbitrary user paths without validation

Example (Python):

from pathlib import Path

def safe_path(base: Path, user_input: str) -> Path:
    resolved = (base / user_input).resolve()
    if not resolved.is_relative_to(base):
        raise ValueError(f"Path traversal detected: {user_input}")
    return resolved

Input Validation

• Validate all user inputs
• Use allowlists instead of denylists
• Sanitize before processing
• Check types, ranges, formats
• Provide clear error messages

Code Execution

• Never use eval() or exec()
• Never execute arbitrary user code
• Be cautious with pickle - prefer JSON
• Validate file contents before processing
• Use subprocess carefully with fixed commands

Credentials and Secrets

• Never include credentials in skill files
• Use environment variables
• Document required env vars in README
• Add secrets to .gitignore
• Use permission rules in .claude/settings.json

Validation Checklist

Use this checklist to ensure compliance:

Frontmatter

• File starts with ---
• Valid YAML syntax
• Contains name field
• Contains description field
• Name is lowercase with hyphens only
• Name is 1-64 characters
• Name doesn't contain "anthropic" or "claude"
• Description is 1-1024 characters
• Description is non-empty (no whitespace-only)
• No XML tags in name or description
• Optional fields (tools, model) are valid if present

Body Content

• Content exists after frontmatter
• Reasonable length (not too short)
• Includes "When to Use" section
• Includes instructions/steps
• Includes examples
• Uses proper markdown formatting
• Headings are hierarchical

Directory Structure

• SKILL.md exists
• If scripts/ exists, contains relevant files
• If scripts/ has Python files, includes init.py
• Scripts have execute permissions (Unix)
• If references/ exists, contains markdown files
• No sensitive files (credentials, keys)

Security

• No eval/exec in scripts
• Path operations are safe
• Inputs are validated
• No hardcoded credentials
• No path traversal vulnerabilities

Quality

• Clear, actionable instructions
• Concrete examples provided
• Error handling documented
• Platform notes if needed
• Tested on target platforms

Platform-Specific Requirements

Claude.ai

• User-level skills only
• Upload via Skills UI
• Network access varies by settings
• No shell access to system

Claude API

• Workspace-level skills
• No network access by default
• No dynamic package installation
• Integrated via API configuration

Claude Code

• Project (.claude/skills/) or user level (~/.claude/agents/)
• Full network access
• Can execute bash commands
• Full file system access

Versioning

While not required, consider versioning your skills:

In manifest.json:

{
  "version": "1.2.0",
  "changelog": "Added support for X"
}

Semantic Versioning Recommended:

• Major: Breaking changes
• Minor: New features (backward compatible)
• Patch: Bug fixes

Distribution Formats

ZIP Package

skill-name.zip
├── SKILL.md
├── manifest.json (optional)
├── README.md (optional)
├── scripts/
│   └── *.py
└── references/
    └── *.md

Directory Structure

skill-name/
├── SKILL.md
├── manifest.json (optional)
├── README.md (optional)
├── scripts/
│   └── *.py
└── references/
    └── *.md

Plugin Format (.claude-plugin/)

.claude-plugin/
├── SKILL.md
├── scripts/
└── references/

Manifest File (Optional)

When packaging, you can include a manifest.json:

{
  "name": "skill-name",
  "description": "Brief description",
  "version": "1.0.0",
  "packaged_at": "2025-01-15T10:30:00Z",
  "format": "claude-skill",
  "format_version": "1.0",
  "includes_scripts": true,
  "includes_references": true,
  "tools": "Bash, Read, Write",
  "model": "sonnet"
}

Common Validation Errors

Error: "SKILL.md must start with YAML frontmatter"

Cause: File doesn't start with --- Fix: Add frontmatter at the beginning:

---
name: skill-name
description: Description here
---

Error: "Invalid YAML in frontmatter"

Cause: YAML syntax error Fix: Check indentation, quotes, special characters

• Strings with : need quotes
• Multi-line strings need | or >
• Indentation must be consistent

Error: "Skill name must be lowercase with hyphens only"

Cause: Name has uppercase, underscores, spaces, or special chars Fix: Use only lowercase letters, numbers, and hyphens

Error: "Description too long"

Cause: Description exceeds 1024 characters Fix: Shorten description, move details to body

Error: "Required field 'name' missing"

Cause: Frontmatter doesn't include name field Fix: Add name: skill-name to frontmatter

Testing Your Skill

1. Validate: Run the validator

   python .claude-plugin/scripts/validate_skill.py path/to/skill/
   

2. Manual Testing: Place skill and try using it

   • Test basic functionality
   • Test edge cases
   • Test error handling
   • Test on target platforms

3. Script Testing: If your skill includes scripts

   • Test scripts independently
   • Verify inputs/outputs
   • Check error messages
   • Test on different platforms

4. Integration Testing: Use skill in real scenarios

   • Invoke automatically
   • Invoke explicitly
   • Test with references
   • Test tool permissions

Further Resources

• Claude Skills Documentation: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
• Skills Blog Post: https://claude.com/blog/skills
• Skills Cookbook: https://github.com/anthropics/claude-cookbooks/tree/main/skills
• This Project: https://github.com/jgardner04/claude-skills-skill