skill-name
Brief description of what this skill does. Should be clear enough that Claude knows when to invoke it. Max 1024 characters.
When & Why to Use This Skill
This Claude skill framework provides a standardized template for developing high-performance, MCP-compatible skills. It focuses on optimizing token efficiency through local code execution, implementing deterministic workflows such as Plan-Validate-Execute, and ensuring robust error handling and caching for AI agents.
Use Cases
- Standardizing the creation of custom Claude skills to ensure consistent behavior, documentation, and reliability across agentic workflows.
- Implementing the Model Context Protocol (MCP) to enable secure and efficient local code execution for data-heavy tasks.
- Designing complex, multi-step agent operations using structured patterns like checklists, conditional logic, and deterministic security protocols.
- Optimizing AI agent performance and reducing costs by offloading intensive data processing and filtering to external scripts (Python/Bash) rather than processing raw data within the LLM context.
| name | skill-name |
|---|---|
| description | Brief description of what this skill does. Should be clear enough that Claude knows when to invoke it. Max 1024 characters. |
| allowed-tools | [Bash] |
Skill Name
One-paragraph description of what this skill does and when to use it.
MCP Code Execution Pattern
This skill follows the pattern described in Code Execution with MCP:
- Heavy processing in code - Fetch/process data in Python/bash, not via Claude tools
- Filter before returning - Return only relevant summaries, not raw data
- Cache intermediate results - Avoid redundant API calls or expensive operations
- Use typed interfaces - Type hints for reliability and clarity
- Deterministic security - Never expose sensitive data in output
Workflow Patterns
Choose the workflow pattern that best fits your skill:
Checklist Workflow
For skills with sequential steps, use a checklist:
When invoked:
1. [ ] Fetch data from source
2. [ ] Validate data completeness
3. [ ] Process and filter results
4. [ ] Format output
5. [ ] Display summary
Conditional Workflow
For skills with decision points, use conditional logic:
When invoked:
If cached data exists and is fresh:
- Load from cache
- Display cached results
Else:
- Fetch fresh data
- Process and cache
- Display new results
Plan-Validate-Execute Pattern
For skills that modify state or perform irreversible operations:
When invoked:
1. **Plan**: Show user what will happen
2. **Validate**: Check prerequisites and feasibility
3. **Execute**: Perform the operation
4. **Report**: Confirm results
See example_skill.py for implementation of the plan-validate-execute pattern.
Progressive Disclosure
Keep this SKILL.md under 500 lines. For detailed information:
- Put workflow details in separate reference files
- Claude loads reference files on-demand
- Keep the main skill file focused on the workflow
If this file grows too large, move detailed sections to a references/ folder.
Usage
How Claude should invoke this skill:
python3 ~/.claude/skills/skill-name/script.py [optional-args]
Or if using bash:
bash ~/.claude/skills/skill-name/script.sh [optional-args]
What It Returns
Describe the output format. For example:
- Returns formatted markdown ready to display
- Returns JSON for programmatic processing
- Returns exit code 0 on success, 1 on error
- Outputs to stdout (results) and stderr (errors/warnings)
Example output:
# Example Output
Summary: Processed 42 items in 1.2s
Details:
- Item 1: Status OK
- Item 2: Status WARNING (details...)
Next steps: [recommendations]
Processing Done by Skill
List the steps this skill performs in code (not in Claude):
- Fetch data from source (API, filesystem, command output)
- Filter/transform data using business logic
- Calculate derived metrics or summaries
- Cache results for subsequent invocations
- Format output for readability
- Return only essential information
Implementation Details
Caching Strategy
- Cache location:
~/.claude/.cache/skill-name.json - Cache invalidation: Describe when cache is cleared/updated
- Cache structure: Describe what data is cached and why
Error Handling
- Exits with code 1 on errors
- Prints user-friendly error messages to stderr
- Falls back to sensible defaults when possible
- Never crashes silently
Dependencies
List any external dependencies:
- Python 3.x required
- Standard library modules:
json,subprocess,datetime - External tools:
ghCLI,curl, etc. - API requirements: GitHub token, etc.
Design Rationale
Why a Skill vs Agent?
This operation is ideal for a skill because:
- Heavy data processing that would consume many tokens if done via Claude tools
- Deterministic logic that doesn't require Claude's reasoning
- Results can be pre-filtered and summarized
- Caching provides significant performance benefits
Token Efficiency
Estimated token savings compared to using Claude tools directly:
- Before: ~X tokens (raw data + processing)
- After: ~Y tokens (formatted summary)
- Reduction: ~Z% token savings
Future Enhancements
Ideas for extending this skill:
- Additional output formats
- More filtering/sorting options
- Integration with other tools
- Performance optimizations