your-skill-name

---

name: your-skill-name description: Brief description of what this skill does (1-2 sentences). Include key triggering words that help agents recognize when to use this skill. version: 1.0.0 author: Your Name/Team category: custom token_estimate: ~500

<when_to_use> Use this skill when:

• [Specific use case 1 with concrete scenario]
• [Specific use case 2 with concrete scenario]
• [Specific use case 3 with concrete scenario]
• [Additional use cases as needed]

Do NOT use this skill when:

• [Anti-pattern or inappropriate scenario 1]
• [Anti-pattern or inappropriate scenario 2] </when_to_use>

• [Required tool, library, or environment setup]
• [Access to specific resources or credentials]
• [Knowledge prerequisites or dependencies]
• [Other skills that should be loaded alongside this one]

If there are no prerequisites, remove this section.

• Check that [prerequisite] is available
• Verify [condition] is met
• Gather [required information]

Example:

# Command to verify setup
tool --version

# Command to check prerequisites
tool check --all

1. Execute [specific action]
2. Monitor [specific indicator]
3. Validate [expected condition]

Important Considerations:

• [Key decision point or branching logic]
• [Edge case to handle]
• [Safety check or validation]

Example:

# Example code showing this step
def main_process():
    """Core implementation of the skill's main action."""
    # Step-by-step implementation
    result = perform_action()
    validate(result)
    return result

Verify the process completed successfully by:

1. Checking [specific output or indicator]
2. Confirming [expected state or condition]
3. Running [validation command or test]

Expected Outcomes:

• [Specific success criterion 1]
• [Specific success criterion 2]

Example:

# Validation commands
tool verify --output
tool status --check-all

• Clean up [temporary resources]
• Document [results or decisions]
• Notify [stakeholders or systems]
• Update [tracking or monitoring systems]

Optional: Remove this step if not applicable.

<best_practices> [Explanation of why this is important and how to apply it.]

Example:

// Code demonstrating this best practice

Rationale: [Why this matters] Implementation: [How to do it]

• High Freedom: Multiple valid approaches; adapt based on context and project needs
• Medium Freedom: Preferred patterns exist; some variation acceptable for good reasons
• Low Freedom: Follow specific procedures exactly; consistency is critical for safety/compliance

Optimization Strategy:

• Core instructions: Always loaded (~X,XXX tokens)
• Examples: Load for reference (~XXX tokens)
• Supporting resources: Load on-demand only (variable)

</best_practices>

<common_pitfalls> What Happens: [Description of the problem]

Why It Happens: [Root cause]

How to Avoid:

1. [Prevention step 1]
2. [Prevention step 2]

Recovery: [How to fix if it happens]

How to Avoid: [Prevention strategy]

Warning Signs: [Early indicators to watch for] </common_pitfalls>

Situation: [Specific setup or starting conditions]

Steps:

1. [First action taken]
2. [Second action taken]
3. [Third action taken]

Implementation:

# Complete, runnable example
def example_basic():
    """Demonstrate basic usage of this skill."""
    # Step 1: Setup
    config = load_config()

    # Step 2: Execute
    result = execute_action(config)

    # Step 3: Validate
    assert verify(result), "Validation failed"

    return result

Expected Output:

[Sample output showing what success looks like]

Outcome: [What was accomplished and why it matters]

Situation: [Specific setup with additional complexity]

Challenges:

• [Challenge or constraint 1]
• [Challenge or constraint 2]

Steps:

1. [First action with additional considerations]
2. [Second action handling edge cases]
3. [Third action with error handling]

Implementation:

# More sophisticated example
class AdvancedExample:
    """Demonstrate advanced usage with error handling."""

    def __init__(self, config):
        self.config = config
        self.state = {}

    def execute(self):
        """Main execution with comprehensive error handling."""
        try:
            # Step 1: Preparation
            self._prepare()

            # Step 2: Core process
            result = self._process()

            # Step 3: Validation
            self._validate(result)

            return result

        except SpecificError as e:
            # Handle known error
            self._handle_error(e)

        except Exception as e:
            # Handle unexpected error
            self._handle_unexpected_error(e)

    def _prepare(self):
        """Preparation logic."""
        pass

    def _process(self):
        """Core processing logic."""
        pass

    def _validate(self, result):
        """Validation logic."""
        pass

Expected Output:

[Sample output for advanced scenario]

Outcome: [What was accomplished, including handling of complexity]

Special Considerations:

• [Unique aspect 1]
• [Unique aspect 2]

Implementation:

# Example handling edge case
def handle_edge_case():
    """Demonstrate how to handle special scenarios."""
    # Implementation details
    pass

Outcome: [Result and lessons learned]

<common_patterns> When to Use: [Triggering conditions for this pattern]

Approach:

1. [Step 1 of pattern]
2. [Step 2 of pattern]
3. [Step 3 of pattern]

Example:

// Code demonstrating this pattern
def pattern_one():
    """Implementation of common pattern 1."""
    pass

Key Characteristics:

• [Characteristic 1]
• [Characteristic 2]

Example:

// Code demonstrating this pattern

Cause: [Why this happens]

Solution:

1. [First resolution step]
2. [Second resolution step]
3. [Verification step]

Prevention: [How to avoid this in future]

Diagnostic Steps:

1. [How to investigate]
2. [What to check]

Solution: [Clear resolution steps]

Alternative Approaches: [If primary solution doesn't work]

Quick Fix: [Immediate solution]

Root Cause Resolution: [Permanent fix]

<related_skills> This skill works well with:

• [Skill Name 1]: [How these skills complement each other]
• [Skill Name 2]: [When to use both together]
• [Skill Name 3]: [Integration points]

This skill may conflict with:

• [Conflicting Skill]: [Why they shouldn't be used together and when to choose each] </related_skills>

<integration_notes> [How this skill integrates with common tools or workflows]

Load When Needed:

• [Supporting resources to load on-demand]
• [Detailed references for specific scenarios]

</integration_notes>

<version_history> Version 1.0.0 (YYYY-MM-DD)

• Initial creation
• Core functionality established
• Basic examples provided

Version 1.1.0 (YYYY-MM-DD)

• [Enhancement or fix]
• [Additional feature] </version_history>

<additional_resources> External documentation and references:

• Relevant external documentation
• Related tool documentation
• Team wiki or internal resources </additional_resources>

<template_usage_notes> REMOVE THIS SECTION when creating your actual skill. This guidance is only for template users.

2. Imperative Form: Write as commands ("Do this", "Check that") not descriptions.

3. Progressive Disclosure:

   • Frontmatter metadata: ~50-100 tokens (always in context)
   • SKILL.md body: 2,000-5,000 tokens (loaded when skill triggered)
   • Supporting resources: Variable (loaded on-demand)

4. Concrete Examples: One good example > 10 paragraphs of explanation.

5. Appropriate Specificity:

   • High freedom: Provide principles, options, and trade-offs
   • Medium freedom: Show preferred patterns with acceptable alternatives
   • Low freedom: Give exact procedures with safety checks

6. Test with Real Tasks: Validate effectiveness with actual agent workflows.

Optional Sections (remove if not applicable):

• prerequisites
• common_pitfalls
• common_patterns
• troubleshooting
• related_skills
• integration_notes
• notes (limitations, assumptions)

Customize Based on Skill Type:

For Workflow/Process Skills:

• Emphasize step-by-step instructions
• Include decision trees for branching logic
• Provide checklist format options
• Document approval/review steps

For Technical/Implementation Skills:

• Focus on code examples
• Include architecture patterns
• Document API usage
• Provide testing strategies

For Domain/Knowledge Skills:

• Emphasize concepts and principles
• Include reference materials
• Document domain-specific patterns
• Provide terminology glossary

Good luck! </template_usage_notes>