Create Skill Command

Goal: Create production-ready skills w/ validation, testing & optimization.

1. Required Skills

Use these skills during creation:

| Skill | Path | Purpose | |-------|------|---------| | skill-creator | .claude/skills/skill-creator/ | Core creation workflow | | token-formatter | .claude/skills/token-formatter/ | Compress SKILL.md content | | md | .claude/skills/document-skills/md/ | Clean markdown w/o errors |

2. Creation Flow

Step 1: Understand Requirements

Ask user:

1. "What should this skill do?"
2. "Example usage scenarios?"
3. "Any scripts/assets needed?"

Step 2: Init Skill

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

Creates:

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Step 3: Plan Resources

Analyze examples → identify:

| Resource | When | |----------|------| | scripts/ | Repeated code, deterministic tasks | | references/ | Docs, schemas, API specs | | assets/ | Templates, images, fonts |

Step 4: Write Content

SKILL.md rules:

• YAML frontmatter: name & description (req)
• Imperative form ("To do X" not "You should")
• Keep lean → move details to references/
• Apply token-formatter compression

Writing style:

# Skill Name

Brief purpose (1-2 sentences).

## When to Use

Invoke when:
- Condition 1
- Condition 2

## Process

1. Step one
2. Step two

Step 5: Optimize

Apply token-formatter:

• Abbreviations: fn, str, num, config, auth, db, etc.
• Remove filler words
• Compress tables & lists
• Use symbols: →, |, &, w/, w/o

Apply md skill:

• Proper fence nesting (use ```` for outer)
• Match opening/closing fences
• Escape | in tables
• Consistent list indentation
• Blank lines around code blocks

3. Testing (REQUIRED)

Test Location

tests/<skill-name>/
├── test_*.py          # Python tests
├── test_*.sh          # Bash tests
├── fixtures/          # Test data
└── expected/          # Expected outputs

Script Testing

For EVERY script in scripts/:

1. Syntax check:

# Python
python -m py_compile scripts/<script>.py

# Bash
bash -n scripts/<script>.sh

# Node
node --check scripts/<script>.js

2. Execution test:

# Run w/ test fixtures
python scripts/<script>.py tests/<skill>/fixtures/input.txt

3. Output validation:

# Compare output to expected
diff output.txt tests/<skill>/expected/output.txt

Validation Checklist

Before completion, verify:

• [ ] SKILL.md has valid YAML frontmatter
• [ ] name & description present in frontmatter
• [ ] All scripts execute w/o errors
• [ ] All scripts have proper shebang
• [ ] References files are valid markdown
• [ ] No hardcoded paths (use relative)
• [ ] Token-optimized (check w/ count_tokens.py)
• [ ] No markdown linting errors

Automated Validation

# Package & validate skill
python scripts/package_skill.py .claude/skills/<skill-name>

Checks:

• YAML frontmatter format
• Required fields present
• Directory structure
• File organization

4. Test Script Template

Create tests/<skill>/test_skill.py:

#!/usr/bin/env python3
"""Tests for <skill-name> skill."""

import subprocess
import os
from pathlib import Path

SKILL_DIR = Path(__file__).parent.parent.parent / ".claude/skills/<skill>"
FIXTURES = Path(__file__).parent / "fixtures"
EXPECTED = Path(__file__).parent / "expected"

def test_script_syntax():
    """Verify all scripts have valid syntax."""
    for script in (SKILL_DIR / "scripts").glob("*.py"):
        result = subprocess.run(
            ["python", "-m", "py_compile", str(script)],
            capture_output=True
        )
        assert result.returncode == 0, f"Syntax error: {script}"

def test_script_execution():
    """Verify scripts run w/o errors."""
    # Add script-specific tests
    pass

def test_skill_md_valid():
    """Verify SKILL.md has valid frontmatter."""
    skill_md = SKILL_DIR / "SKILL.md"
    content = skill_md.read_text()
    assert content.startswith("---"), "Missing YAML frontmatter"
    assert "name:" in content, "Missing name field"
    assert "description:" in content, "Missing description field"

if __name__ == "__main__":
    test_script_syntax()
    test_skill_md_valid()
    print("All tests passed!")

5. Execution Summary

1. Understand     → Ask user, clarify scope
2. Init           → Run init_skill.py
3. Plan           → Identify scripts/refs/assets
4. Write          → SKILL.md + resources
5. Optimize       → token-formatter + md skill
6. Test           → Create tests, run validation
7. Package        → package_skill.py
8. Iterate        → Fix issues, re-test

6. Quick Reference

Abbreviations (token-formatter)

fn=function  str=string  num=number  bool=boolean
arr=array    obj=object  param=parameter
config=configuration     env=environment
auth=authentication      db=database
req=required opt=optional def=default
w/=with      w/o=without  &=and  |=or

Frontmatter Template

---

name: skill-name
description: Brief desc. Use third-person ("This skill should be used when...")
license: Complete terms in LICENSE.txt
---

Directory Structure

.claude/skills/<skill>/
├── SKILL.md              # Core instructions (req)
├── scripts/              # Executable code (opt)
├── references/           # Docs to load as needed (opt)
└── assets/               # Output files (opt)

tests/<skill>/
├── test_*.py             # Test scripts
├── fixtures/             # Test inputs
└── expected/             # Expected outputs

---

Ref: .claude/skills/skill-creator/SKILL.md, .claude/skills/token-formatter/SKILL.md, .claude/skills/document-skills/md/SKILL.md