| 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 |
- [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]
- [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
- Execute [specific action]
- Monitor [specific indicator]
- 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:
- Checking [specific output or indicator]
- Confirming [expected state or condition]
- 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.
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)
Why It Happens: [Root cause]
How to Avoid:
- [Prevention step 1]
- [Prevention step 2]
Recovery: [How to fix if it happens]
How to Avoid: [Prevention strategy]
Warning Signs: [Early indicators to watch for]
Situation: [Specific setup or starting conditions]
Steps:
- [First action taken]
- [Second action taken]
- [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:
- [First action with additional considerations]
- [Second action handling edge cases]
- [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]
Approach:
- [Step 1 of pattern]
- [Step 2 of pattern]
- [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:
- [First resolution step]
- [Second resolution step]
- [Verification step]
Prevention: [How to avoid this in future]
Diagnostic Steps:
- [How to investigate]
- [What to check]
Solution: [Clear resolution steps]
Alternative Approaches: [If primary solution doesn't work]
Quick Fix: [Immediate solution]
Root Cause Resolution: [Permanent fix]
- [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]
Load When Needed:
- [Supporting resources to load on-demand]
- [Detailed references for specific scenarios]
Version 1.1.0 (YYYY-MM-DD)
- [Enhancement or fix]
- [Additional feature]
Imperative Form: Write as commands ("Do this", "Check that") not descriptions.
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)
Concrete Examples: One good example > 10 paragraphs of explanation.
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
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!