template-skill-enhanced

# Enhanced Skill Template

A production-ready skill template demonstrating progressive disclosure, bundled resource patterns, and quality validation. Use this template when creating skills that require tiered content loading, reference file organization, or structured quality scoring.

## When to Use This Skill

- Creating a new skill that needs **progressive disclosure** (tiered content loading)
- Building skills with **bundled resources** (references, examples, validation rubrics)
- Designing skills that exceed basic template complexity
- Setting up skills with **quality targets** and scoring rubrics
- Avoid using for simple, single-purpose skills — use `template-skill` instead

## Workflow

### Step 1: Set Up Frontmatter

Define metadata with kebab-case name, quoted description including a "Use when" clause, version, and tags:

```yaml
---
name: my-new-skill
description: "Clear description of what this skill does. Use when [specific trigger condition]."
version: 1.0.0
tags: [domain, category]
---
```

### Step 2: Write Core Principles (Tier 1 — Always Loaded)

The first section loads immediately on activation. Keep it under ~1000 tokens:

```markdown
## Core Principles

### Principle 1: Foundation Concept
Explanation with a concise code example:

\`\`\`python
# Demonstrate the concept clearly
def foundation_example(input_data):
    validated = validate(input_data)
    return transform(validated)
\`\`\`

**Key Points:**
- Critical aspect that must be understood
- Common misconception to avoid
```

### Step 3: Add Implementation Patterns (Tier 2 — Loaded When Needed)

Detailed patterns for common scenarios (~1500 tokens):

```markdown
### Pattern: Descriptive Name

**Problem**: What specific problem this solves
**Solution**: High-level approach

\`\`\`python
def pattern_implementation(input_data):
    validate(input_data)
    result = transform(input_data)
    return format_output(result)
\`\`\`

**Trade-offs**:
| Aspect | Benefit | Cost |
|--------|---------|------|
| Performance | Fast execution | Higher memory |
| Maintainability | Clear structure | More boilerplate |
```

### Step 4: Add Advanced Usage (Tier 3 — Complex Scenarios)

Reserve for sophisticated implementations (~2000+ tokens). Include edge cases:

| Scenario | Expected Behavior | Handling Strategy |
|----------|-------------------|-------------------|
| Empty input | Graceful failure | Return default or descriptive error |
| Invalid format | Validation error | Clear error message with fix guidance |
| Resource exhaustion | Graceful degradation | Backoff and retry logic |

### Step 5: Organize Bundled Resources

Create sibling directories for heavy content:

```
skills/my-new-skill/
├── SKILL.md                          # Core skill (under token budget)
├── references/
│   ├── README.md                     # Guide to reference docs
│   └── detailed-patterns.md          # Extended pattern documentation
├── examples/
│   └── basic.md                      # Annotated usage example
└── validation/
    └── rubric.yaml                   # Quality scoring rubric
```

### Step 6: Define Quality Targets

Set measurable quality criteria:

```yaml
quality_targets:
  clarity: ">= 4/5"
  completeness: ">= 4/5"
  accuracy: ">= 5/5"
  usefulness: ">= 4/5"
```

### Step 7: Validate the Skill

```bash
cortex skills validate my-new-skill
cortex skills info my-new-skill --show-tokens
```

Ensure total token count stays within 500–8,000 tokens per CONTRIBUTING guidelines.

## Best Practices

- **Progressive disclosure**: Keep Tier 1 concise — load detail on demand
- **Bundled resources**: Move lengthy examples and deep-dives to `references/` or `examples/`
- **Quality rubrics**: Define scoring criteria in `validation/rubric.yaml` so skill outputs can be evaluated consistently
- **Token budget**: Core SKILL.md should stay under token limits; offload heavy content to sibling files
- **Real examples**: Replace all placeholder content with domain-specific, working code
- **Kebab-case naming**: Directories and skill names use lowercase hyphen-case

## Anti-Patterns

- **Placeholder content in production**: Shipping `[Pattern Name]` or `example_code_here()` — always fill in real content
- **Monolithic skills**: Putting everything in SKILL.md instead of using bundled resources
- **Missing "Use when" clause**: Description must include activation context
- **Ignoring token budgets**: Skills over 8,000 tokens slow activation and may be truncated