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:

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

Basic Usage Example

This document demonstrates a simple use case for the skill with annotated explanations.

Scenario

User Request: "Help me [describe the task the user wants to accomplish]"

Context:

• Project type: [e.g., Python web application, TypeScript library]
• Existing codebase: [e.g., small startup, large enterprise]
• Constraints: [e.g., must maintain backward compatibility]

Input

The user provides the following information or context:

[Example user input - this could be a description, code snippet, or specification]

Key Input Elements

Annotated breakdown of what the skill extracts from the input:

Processing Steps

How the skill processes this request:

Step 1: Analyze Input

<!-- ANNOTATION: The skill first identifies the core request and any constraints -->

Analysis:
- Primary objective: [identified objective]
- Secondary needs: [identified secondary needs]
- Potential challenges: [anticipated issues]

Step 2: Select Appropriate Pattern

<!-- ANNOTATION: Based on analysis, choose from the skill's pattern library -->

Pattern Selected: [Pattern Name from SKILL.md]

Rationale: This pattern was chosen because:

• [Reason 1 - relates to user's stated requirements]
• [Reason 2 - addresses identified constraints]
• [Reason 3 - aligns with quality requirements]

Alternatives Considered:

• [Alternative Pattern 1]: Not selected because [reason]
• [Alternative Pattern 2]: Not selected because [reason]

Step 3: Apply Pattern

<!-- ANNOTATION: Demonstrate the actual implementation -->

// Implementation applying the selected pattern
// Each section is annotated with explanations

/**
 * ANNOTATION: This comment explains WHY we're using this approach,
 * not just WHAT the code does.
 */
function implementedSolution(input) {
    // ANNOTATION: Validation first - following skill's best practices
    if (!isValid(input)) {
        throw new ValidationError('Input must meet criteria X');
    }

    // ANNOTATION: Core logic applies the pattern's main transformation
    const processed = applyTransformation(input);

    // ANNOTATION: Format output according to skill's standards
    return formatOutput(processed);
}

Step 4: Validate Output

<!-- ANNOTATION: Check the output against the skill's quality criteria -->

Validation Checklist:

• [x] Meets primary objective
• [x] Satisfies all constraints
• [x] Follows skill's best practices
• [x] No anti-patterns present
• [x] Code is testable

Output

The skill produces the following result:

// Final output ready for use
// This is what the user receives

[Complete, working solution]

Output Breakdown

Key Decisions Explained

Decision 1: [Choice Made]

What: Description of the decision

Why: Rationale aligned with skill principles

Trade-off: What was sacrificed and why it was acceptable

Decision 2: [Another Choice]

What: Description

Why: Rationale

Alternative: What could have been done differently and when that would be preferable

Quality Assessment

Using the rubric from validation/rubric.yaml:

Weighted Score: 4.5/5 (Exceptional)

Common Variations

Variation A: Different Constraint

If the user had specified [different constraint], the approach would change:

// Modified implementation for different constraint
modified_approach()

Variation B: Different Scale

For larger scale applications:

// Scaled implementation
scaled_approach()

Testing the Example

To verify this example works correctly:

// Test case demonstrating the example works
describe('Basic Usage Example', () => {
    it('produces expected output for standard input', () => {
        const input = prepareStandardInput();
        const result = implementedSolution(input);
        expect(result).toMatchExpectedOutput();
    });

    it('handles edge cases gracefully', () => {
        const edgeInput = prepareEdgeCaseInput();
        const result = implementedSolution(edgeInput);
        expect(result).toHandleEdgeCaseCorrectly();
    });
});

What to Watch For

When adapting this example for your use case:

1. Customize validation rules - Your domain may have different constraints 2. Adjust formatting - Output format may need to match your conventions 3. Add logging - Production code should include appropriate logging 4. Handle async - If your implementation involves async operations, adjust accordingly

Related Examples

• examples/advanced.md - More complex scenarios with multiple patterns
• examples/integration.md - Integration with external systems
• examples/troubleshooting.md - Common issues and fixes

---

This example follows the annotated example pattern from the cortex cookbook.

Reference Documentation Guide

This directory contains reference documentation that Claude loads as needed during skill execution. Unlike the main SKILL.md which loads immediately, reference files are loaded on-demand to optimize context usage.

Directory Structure

references/
├── README.md              # This file - navigation and usage guide
├── detailed-patterns.md   # Extended pattern documentation (when created)
├── api-reference.md       # API specifications (when applicable)
├── troubleshooting.md     # Common issues and solutions (when created)
└── glossary.md            # Domain-specific terminology (when created)

When to Use References

Reference files should be loaded when:

1. Deep Dive Required: User needs detailed information beyond core principles 2. Troubleshooting: User encounters issues requiring diagnostic guidance 3. Integration: User is integrating with external systems or services 4. Advanced Scenarios: User's use case exceeds basic pattern coverage

Reference File Guidelines

File Organization

Each reference file should follow this structure:

# Reference: [Topic Name]

## Overview
Brief description of what this reference covers and when to use it.

## Quick Reference
Most commonly needed information in table or list format.

## Detailed Content
Comprehensive coverage of the topic.

## Related References
Links to other relevant reference files.

Content Principles

1. Searchable: Use clear headings and keywords for grep-based discovery 2. Modular: Each file covers one topic comprehensively 3. Progressive: Order content from common to rare use cases 4. Practical: Include working examples and code snippets 5. Current: Keep information up-to-date with latest versions

Size Guidelines

For files exceeding 10000 words, split into multiple files with clear navigation.

Search Patterns

When looking for information in reference files, use these grep patterns:

# Find pattern documentation
grep -r "Pattern:" references/

# Find code examples
grep -r "```" references/

# Find troubleshooting entries
grep -r "Issue:" references/
grep -r "Problem:" references/

# Find API information
grep -r "Endpoint:" references/
grep -r "Method:" references/

Creating New References

When adding a new reference file:

1. Identify the need: What information gap does this address? 2. Check for overlap: Could this be added to an existing file? 3. Name clearly: Use descriptive, lowercase-with-hyphens names 4. Add to index: Update this README with the new file 5. Link appropriately: Add cross-references from SKILL.md if needed

Reference Template

# Reference: [Topic Name]

## Overview

[1-2 sentences describing what this reference covers]

## Quick Reference

| Item | Description | Example |
|------|-------------|---------|
| [Key item] | [Brief description] | [Example value] |

## [Main Section 1]

### [Subsection]

[Detailed content with examples]

// Code example example_code()

## [Main Section 2]

[Additional content]

## Related References

- `reference-name.md` - [How it relates]
- `another-reference.md` - [How it relates]

## Changelog

- YYYY-MM-DD: Initial creation
- YYYY-MM-DD: [Update description]

Loading Strategy

Claude uses these strategies to determine when to load references:

Automatic Loading Triggers

• User mentions topic covered by a reference file
• Current pattern requires additional context
• Troubleshooting mode is activated
• Integration with external system is detected

Manual Loading Requests

Users can request reference loading explicitly:

• "Show me the detailed patterns"
• "I need the API reference"
• "What does [term] mean?"

Conditional Loading

References load based on context:

• Error messages trigger troubleshooting.md
• API questions trigger api-reference.md
• Unfamiliar terms trigger glossary.md

Best Practices for Reference Usage

For Skill Authors

1. Keep SKILL.md lean: Move detailed content to references 2. Use progressive disclosure: Core concepts in SKILL.md, details in references 3. Avoid duplication: Information lives in ONE place 4. Maintain consistency: Use consistent formatting across references 5. Update together: When updating SKILL.md, check if references need updates

For Users

1. Start with SKILL.md: Core concepts first 2. Request specifics: Ask for detailed patterns when needed 3. Search first: Use keywords to find relevant references 4. Report gaps: If information is missing, suggest additions

Maintenance

Regular Review

• [ ] Check for outdated information (quarterly)
• [ ] Verify code examples still work (monthly)
• [ ] Update external links (quarterly)
• [ ] Review and incorporate user feedback (ongoing)

Version Alignment

References should be versioned with the main skill:

• Major version: Structural changes to references
• Minor version: Content additions or updates
• Patch version: Typo fixes and minor corrections

Index of Available References

<!-- Update this section as references are added -->

---

Reference documentation follows the progressive disclosure pattern from the cortex cookbook.