feat: Convert to Claude Code plugin marketplace
Transform repository into a plugin marketplace structure with two plugins: - claude-code plugin: Complete toolkit with 5 skills * claude-code-plugins * claude-code-slash-commands * claude-code-hooks * claude-code-subagents * claude-code-memory - claude-skills plugin: Meta-skill for creating Agent Skills * Comprehensive best practices guide * Templates and examples * Progressive disclosure patterns Infrastructure: - Add marketplace.json manifest - Create plugin.json for each plugin - Update documentation for marketplace structure - Add contribution and testing guides Installation: - /plugin install claude-code@claude-skills - /plugin install claude-skills@claude-skills 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
movq
151
claude-skills-plugin/skills/claude-skills/README.md
Normal file
151
claude-skills-plugin/skills/claude-skills/README.md
Normal 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-plugin/skills/claude-skills/SKILL.md
Normal file
456
claude-skills-plugin/skills/claude-skills/SKILL.md
Normal 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-plugin/skills/claude-skills/checklist.md
Normal file
260
claude-skills-plugin/skills/claude-skills/checklist.md
Normal 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-plugin/skills/claude-skills/examples.md
Normal file
903
claude-skills-plugin/skills/claude-skills/examples.md
Normal 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-plugin/skills/claude-skills/templates.md
Normal file
729
claude-skills-plugin/skills/claude-skills/templates.md
Normal 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
|
||||
Reference in New Issue
Block a user