movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

skills skill v1

Browse Source
This commit is contained in:
movq
2025-10-17 10:32:29 -05:00
commit cb6b9f532a
6 changed files with 2500 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
.claude/settings.local.json

151
claude-skills/README.md Normal file
View File

@@ -0,0 +1,151 @@
# Skill Creator - Meta Skill for Building Agent Skills
A comprehensive guide for creating effective Claude Agent Skills, complete with best practices, templates, and real-world examples.
## What's Included
- **SKILL.md**: Complete best practices guide with progressive disclosure principles, structure guidelines, and development workflows
- **examples.md**: Working examples of well-structured skills across different domains (testing, API integration, documentation)
- **templates.md**: Ready-to-use templates for common skill types (code frameworks, workflows, reference guides, tools)
## Quick Start
### For Claude Code Users
1. Place this skill directory in your skills folder
2. The skill will automatically be available when you need to create or improve skills
3. Invoke by mentioning skill creation, or Claude will trigger it when relevant
### For Claude.ai Users
1. Zip this directory
2. Upload via Settings > Capabilities > Upload skill
3. Enable the skill toggle
## When This Skill Triggers
This skill activates when you:
- Create a new Agent Skill from scratch
- Improve or refactor an existing skill
- Debug why a skill isn't triggering correctly
- Need to understand skill architecture
- Optimize skill structure for token efficiency
## Key Principles Covered
1. **Progressive Disclosure**: Three-layer architecture (metadata → instructions → resources)
2. **Trigger Optimization**: Writing descriptions that activate at the right time
3. **Token Efficiency**: Strategic file splitting and on-demand loading
4. **Development Workflow**: Iterative approach to skill creation
5. **Security Considerations**: Best practices for safe skill creation and usage
## Example Skills Included
### 1. Python Testing with pytest
Complete guide for writing comprehensive Python tests with fixtures, parametrization, and mocking.
### 2. REST API Integration
Patterns for building robust API clients with authentication, error handling, rate limiting, and pagination.
### 3. Technical Documentation Writer
Templates and guidelines for creating clear API docs, README files, and code comments.
## Templates Available
- **Code Framework Skill**: For teaching libraries/frameworks
- **Workflow/Process Skill**: For guiding through procedures
- **Reference/Lookup Skill**: For quick information access
- **Tool/Utility Skill**: For operating specific tools
## Using This Skill
### Creating a New Skill
Ask Claude: "Help me create a skill for [topic]"
Claude will:
1. Guide you through choosing the right template
2. Help write an effective description
3. Structure content using progressive disclosure
4. Provide examples relevant to your domain
### Improving an Existing Skill
Ask Claude: "Review my skill and suggest improvements"
Claude will analyze:
- Trigger accuracy (does description match use cases?)
- Structure optimization (can it be split for better token usage?)
- Content clarity (are examples concrete enough?)
- Best practices alignment
### Debugging Skill Triggering
Ask Claude: "Why isn't my skill triggering when [scenario]?"
Claude will check:
- Description specificity and keywords
- Name clarity
- Potential conflicts with other skills
- Whether use cases are documented
## Structure of a Good Skill
```
my-skill/
├── SKILL.md # Required: Main entry point with metadata
├── examples.md # Optional: Detailed examples
├── reference.md # Optional: Deep reference material
├── templates/ # Optional: Reusable templates
└── scripts/ # Optional: Executable utilities
```
### Minimal Skill
At minimum, you need `SKILL.md` with:
```yaml
---
name: Your Skill Name
description: Specific description of what this does and when to use it
---
[Skill content]
```
## Best Practices Checklist
- [ ] Description is under 1024 characters and specific
- [ ] Name is under 64 characters and clear
- [ ] "When to Use This Skill" section is present
- [ ] At least one concrete example is included
- [ ] No sensitive information is hardcoded
- [ ] Tested triggering with target scenarios
- [ ] File splitting used for mutually exclusive content
- [ ] Security considerations addressed
## Common Pitfalls Covered
1. **Vague descriptions** that don't trigger reliably
2. **Overly broad content** that wastes tokens
3. **Missing examples** that leave users guessing
4. **Security oversights** like hardcoded credentials
5. **Poor file organization** that loads unnecessary content
## Resources
- [Official Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Engineering Blog: Equipping Agents for the Real World](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
## Contributing
This is a meta-skill that helps create other skills. If you discover new patterns or best practices:
1. Test them in real skill creation scenarios
2. Document what works and what doesn't
3. Add to the appropriate section (SKILL.md for principles, examples.md for cases, templates.md for reusable patterns)
## License
This skill is provided as a reference implementation for creating Agent Skills. Use it freely to build your own skills.

456
claude-skills/SKILL.md Normal file
View File

@@ -0,0 +1,456 @@
---
name: Skill Creator
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use when building new skills or improving existing ones.
---
# Skill Creation Best Practices
## When to Use This Skill
Use this skill when:
- Creating a new Agent Skill from scratch
- Improving or refactoring an existing skill
- Debugging why a skill isn't triggering correctly
- Understanding skill architecture and design patterns
- Optimizing skill structure for token efficiency
## Core Principle: Progressive Disclosure
**Progressive disclosure is the fundamental design pattern for Agent Skills.** It works in three layers:
### Layer 1: Metadata (Always Loaded)
- **What**: YAML frontmatter with `name` and `description`
- **When**: Pre-loaded at every session start
- **Cost**: ~100 tokens per skill
- **Purpose**: Trigger detection - helps Claude decide if skill is relevant
### Layer 2: Instructions (Triggered)
- **What**: Main SKILL.md content
- **When**: Loads when Claude determines skill applies
- **Cost**: Variable (keep focused and concise)
- **Purpose**: Procedural guidance, workflows, best practices
### Layer 3: Resources (On-Demand)
- **What**: Additional files, scripts, reference materials
- **When**: Only when explicitly needed
- **Cost**: Only when accessed
- **Purpose**: Deep reference, executable code, examples
## Skill Structure Requirements
### Mandatory: SKILL.md File
Every skill MUST have a `SKILL.md` file with YAML frontmatter:
```yaml
---
name: Your Skill Name
description: Clear description of what this does and when to use it
---
```
**Critical Constraints:**
- Name: Maximum 64 characters
- Description: Maximum 1024 characters
- **The description is crucial** - it determines when Claude triggers the skill
### Optional: Additional Resources
Structure additional files strategically:
```
my-skill/
├── SKILL.md # Main entry point (required)
├── reference.md # Deep reference material (load on-demand)
├── examples.md # Code samples and templates
├── workflows/ # Step-by-step procedures
│ ├── advanced.md
│ └── beginner.md
└── scripts/ # Executable utilities
└── helper.sh
```
## Writing Effective Descriptions
The `description` field is your skill's trigger mechanism. Make it count:
### Good Descriptions
✓ **Specific use cases**: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables"
✓ **Clear triggers**: "Use when building React components following atomic design principles"
✓ **Domain clarity**: "Debug Swift applications using LLDB for crashes, memory issues, and runtime errors"
### Poor Descriptions
✗ **Too vague**: "Helps with coding"
✗ **No trigger context**: "Python utilities"
✗ **Feature list without purpose**: "Has functions for A, B, and C"
### Template for Descriptions
```
[Action verb] [specific domain/task] [with/for/using] [key capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios].
```
**Example:** "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports."
## Best Practices for SKILL.md Content
### 1. Start with "When to Use This Skill"
Immediately clarify trigger scenarios:
```markdown
## When to Use This Skill
Use this skill when:
- [Primary scenario]
- [Secondary scenario]
- [Edge case to include]
Do NOT use this skill for:
- [Common confusion case]
- [Related but different scenario]
```
### 2. Structure for Scannability
Use clear hierarchies and action-oriented headers:
```markdown
## Quick Start
[Minimal example to get started]
## Core Workflows
### Workflow 1: [Name]
1. Step one
2. Step two
### Workflow 2: [Name]
1. Step one
2. Step two
## Advanced Techniques
[Less common but powerful approaches]
## Common Pitfalls
[Known issues and how to avoid them]
```
### 3. Include Concrete Examples
Always provide working examples, not abstract descriptions:
```markdown
## Example: Creating a User Authentication Module
**Scenario**: Building JWT-based auth for a Flask API
**Steps**:
1. Install dependencies: `pip install pyjwt flask-login`
2. Create auth.py with [specific structure]
3. Configure middleware in app.py
4. Add protected routes with @login_required
**Result**: Users can register, login, and access protected endpoints
```
### 4. Reference Additional Files Explicitly
When you need to split content, reference it clearly:
```markdown
## Deep Dive: Advanced Patterns
For comprehensive examples of [topic], see [examples.md](examples.md).
For API reference, consult [reference.md](reference.md).
```
## Optimizing for Token Efficiency
### When to Split Files
**Keep in SKILL.md if:**
- Information is needed for 80%+ of use cases
- Content is under ~2000 tokens
- Steps are sequential and interdependent
**Split to separate file if:**
- Content is mutually exclusive (e.g., Python vs JavaScript examples)
- Material is reference-heavy (API docs, configuration options)
- Information is advanced/edge-case focused
### Code as Documentation
Executable scripts serve dual purposes:
1. **Tools Claude can run** without loading code into context
2. **Documentation by example** showing best practices
```markdown
## Generating Boilerplate
Run the initialization script to create project structure:
```bash
./scripts/init-project.sh my-app
```
This creates [description of what's created].
```
Claude can execute this without the script code consuming context tokens.
## Development Workflow
### 1. Start with Evaluation
**Don't guess what skills you need.** Instead:
1. Run Claude on representative tasks
2. Identify where it struggles or asks repetitive questions
3. Capture successful patterns from those sessions
4. Codify into a skill
### 2. Iterate with Claude
Build skills collaboratively:
1. Work with Claude on a task
2. When you find a good solution, ask: "Should we capture this as a skill?"
3. Let Claude help structure the skill content
4. Test with new similar tasks
5. Refine based on actual usage
### 3. Monitor Trigger Accuracy
After creating a skill, test whether it triggers correctly:
**Test scenarios:**
- Direct requests that SHOULD trigger it
- Similar requests that SHOULD trigger it
- Related requests that should NOT trigger it
If triggering is unreliable, refine the `description` field.
### 4. Start Simple, Grow Organically
Begin with a minimal SKILL.md:
- Clear metadata
- One core workflow
- A few examples
Add complexity only when you encounter actual needs:
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when you repeat the same commands
- Create reference files for API documentation
## Common Patterns by Domain
### Code Development Skills
```markdown
---
name: [Framework/Language] [Pattern] Guide
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
---
## When to Use This Skill
Use when building [specific project type] with [language/framework]
## Project Structure
[Standard directory layout]
## Core Workflows
### Create New [Component Type]
[Step-by-step process]
### Common Patterns
[Frequently used code patterns with examples]
## Testing Strategy
[How to test this type of code]
```
### Workflow/Process Skills
```markdown
---
name: [Task] Workflow
description: [Action] for [domain] following [methodology]. Use when [scenario].
---
## When to Use This Skill
Use when you need to [primary task] and [key differentiator]
## Prerequisites
[What's needed before starting]
## Step-by-Step Process
### Phase 1: [Name]
[Detailed steps]
### Phase 2: [Name]
[Detailed steps]
## Quality Checklist
- [ ] [Verification step]
- [ ] [Verification step]
```
### Reference/Documentation Skills
```markdown
---
name: [Topic] Reference
description: [Type of information] for [domain/tool]. Use when [looking up/configuring/understanding] [specific aspects].
---
## Quick Reference
[Most common lookups in concise format]
## Detailed Documentation
See [reference.md](reference.md) for comprehensive API documentation.
## Common Tasks
### Task 1
[Quick example]
### Task 2
[Quick example]
```
## Security Considerations
### For Skill Creators
**Never include in skills:**
- Hardcoded credentials or API keys
- Personal identifying information
- Proprietary code without permission
- Instructions to make unsafe system changes
**Always consider:**
- Can this skill be misused if shared?
- Does it access sensitive file locations?
- Are external dependencies from trusted sources?
### For Skill Users
**Before installing a skill:**
1. Audit all files in the skill package
2. Check for network access attempts
3. Review any bundled scripts for malicious code
4. Verify the source is trustworthy
## Debugging Skills
### Skill Doesn't Trigger
**Checklist:**
1. Is the description specific enough?
2. Does the description mention the trigger scenario?
3. Is the name too generic?
4. Test with explicit requests mentioning keywords from the description
**Example fix:**
- Before: `description: "Python development helpers"`
- After: `description: "Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems."`
### Skill Triggers Too Often
**Checklist:**
1. Is the description too broad?
2. Add negative cases: "Do NOT use for..."
3. Make the domain more specific
### Content Doesn't Load
**Checklist:**
1. Verify file paths in references are correct
2. Check that additional .md files are in the skill package
3. Ensure script paths are relative to skill root
## Skill Metadata Checklist
Before finalizing a skill, verify:
- [ ] Name is under 64 characters
- [ ] Description is under 1024 characters
- [ ] Description includes specific use cases
- [ ] Description mentions when to trigger the skill
- [ ] SKILL.md has YAML frontmatter with both fields
- [ ] "When to Use This Skill" section is present
- [ ] At least one concrete example is included
- [ ] No sensitive information is hardcoded
- [ ] File references are accurate
- [ ] Tested triggering with target scenarios
- [ ] Tested NOT triggering with related but different scenarios
## Resources
### Official Documentation
- [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Engineering Blog Post](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Using Skills Guide](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
### Example Skills
Study Anthropic's pre-built skills for reference:
- Excel (xlsx) - Complex domain with many features
- Word (docx) - Document generation workflows
- PowerPoint (pptx) - Creative + structured content
- PDF (pdf) - File manipulation and analysis
## Quick Start Template
Use this template to begin a new skill:
```markdown
---
name:
description:
---
# [Skill Name]
## When to Use This Skill
Use this skill when:
-
-
Do NOT use this skill for:
-
## Quick Start
[Minimal working example]
## Core Workflows
### Workflow 1: [Name]
1.
2.
3.
**Example:**
```
[Code or command]
```
**Result:** [What this achieves]
## Common Pitfalls
### Issue: [Problem]
**Solution:** [How to avoid/fix]
### Issue: [Problem]
**Solution:** [How to avoid/fix]
## Advanced Topics
[Optional: complex scenarios or optimizations]
```
---
**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.

260
claude-skills/checklist.md Normal file
View File

@@ -0,0 +1,260 @@
# Skill Creation Checklist
Use this checklist when creating or reviewing Agent Skills to ensure quality and effectiveness.
## Pre-Creation
- [ ] Identified a real need (tested Claude on tasks where it struggled or asked repetitive questions)
- [ ] Verified no existing skill already covers this domain
- [ ] Defined clear trigger scenarios (when should this skill activate?)
- [ ] Identified target audience (junior devs, experienced engineers, specific domain experts)
## Metadata (YAML Frontmatter)
- [ ] **Name** is clear and descriptive
- [ ] Under 64 characters
- [ ] Avoids generic terms ("Helper", "Utility")
- [ ] Includes domain/context (e.g., "Python Testing with pytest", not just "Testing")
- [ ] **Description** is specific and trigger-focused
- [ ] Under 1024 characters
- [ ] Includes action verbs
- [ ] Mentions primary use cases
- [ ] Contains keywords from likely user requests
- [ ] Specifies "Use when..." scenarios
- [ ] Example: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building spreadsheet-based reports or data analysis tools."
## Content Structure
- [ ] **"When to Use This Skill"** section is present at the top
- [ ] Lists 3-5 positive scenarios ("Use this skill when...")
- [ ] Lists 2-3 negative scenarios ("Do NOT use this skill for...")
- [ ] Helps Claude decide when to trigger
- [ ] **Quick Start** section provides minimal working example
- [ ] Can be completed in under 5 minutes
- [ ] Demonstrates core value proposition
- [ ] Includes actual code/commands, not pseudocode
- [ ] **Core Workflows** are clearly structured
- [ ] Each workflow has a descriptive name
- [ ] Steps are numbered and actionable
- [ ] Each step explains "what" and "why"
- [ ] Workflows show expected outputs/results
- [ ] **Examples** are concrete and realistic
- [ ] Use real-world scenarios, not "foo/bar" placeholders
- [ ] Include full code, not fragments
- [ ] Show both input and expected output
- [ ] Cover common use cases, not just edge cases
## Progressive Disclosure
- [ ] **Main SKILL.md** contains essential information
- [ ] Under ~3000 tokens if possible
- [ ] Focuses on 80% use cases
- [ ] References additional files when needed
- [ ] **Separate files** used strategically
- [ ] Mutually exclusive content split (e.g., Python vs JavaScript examples)
- [ ] Advanced topics in separate files
- [ ] Deep reference material externalized
- [ ] Files explicitly referenced: "See [examples.md](examples.md) for..."
- [ ] **Scripts** serve dual purpose
- [ ] Executable tools Claude can run
- [ ] Documentation through working code
- [ ] Don't duplicate information in SKILL.md
## Quality Checks
- [ ] **No sensitive information**
- [ ] No hardcoded API keys, passwords, or tokens
- [ ] No personal identifying information
- [ ] No proprietary code without permission
- [ ] Examples use environment variables or placeholders for secrets
- [ ] **Examples are tested**
- [ ] All code examples actually run
- [ ] Commands produce expected output
- [ ] Dependencies are documented
- [ ] Version-specific behavior is noted
- [ ] **Terminology is consistent**
- [ ] Same terms used throughout (not "function" then "method")
- [ ] Acronyms defined on first use
- [ ] Domain-specific jargon explained
- [ ] **Navigation is clear**
- [ ] Headers create logical hierarchy
- [ ] Related sections are linked
- [ ] Table of contents if skill is long
- [ ] File references are accurate
## Security & Safety
- [ ] **Reviewed for security issues**
- [ ] No instructions to disable security features
- [ ] No unsafe system operations
- [ ] Dependencies from trusted sources only
- [ ] Network access is documented and justified
- [ ] **Privacy considerations**
- [ ] No data exfiltration to unexpected locations
- [ ] File access is scoped appropriately
- [ ] User consent for sensitive operations
## Testing & Validation
- [ ] **Trigger accuracy tested**
- [ ] Activates for intended scenarios
- [ ] Doesn't activate for unrelated scenarios
- [ ] Description keywords match user vocabulary
- [ ] **Content accessibility tested**
- [ ] Referenced files load correctly
- [ ] Scripts execute without errors
- [ ] Relative paths are correct
- [ ] **Used in real scenarios**
- [ ] Tested with actual tasks, not hypotheticals
- [ ] Refined based on Claude's usage patterns
- [ ] Addressed gaps discovered during use
## Optimization
- [ ] **Token efficiency considered**
- [ ] Frequently needed info in SKILL.md
- [ ] Rarely needed info in separate files
- [ ] Scripts used instead of inline code where possible
- [ ] Repetitive content templated or scripted
- [ ] **Scanning-friendly format**
- [ ] Clear section headers
- [ ] Bulleted lists for quick reading
- [ ] Code blocks with syntax highlighting
- [ ] Tables for comparison/reference
- [ ] **Progressive complexity**
- [ ] Begins with simple concepts
- [ ] Builds to advanced topics
- [ ] Clear path from beginner to expert
- [ ] Advanced sections clearly marked
## Documentation
- [ ] **README.md includes**
- [ ] Purpose and scope
- [ ] Installation instructions (if needed)
- [ ] Quick start guide
- [ ] File structure explanation
- [ ] Link to official resources
- [ ] **Common pitfalls documented**
- [ ] Known issues listed
- [ ] Workarounds provided
- [ ] Error messages explained
- [ ] Troubleshooting section
- [ ] **Prerequisites stated**
- [ ] Required tools/dependencies
- [ ] Minimum versions specified
- [ ] Assumed knowledge level
- [ ] Setup instructions if complex
## Final Review
- [ ] Read through as a new user
- [ ] Can someone unfamiliar follow along?
- [ ] Are all terms defined?
- [ ] Do examples make sense in context?
- [ ] Test with Claude
- [ ] Ask Claude to use the skill on test tasks
- [ ] Verify it triggers when expected
- [ ] Check that instructions are clear
- [ ] Identify any confusion or gaps
- [ ] Spell check and grammar
- [ ] Professional tone maintained
- [ ] No typos in code or commands
- [ ] Formatting is consistent
- [ ] Package correctly
- [ ] All referenced files included
- [ ] File paths are relative, not absolute
- [ ] Directory structure is clean
- [ ] No unnecessary files (build artifacts, etc.)
## Post-Launch
- [ ] Monitor usage patterns
- [ ] Track when skill triggers
- [ ] Note when it should trigger but doesn't
- [ ] Identify frequently asked questions
- [ ] Iterate based on feedback
- [ ] Update examples that caused confusion
- [ ] Add missing workflows discovered through use
- [ ] Refine description if trigger accuracy is poor
- [ ] Split or merge sections based on token usage
- [ ] Keep current
- [ ] Update when dependencies change versions
- [ ] Revise when best practices evolve
- [ ] Add new patterns as discovered
- [ ] Remove outdated information
## Template Selection
Choose the right starting template:
| If your skill... | Use template |
|------------------|--------------|
| Teaches a framework or library | Code Framework |
| Guides through a multi-step process | Workflow/Process |
| Provides quick reference info | Reference/Lookup |
| Explains how to use a tool | Tool/Utility |
| Doesn't fit above | Start with minimal template and build up |
## Common Mistakes to Avoid
- [ ] **Avoided**: Vague description ("Python helpers")
- **Instead**: Specific description with use cases
- [ ] **Avoided**: No examples or only pseudocode
- **Instead**: Real, runnable examples
- [ ] **Avoided**: Everything in one giant SKILL.md file
- **Instead**: Strategic file splitting for token efficiency
- [ ] **Avoided**: "What" without "why"
- **Instead**: Explain reasoning and trade-offs
- [ ] **Avoided**: Hardcoded secrets or credentials
- **Instead**: Environment variables and configuration
- [ ] **Avoided**: Testing only happy path
- **Instead**: Test errors, edge cases, and "should not trigger" scenarios
- [ ] **Avoided**: Generic names like "Helper" or "Utils"
- **Instead**: Specific, searchable names
- [ ] **Avoided**: Assuming too much knowledge
- **Instead**: State prerequisites and define terms
## Success Criteria
A well-crafted skill should:
✓ Trigger reliably for intended use cases
✓ Load quickly (tokens optimized)
✓ Be immediately useful (quick start works)
✓ Scale from beginner to advanced
✓ Remain current and maintainable
✓ Be secure and privacy-conscious
✓ Provide clear value over generic Claude
---
**Remember**: Skills emerge from real usage. Start minimal, test with actual tasks, and iterate based on what Claude actually needs.

903
claude-skills/examples.md Normal file
View File

@@ -0,0 +1,903 @@
# Skill Examples
This file contains complete, working examples of well-structured skills across different domains.
## Example 1: Python Testing Skill
### Structure
```
python-testing-skill/
├── SKILL.md
└── test-templates/
├── pytest-basic.py
└── pytest-advanced.py
```
### SKILL.md
```markdown
---
name: Python Testing with pytest
description: Create comprehensive Python tests using pytest with fixtures, parametrization, and mocking. Use when writing unit tests, integration tests, or setting up test infrastructure for Python projects.
---
## When to Use This Skill
Use this skill when:
- Writing unit tests for Python functions and classes
- Creating integration tests for Python applications
- Setting up pytest configuration and fixtures
- Implementing test parametrization for multiple scenarios
- Mocking external dependencies in tests
Do NOT use this skill for:
- Testing non-Python code
- End-to-end browser testing (use Playwright skill instead)
- Load testing or performance benchmarking
## Quick Start
Basic test structure:
```python
import pytest
from myapp import add_numbers
def test_add_numbers():
result = add_numbers(2, 3)
assert result == 5
```
Run tests:
```bash
pytest tests/ -v
```
## Core Workflows
### Workflow 1: Writing Unit Tests
1. Create a test file matching your source file: `test_module.py` for `module.py`
2. Import the code to test and pytest
3. Write test functions starting with `test_`
4. Use assert statements for validation
5. Run pytest from project root
**Example:**
```python
# test_calculator.py
import pytest
from calculator import Calculator
def test_addition():
calc = Calculator()
assert calc.add(2, 3) == 5
assert calc.add(-1, 1) == 0
assert calc.add(0, 0) == 0
def test_division_by_zero():
calc = Calculator()
with pytest.raises(ValueError, match="Cannot divide by zero"):
calc.divide(10, 0)
```
### Workflow 2: Using Fixtures
1. Create fixtures for common test setup
2. Use `@pytest.fixture` decorator
3. Accept fixtures as test function parameters
4. Fixtures run automatically before tests
**Example:**
```python
import pytest
from database import Database
@pytest.fixture
def db():
"""Provide a test database instance"""
database = Database(":memory:")
database.setup()
yield database
database.teardown()
def test_create_user(db):
user = db.create_user("alice", "alice@example.com")
assert user.name == "alice"
assert user.email == "alice@example.com"
def test_query_user(db):
db.create_user("bob", "bob@example.com")
user = db.query_user("bob")
assert user is not None
```
### Workflow 3: Parametrized Tests
1. Use `@pytest.mark.parametrize` decorator
2. Provide parameter names and test cases
3. Test function runs once per parameter set
**Example:**
```python
import pytest
from validators import validate_email
@pytest.mark.parametrize("email,expected", [
("user@example.com", True),
("user@domain.co.uk", True),
("invalid@", False),
("@example.com", False),
("no-at-sign.com", False),
("", False),
])
def test_email_validation(email, expected):
assert validate_email(email) == expected
```
### Workflow 4: Mocking External Dependencies
1. Import `unittest.mock` or use `pytest-mock`
2. Use `mocker.patch()` to replace dependencies
3. Configure mock return values or side effects
4. Verify mock interactions
**Example:**
```python
import pytest
from unittest.mock import Mock
from weather_app import get_weather
def test_get_weather(mocker):
# Mock the external API call
mock_api = mocker.patch('weather_app.weather_api.fetch')
mock_api.return_value = {
"temperature": 72,
"conditions": "sunny"
}
result = get_weather("San Francisco")
assert result["temperature"] == 72
assert result["conditions"] == "sunny"
mock_api.assert_called_once_with("San Francisco")
```
## Test Organization
### Project Structure
```
myproject/
├── src/
│ └── myapp/
│ ├── __init__.py
│ ├── core.py
│ └── utils.py
├── tests/
│ ├── __init__.py
│ ├── conftest.py # Shared fixtures
│ ├── test_core.py
│ └── test_utils.py
└── pyproject.toml # pytest configuration
```
### conftest.py for Shared Fixtures
```python
import pytest
from myapp import create_app
@pytest.fixture(scope="session")
def app():
"""Create application for testing"""
app = create_app(testing=True)
return app
@pytest.fixture
def client(app):
"""Test client for making requests"""
return app.test_client()
```
## Configuration
### pyproject.toml
```toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = [
"-v",
"--strict-markers",
"--cov=myapp",
"--cov-report=term-missing",
]
markers = [
"slow: marks tests as slow",
"integration: marks tests as integration tests",
]
```
## Coverage Goals
Aim for:
- 80%+ code coverage for business logic
- 100% coverage for critical paths (auth, payments, data integrity)
- Edge cases and error conditions tested
- Integration tests for key workflows
Check coverage:
```bash
pytest --cov=myapp --cov-report=html
open htmlcov/index.html
```
## Common Pitfalls
### Issue: Tests Pass Locally but Fail in CI
**Solution:**
- Use fixtures to avoid state pollution between tests
- Don't rely on file system state or specific paths
- Mock time-dependent functionality
- Set explicit random seeds for reproducibility
### Issue: Slow Test Suite
**Solution:**
- Use `@pytest.mark.slow` for slow tests, run separately
- Mock external API calls instead of making real requests
- Use in-memory databases for tests
- Run fast unit tests before slow integration tests
### Issue: Fixtures Not Running
**Solution:**
- Ensure fixture name matches parameter name exactly
- Check fixture scope (function/class/module/session)
- Verify conftest.py is in correct location
## Advanced Techniques
### Async Testing
```python
import pytest
@pytest.mark.asyncio
async def test_async_function():
result = await async_fetch_data()
assert result["status"] == "success"
```
### Testing Exceptions with Context
```python
def test_invalid_input():
with pytest.raises(ValueError) as exc_info:
process_data(invalid_input)
assert "expected format" in str(exc_info.value)
```
### Temporary File Testing
```python
def test_file_processing(tmp_path):
# tmp_path is a pytest fixture providing a temporary directory
test_file = tmp_path / "test.txt"
test_file.write_text("test content")
result = process_file(test_file)
assert result.success
```
```
---
## Example 2: API Integration Skill
### SKILL.md
```markdown
---
name: REST API Integration
description: Design and implement RESTful API integrations with proper error handling, authentication, and rate limiting. Use when building API clients or integrating third-party services.
---
## When to Use This Skill
Use this skill when:
- Integrating third-party REST APIs into your application
- Building API client libraries
- Implementing API authentication flows (OAuth, JWT, API keys)
- Handling rate limiting and retries
- Creating robust error handling for API calls
Do NOT use this skill for:
- GraphQL APIs (different query paradigm)
- gRPC or WebSocket connections
- Building API servers (use framework-specific skills)
## Quick Start
Basic API client structure:
```python
import requests
class APIClient:
def __init__(self, base_url, api_key):
self.base_url = base_url
self.session = requests.Session()
self.session.headers.update({
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
})
def get(self, endpoint):
response = self.session.get(f"{self.base_url}{endpoint}")
response.raise_for_status()
return response.json()
```
## Core Workflows
### Workflow 1: Implementing Authentication
**API Key Authentication:**
```python
class APIKeyClient:
def __init__(self, api_key):
self.headers = {"X-API-Key": api_key}
def request(self, method, url, **kwargs):
kwargs.setdefault('headers', {}).update(self.headers)
return requests.request(method, url, **kwargs)
```
**OAuth 2.0 Flow:**
```python
from requests_oauthlib import OAuth2Session
class OAuthClient:
def __init__(self, client_id, client_secret, redirect_uri):
self.client_id = client_id
self.client_secret = client_secret
self.redirect_uri = redirect_uri
self.session = None
def get_authorization_url(self, authorization_base_url):
oauth = OAuth2Session(self.client_id, redirect_uri=self.redirect_uri)
authorization_url, state = oauth.authorization_url(authorization_base_url)
return authorization_url, state
def fetch_token(self, token_url, authorization_response):
oauth = OAuth2Session(self.client_id, redirect_uri=self.redirect_uri)
token = oauth.fetch_token(
token_url,
authorization_response=authorization_response,
client_secret=self.client_secret
)
self.session = oauth
return token
```
### Workflow 2: Error Handling and Retries
```python
import time
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry
class RobustAPIClient:
def __init__(self, base_url, api_key, max_retries=3):
self.base_url = base_url
self.session = requests.Session()
# Configure retry strategy
retry_strategy = Retry(
total=max_retries,
backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET", "POST", "PUT", "DELETE"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
self.session.mount("http://", adapter)
self.session.mount("https://", adapter)
self.session.headers.update({
"Authorization": f"Bearer {api_key}"
})
def request(self, method, endpoint, **kwargs):
url = f"{self.base_url}{endpoint}"
try:
response = self.session.request(method, url, **kwargs)
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 401:
raise AuthenticationError("Invalid or expired API key")
elif e.response.status_code == 404:
raise NotFoundError(f"Resource not found: {endpoint}")
elif e.response.status_code == 429:
raise RateLimitError("Rate limit exceeded")
else:
raise APIError(f"API request failed: {e}")
except requests.exceptions.RequestException as e:
raise APIError(f"Network error: {e}")
class APIError(Exception): pass
class AuthenticationError(APIError): pass
class NotFoundError(APIError): pass
class RateLimitError(APIError): pass
```
### Workflow 3: Rate Limiting
```python
import time
from threading import Lock
class RateLimiter:
def __init__(self, calls_per_second):
self.calls_per_second = calls_per_second
self.min_interval = 1.0 / calls_per_second
self.last_call = 0
self.lock = Lock()
def __call__(self, func):
def wrapper(*args, **kwargs):
with self.lock:
elapsed = time.time() - self.last_call
if elapsed < self.min_interval:
time.sleep(self.min_interval - elapsed)
self.last_call = time.time()
return func(*args, **kwargs)
return wrapper
class RateLimitedClient:
def __init__(self, base_url, api_key, rate_limit=10):
self.client = APIClient(base_url, api_key)
self.limiter = RateLimiter(rate_limit)
@property
def get(self):
return self.limiter(self.client.get)
@property
def post(self):
return self.limiter(self.client.post)
```
### Workflow 4: Pagination Handling
```python
class PaginatedAPIClient(APIClient):
def get_all_pages(self, endpoint, params=None):
"""Fetch all pages of results"""
results = []
page = 1
params = params or {}
while True:
params['page'] = page
response = self.get(endpoint, params=params)
# Adjust based on API response structure
items = response.get('items', [])
results.extend(items)
# Check if more pages exist
if not response.get('has_more', False):
break
page += 1
return results
def get_all_cursor(self, endpoint, params=None):
"""Fetch all results using cursor-based pagination"""
results = []
cursor = None
params = params or {}
while True:
if cursor:
params['cursor'] = cursor
response = self.get(endpoint, params=params)
items = response.get('data', [])
results.extend(items)
cursor = response.get('next_cursor')
if not cursor:
break
return results
```
## Common Patterns
### Request Caching
```python
from functools import lru_cache
import hashlib
import json
class CachedAPIClient(APIClient):
def __init__(self, base_url, api_key, cache_ttl=300):
super().__init__(base_url, api_key)
self.cache = {}
self.cache_ttl = cache_ttl
def _cache_key(self, method, endpoint, params):
key_data = f"{method}:{endpoint}:{json.dumps(params, sort_keys=True)}"
return hashlib.md5(key_data.encode()).hexdigest()
def get_cached(self, endpoint, params=None):
cache_key = self._cache_key("GET", endpoint, params or {})
if cache_key in self.cache:
cached_data, cached_time = self.cache[cache_key]
if time.time() - cached_time < self.cache_ttl:
return cached_data
data = self.get(endpoint, params=params)
self.cache[cache_key] = (data, time.time())
return data
```
### Webhook Signature Verification
```python
import hmac
import hashlib
class WebhookValidator:
def __init__(self, secret):
self.secret = secret.encode()
def verify_signature(self, payload, signature_header):
"""Verify webhook signature"""
expected_signature = hmac.new(
self.secret,
payload.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected_signature, signature_header)
```
## Testing API Integrations
### Using responses Library
```python
import responses
import requests
@responses.activate
def test_api_get():
# Mock the API response
responses.add(
responses.GET,
'https://api.example.com/users/123',
json={'id': 123, 'name': 'Alice'},
status=200
)
client = APIClient('https://api.example.com', 'test-key')
user = client.get('/users/123')
assert user['name'] == 'Alice'
@responses.activate
def test_api_error_handling():
responses.add(
responses.GET,
'https://api.example.com/users/999',
json={'error': 'Not found'},
status=404
)
client = RobustAPIClient('https://api.example.com', 'test-key')
with pytest.raises(NotFoundError):
client.request('GET', '/users/999')
```
## Common Pitfalls
### Issue: Leaking API Keys
**Solution:** Never hardcode keys. Use environment variables or secret management:
```python
import os
api_key = os.environ.get('API_KEY')
if not api_key:
raise ValueError("API_KEY environment variable not set")
```
### Issue: Not Handling Rate Limits
**Solution:** Implement exponential backoff and respect rate limit headers:
```python
def handle_rate_limit(response):
if response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
time.sleep(retry_after)
# Retry request
```
### Issue: Timeout Issues
**Solution:** Always set timeouts:
```python
response = self.session.get(url, timeout=(3.0, 10.0)) # (connect, read)
```
```
---
## Example 3: Documentation Skill
### SKILL.md
```markdown
---
name: Technical Documentation Writer
description: Create clear, comprehensive technical documentation including API docs, README files, user guides, and code comments. Use when documenting code, APIs, or writing user-facing technical content.
---
## When to Use This Skill
Use this skill when:
- Writing README.md files for repositories
- Documenting APIs (REST, GraphQL, SDKs)
- Creating user guides and tutorials
- Writing inline code documentation
- Building developer onboarding materials
Do NOT use this skill for:
- Marketing copy or sales content
- Academic papers or research documentation
- Legal or compliance documentation
## Core Principles
1. **Write for your audience**: Junior developers need more context than senior engineers
2. **Show, don't just tell**: Include code examples for every concept
3. **Start with "why"**: Explain the purpose before the implementation
4. **Maintain consistency**: Use the same terminology throughout
5. **Keep it current**: Documentation that's out of date is worse than no documentation
## README.md Template
```markdown
# Project Name
Brief (1-2 sentence) description of what this project does.
## Features
- Key feature 1
- Key feature 2
- Key feature 3
## Installation
\```bash
npm install project-name
\```
## Quick Start
\```javascript
const Project = require('project-name');
const instance = new Project({
apiKey: 'your-api-key'
});
const result = await instance.doSomething();
console.log(result);
\```
## Documentation
Full documentation available at [link]
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| apiKey | string | required | Your API key |
| timeout | number | 5000 | Request timeout in ms |
## Examples
### Example 1: Basic Usage
[Code example with explanation]
### Example 2: Advanced Pattern
[Code example with explanation]
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
[License type] - see [LICENSE](LICENSE)
```
## API Documentation Template
```markdown
## endpoint_name
Brief description of what this endpoint does.
### HTTP Request
\```
POST /api/v1/resource
\```
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Resource name |
| type | string | No | Resource type (default: "standard") |
| metadata | object | No | Additional metadata |
### Request Example
\```json
{
"name": "example-resource",
"type": "premium",
"metadata": {
"created_by": "user123"
}
}
\```
### Response
\```json
{
"id": "res_abc123",
"name": "example-resource",
"type": "premium",
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
}
\```
### Errors
| Status Code | Error Code | Description |
|-------------|------------|-------------|
| 400 | invalid_name | Name contains invalid characters |
| 401 | unauthorized | Invalid or missing API key |
| 409 | duplicate | Resource with this name already exists |
### Example Usage
\```python
import requests
response = requests.post(
'https://api.example.com/api/v1/resource',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'name': 'example-resource',
'type': 'premium'
}
)
resource = response.json()
print(f"Created resource: {resource['id']}")
\```
```
## Code Comment Guidelines
### Function Documentation
**Python (docstring):**
```python
def calculate_discount(price: float, discount_percent: float, min_price: float = 0) -> float:
"""
Calculate discounted price with minimum price floor.
Args:
price: Original price before discount
discount_percent: Discount percentage (0-100)
min_price: Minimum price floor (default: 0)
Returns:
Final price after applying discount, never below min_price
Raises:
ValueError: If discount_percent is not between 0 and 100
ValueError: If price or min_price is negative
Examples:
>>> calculate_discount(100, 20)
80.0
>>> calculate_discount(100, 20, min_price=85)
85.0
"""
if not 0 <= discount_percent <= 100:
raise ValueError("Discount percent must be between 0 and 100")
if price < 0 or min_price < 0:
raise ValueError("Prices cannot be negative")
discounted = price * (1 - discount_percent / 100)
return max(discounted, min_price)
```
**JavaScript (JSDoc):**
```javascript
/**
* Fetch user data from the API with caching
*
* @param {string} userId - The unique user identifier
* @param {Object} options - Configuration options
* @param {boolean} [options.skipCache=false] - Whether to bypass cache
* @param {number} [options.timeout=5000] - Request timeout in ms
* @returns {Promise<User>} The user object
* @throws {NotFoundError} If user doesn't exist
* @throws {APIError} If the API request fails
*
* @example
* const user = await fetchUser('user123');
* console.log(user.name);
*
* @example
* // Skip cache for fresh data
* const user = await fetchUser('user123', { skipCache: true });
*/
async function fetchUser(userId, options = {}) {
// Implementation
}
```
### Inline Comments
**Good inline comments explain "why", not "what":**
```python
# Good: Explains reasoning
# Use a Set for O(1) lookup time since we'll be checking membership frequently
seen_ids = set()
# Bad: Just repeats what the code says
# Create a set called seen_ids
seen_ids = set()
```
```python
# Good: Explains non-obvious behavior
# Delay between requests to avoid hitting rate limit (10 req/sec)
time.sleep(0.1)
# Bad: States the obvious
# Sleep for 0.1 seconds
time.sleep(0.1)
```
## Common Pitfalls
### Issue: Documentation Out of Sync with Code
**Solution:**
- Keep docs close to code (docstrings, inline comments)
- Auto-generate API docs from code when possible
- Include doc updates in pull request checklist
- Set up CI checks for documentation completeness
### Issue: Too Much or Too Little Detail
**Solution:**
- README: High-level overview + quick start
- API Docs: Complete reference for every parameter
- Tutorials: Step-by-step with context
- Code Comments: Why, not what
### Issue: Examples Don't Run
**Solution:**
- Test all code examples as part of CI
- Use tools like doctest (Python) or jsdoc-to-markdown
- Include a "examples" directory with runnable code
- Version examples alongside code releases
```

729
claude-skills/templates.md Normal file
View File

@@ -0,0 +1,729 @@
# Skill Templates
Ready-to-use templates for common skill types. Copy and customize for your needs.
## Template 1: Code Framework Skill
```markdown
---
name: [Framework Name] Development
description: Build [type of applications] using [framework] following [key principles/patterns]. Use when creating [specific project types] with [key requirements].
---
## When to Use This Skill
Use this skill when:
- Building [specific type] applications with [framework]
- Implementing [key feature] using [framework] patterns
- Setting up [framework] projects with best practices
Do NOT use this skill for:
- [Related but different framework]
- [Different type of application]
## Prerequisites
- [Framework] version X.X or higher
- [Required dependencies]
- Basic understanding of [concepts]
## Quick Start
Create a new project:
\```bash
[command to create project]
\```
Basic structure:
\```[language]
[Minimal working example]
\```
Run the application:
\```bash
[command to run]
\```
## Project Structure
\```
project-name/
├── src/
│ ├── [key directory 1]/
│ ├── [key directory 2]/
│ └── [key file]
├── tests/
├── [config file]
└── README.md
\```
## Core Patterns
### Pattern 1: [Name]
**When to use:** [Scenario]
**Implementation:**
\```[language]
[Code example]
\```
**Key points:**
- [Important detail]
- [Important detail]
### Pattern 2: [Name]
**When to use:** [Scenario]
**Implementation:**
\```[language]
[Code example]
\```
## Common Tasks
### Task 1: [Name]
1. [Step]
2. [Step]
3. [Step]
**Example:**
\```[language]
[Code]
\```
### Task 2: [Name]
1. [Step]
2. [Step]
3. [Step]
**Example:**
\```[language]
[Code]
\```
## Configuration
### [Config File Name]
\```[format]
[Example configuration]
\```
**Options:**
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| [name] | [type] | [default] | [description] |
## Testing
### Unit Tests
\```[language]
[Test example]
\```
### Integration Tests
\```[language]
[Test example]
\```
## Common Pitfalls
### Issue: [Problem]
**Solution:** [How to fix/avoid]
### Issue: [Problem]
**Solution:** [How to fix/avoid]
## Advanced Topics
### [Topic 1]
[Brief explanation and example]
### [Topic 2]
[Brief explanation and example]
## Resources
- Official Documentation: [link]
- Best Practices Guide: [link]
- Community Examples: [link]
```
---
## Template 2: Workflow/Process Skill
```markdown
---
name: [Process Name]
description: [Action verb] for [domain/purpose] following [methodology/standard]. Use when [primary scenario] and [key differentiator].
---
## When to Use This Skill
Use this skill when:
- [Primary use case]
- [Secondary use case]
- [Edge case to include]
Do NOT use this skill for:
- [Common confusion case]
- [Related but different process]
## Overview
[Brief explanation of what this process achieves and why it matters]
## Prerequisites
Before starting, ensure you have:
- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]
## Process Steps
### Phase 1: [Name]
**Goal:** [What this phase accomplishes]
**Steps:**
1. **[Step name]**
- [Detailed action]
- [Why this matters]
- **Output:** [What you should have after this step]
2. **[Step name]**
- [Detailed action]
- [Why this matters]
- **Output:** [What you should have after this step]
**Checkpoint:** [How to verify this phase is complete]
### Phase 2: [Name]
**Goal:** [What this phase accomplishes]
**Steps:**
1. **[Step name]**
- [Detailed action]
- [Why this matters]
- **Output:** [What you should have after this step]
2. **[Step name]**
- [Detailed action]
- [Why this matters]
- **Output:** [What you should have after this step]
**Checkpoint:** [How to verify this phase is complete]
### Phase 3: [Name]
**Goal:** [What this phase accomplishes]
**Steps:**
1. **[Step name]**
- [Detailed action]
- [Why this matters]
- **Output:** [What you should have after this step]
**Checkpoint:** [How to verify this phase is complete]
## Decision Points
### Decision 1: [Name]
**When:** [At what point in the process]
**Question:** [What you need to decide]
**Options:**
- **Option A:** [Description] → Proceed to [next step/phase]
- **Option B:** [Description] → Proceed to [next step/phase]
### Decision 2: [Name]
**When:** [At what point in the process]
**Question:** [What you need to decide]
**Options:**
- **Option A:** [Description] → Proceed to [next step/phase]
- **Option B:** [Description] → Proceed to [next step/phase]
## Quality Checklist
Before considering the process complete, verify:
- [ ] [Quality criterion 1]
- [ ] [Quality criterion 2]
- [ ] [Quality criterion 3]
- [ ] [Quality criterion 4]
## Common Scenarios
### Scenario 1: [Name]
**Situation:** [When this applies]
**Approach:**
1. [Specific step for this scenario]
2. [Specific step for this scenario]
### Scenario 2: [Name]
**Situation:** [When this applies]
**Approach:**
1. [Specific step for this scenario]
2. [Specific step for this scenario]
## Troubleshooting
### Problem: [Issue]
**Symptoms:** [How you know this is happening]
**Solution:** [Steps to resolve]
### Problem: [Issue]
**Symptoms:** [How you know this is happening]
**Solution:** [Steps to resolve]
## Examples
### Example 1: [Scenario Name]
**Context:** [Background and requirements]
**Process:**
1. [What was done in Phase 1]
2. [What was done in Phase 2]
3. [What was done in Phase 3]
**Outcome:** [What was achieved]
**Lessons learned:** [Key insights]
### Example 2: [Scenario Name]
**Context:** [Background and requirements]
**Process:**
1. [What was done in Phase 1]
2. [What was done in Phase 2]
3. [What was done in Phase 3]
**Outcome:** [What was achieved]
**Lessons learned:** [Key insights]
## Templates and Tools
### Template 1: [Name]
\```
[Template content]
\```
### Template 2: [Name]
\```
[Template content]
\```
## References
- [Resource 1]
- [Resource 2]
- [Resource 3]
```
---
## Template 3: Reference/Lookup Skill
```markdown
---
name: [Topic] Reference
description: Quick reference for [specific domain/tool/technology] covering [key aspects]. Use when [looking up/configuring/troubleshooting] [specific scenarios].
---
## When to Use This Skill
Use this skill when:
- Looking up [specific information type]
- Configuring [system/tool]
- Troubleshooting [specific issues]
Do NOT use this skill for:
- [Different but related topic]
- [Step-by-step tutorials - refer to X skill instead]
## Quick Reference
### Most Common Operations
| Operation | Command/Syntax | Example |
|-----------|----------------|---------|
| [Operation 1] | `[syntax]` | `[example]` |
| [Operation 2] | `[syntax]` | `[example]` |
| [Operation 3] | `[syntax]` | `[example]` |
## Command Reference
### Category 1: [Name]
#### [command_name]
**Purpose:** [What it does]
**Syntax:**
\```
[command syntax]
\```
**Options:**
- `[option]`: [description]
- `[option]`: [description]
**Examples:**
\```
[example 1]
[example 2]
\```
#### [command_name]
**Purpose:** [What it does]
**Syntax:**
\```
[command syntax]
\```
**Options:**
- `[option]`: [description]
- `[option]`: [description]
**Examples:**
\```
[example 1]
[example 2]
\```
### Category 2: [Name]
[Similar structure as Category 1]
## Configuration Reference
### [Configuration File/Section Name]
**Location:** `[path/to/config]`
**Format:** [format type]
**Common Settings:**
\```[format]
[example configuration with comments]
\```
**Options:**
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| [name] | [type] | [default] | [description] |
| [name] | [type] | [default] | [description] |
## Common Patterns
### Pattern 1: [Name]
**Use case:** [When to use this]
**Implementation:**
\```
[code/commands]
\```
### Pattern 2: [Name]
**Use case:** [When to use this]
**Implementation:**
\```
[code/commands]
\```
## Troubleshooting
### Error: [Error message or type]
**Cause:** [Why this happens]
**Solution:**
\```
[fix command or steps]
\```
### Error: [Error message or type]
**Cause:** [Why this happens]
**Solution:**
\```
[fix command or steps]
\```
## Tips and Tricks
### Tip 1: [Name]
[Description and example]
### Tip 2: [Name]
[Description and example]
## Related Topics
- **[Related Skill/Topic]**: [When to use instead]
- **[Related Skill/Topic]**: [When to use instead]
## Further Reading
For detailed information, see [reference.md](reference.md)
- Official Documentation: [link]
- Cheat Sheet: [link]
- Common Examples: [link]
```
---
## Template 4: Tool/Utility Skill
```markdown
---
name: [Tool Name]
description: Use [tool] to [primary purpose] for [domain/use case]. Covers [key features] and [integration points].
---
## When to Use This Skill
Use this skill when:
- [Primary use case]
- [Secondary use case]
- [Integration scenario]
Do NOT use this skill for:
- [What the tool doesn't do]
- [Alternative tool suggestion]
## Installation
### Prerequisites
- [System requirement 1]
- [System requirement 2]
### Install
**Using [package manager 1]:**
\```bash
[install command]
\```
**Using [package manager 2]:**
\```bash
[install command]
\```
**Verify installation:**
\```bash
[verify command]
\```
## Quick Start
Minimal example to get started:
\```bash
[command]
\```
Expected output:
\```
[output]
\```
## Core Features
### Feature 1: [Name]
**What it does:** [Description]
**Basic usage:**
\```bash
[command]
\```
**Common options:**
- `[option]`: [what it does]
- `[option]`: [what it does]
**Example:**
\```bash
[example command]
\```
### Feature 2: [Name]
**What it does:** [Description]
**Basic usage:**
\```bash
[command]
\```
**Common options:**
- `[option]`: [what it does]
- `[option]`: [what it does]
**Example:**
\```bash
[example command]
\```
## Common Workflows
### Workflow 1: [Name]
**Goal:** [What you're trying to achieve]
**Steps:**
1. [Step with command]
\```bash
[command]
\```
2. [Step with command]
\```bash
[command]
\```
3. [Step with command]
\```bash
[command]
\```
**Result:** [What you've accomplished]
### Workflow 2: [Name]
[Similar structure]
## Configuration
### Configuration File
**Location:** `[path]`
**Example:**
\```[format]
[configuration example]
\```
### Environment Variables
| Variable | Purpose | Example |
|----------|---------|---------|
| [VAR_NAME] | [description] | `[example value]` |
## Integration
### Integration with [Tool/Framework 1]
\```[language]
[integration example]
\```
### Integration with [Tool/Framework 2]
\```[language]
[integration example]
\```
## Troubleshooting
### Issue: [Problem]
**Symptoms:** [How you know]
**Cause:** [Why it happens]
**Solution:**
\```bash
[fix]
\```
### Issue: [Problem]
**Symptoms:** [How you know]
**Cause:** [Why it happens]
**Solution:**
\```bash
[fix]
\```
## Advanced Usage
### Advanced Feature 1: [Name]
[Description and example]
### Advanced Feature 2: [Name]
[Description and example]
## Best Practices
1. **[Practice 1]:** [Why and how]
2. **[Practice 2]:** [Why and how]
3. **[Practice 3]:** [Why and how]
## Resources
- Official Documentation: [link]
- GitHub Repository: [link]
- Tutorial: [link]
```
---
## Template Selection Guide
Choose your template based on:
| Skill Type | Primary Goal | Use Template |
|------------|--------------|--------------|
| Teaching a framework/library | Help users write code | Code Framework |
| Guiding through a process | Help users complete workflow | Workflow/Process |
| Quick information lookup | Provide reference material | Reference/Lookup |
| Using a specific tool | Help users operate tool | Tool/Utility |
## Customization Tips
1. **Remove unnecessary sections**: If a section doesn't apply, delete it
2. **Add domain-specific sections**: Include what matters for your skill
3. **Adjust examples**: Make examples relevant to actual use cases
4. **Set the right scope**: Focus on one clear purpose per skill
5. **Test trigger accuracy**: Ensure description matches when you want it to activate