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:

---
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:

## 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):

### 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:

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

Step 7: Validate the Skill

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