From cb6b9f532a4be88948b995ebd02e3c615d4ba756 Mon Sep 17 00:00:00 2001 From: movq Date: Fri, 17 Oct 2025 10:32:29 -0500 Subject: [PATCH] skills skill v1 --- .gitignore | 1 + claude-skills/README.md | 151 +++++++ claude-skills/SKILL.md | 456 +++++++++++++++++++ claude-skills/checklist.md | 260 +++++++++++ claude-skills/examples.md | 903 +++++++++++++++++++++++++++++++++++++ claude-skills/templates.md | 729 ++++++++++++++++++++++++++++++ 6 files changed, 2500 insertions(+) create mode 100644 .gitignore create mode 100644 claude-skills/README.md create mode 100644 claude-skills/SKILL.md create mode 100644 claude-skills/checklist.md create mode 100644 claude-skills/examples.md create mode 100644 claude-skills/templates.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d6b130c --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.claude/settings.local.json diff --git a/claude-skills/README.md b/claude-skills/README.md new file mode 100644 index 0000000..cd9163a --- /dev/null +++ b/claude-skills/README.md @@ -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. diff --git a/claude-skills/SKILL.md b/claude-skills/SKILL.md new file mode 100644 index 0000000..9348419 --- /dev/null +++ b/claude-skills/SKILL.md @@ -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. diff --git a/claude-skills/checklist.md b/claude-skills/checklist.md new file mode 100644 index 0000000..21795f6 --- /dev/null +++ b/claude-skills/checklist.md @@ -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. diff --git a/claude-skills/examples.md b/claude-skills/examples.md new file mode 100644 index 0000000..064c161 --- /dev/null +++ b/claude-skills/examples.md @@ -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} 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 +``` diff --git a/claude-skills/templates.md b/claude-skills/templates.md new file mode 100644 index 0000000..3957cb6 --- /dev/null +++ b/claude-skills/templates.md @@ -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