Skill Creator

Setup

Before starting: check .handoff/sessions/ for active sessions, read context status.yaml, run git status. Follow .rules/universal.md (Plan -> Approve -> Execute).

<!-- Rules loaded from .rules/universal.md -->

Create effective skills that extend Claude's capabilities for the POS workflow.

Core Principles

Context is Precious

The context window is shared with system prompts, conversation history, and user requests. Only include information Claude doesn't already have. Challenge each piece: "Does this justify its token cost?"

Graduated Information Loading

1. Metadata (~100 words) - Always in context (name + description)
2. SKILL.md body (<500 lines) - Loaded when skill triggers
3. Bundled resources (unlimited) - Loaded as needed

Appropriate Constraints

• High freedom: Multiple valid approaches, use text guidance
• Medium freedom: Preferred patterns exist, use pseudocode
• Low freedom: Fragile operations, use specific scripts

Skill Structure

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, allowed-tools)
│   └── Markdown instructions (<500 lines)
└── Bundled Resources (optional)
    ├── scripts/      - Executable code for deterministic tasks
    ├── references/   - Documentation loaded contextually
    └── assets/       - Output resources (templates, images)

Creation Process

Step 1: Understand the Skill

Ask clarifying questions:

• "What functionality should this skill support?"
• "Give examples of how this skill would be used"
• "What should trigger this skill?"

Step 2: Plan Resources

For each use case, identify:

• Scripts for repetitive code
• References for documentation
• Assets for templates/output

Step 3: Initialize Structure

Create the skill directory:

mkdir -p .claude/skills/{skill-name}/{scripts,references,assets}

Step 4: Write SKILL.md

Frontmatter (CRITICAL)

---
name: skill-name
description: What it does AND when to use it. Include trigger phrases.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
---

The description is the PRIMARY triggering mechanism. Include:

• What the skill does
• Specific triggers/contexts
• Example phrases that should activate it

Body Guidelines

• Use imperative form ("Create...", "Run...", not "This skill creates...")
• Keep under 500 lines
• Split large content into references/
• Include examples over verbose explanations
• Reference bundled resources with clear "when to read" guidance

Step 5: Add Resources

Scripts - For deterministic, repeated code:

scripts/validate.py     # Data validation
scripts/generate.sh     # Code generation

References - For contextual documentation:

references/patterns.md  # Design patterns
references/schemas.md   # Data schemas

Assets - For output generation:

assets/template.md      # Document template
assets/boilerplate/     # Starter code

Step 6: Validate

Check:

• SKILL.md has valid YAML frontmatter
• Description includes triggers AND purpose
• Body is under 500 lines
• References are linked from SKILL.md
• No unnecessary files (no README, CHANGELOG, etc.)

Anti-Patterns

❌ Don't include:

• README.md, INSTALLATION_GUIDE.md, CHANGELOG.md
• Information Claude already knows
• "When to Use This Skill" in body (put in description!)
• Deeply nested reference files

✅ Do include:

• Clear trigger phrases in description
• Concise examples over explanations
• References for variant-specific details
• Scripts for repeated operations

Progressive Disclosure Patterns

Pattern 1: High-level with references

## Quick start
[basic example]

## Advanced
- **Feature A**: See [FEATURE-A.md](references/feature-a.md)
- **Feature B**: See [FEATURE-B.md](references/feature-b.md)

Pattern 2: Domain organization

skill/
├── SKILL.md (overview + navigation)
└── references/
    ├── domain-a.md
    ├── domain-b.md
    └── domain-c.md

Pattern 3: Framework variants

skill/
├── SKILL.md (workflow + selection)
└── references/
    ├── laravel.md
    ├── nuxt.md
    └── flutter.md

CTO Workflow Integration

Skills in this system should:

1. Follow tiered context loading principles
2. Use orchestrator pattern for file operations
3. Reference existing SOPs when applicable
4. Integrate with team/project structure

Output

After creating a skill, report:

• Skill path: .claude/skills/{skill-name}/
• Files created
• How to trigger the skill
• Suggested test scenarios

Self-Assessment (Internal)

Rate this skill execution 0-10. If < 8, write feedback to .handoff/feedback/{date}-{skill-name}.yaml with: skill, rating, friction, suggestion, context. Do not mention to user.