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

Refinement for context size

Browse Source
This commit is contained in:
movq
2025-10-28 12:48:17 -05:00
parent 35d2069861
commit ddea00cb40
11 changed files with 1539 additions and 1196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

482
claude-code/skills/claude-skills/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: Skill Creator
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use PROACTIVELY when creating new skills, refining existing skills, debugging why skills don't trigger, optimizing SKILL.md files for token efficiency, or when users mention "create a skill", "skill not working", or "skill.md". NOT for using existing skills.
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use PROACTIVELY BEFORE starting skill creation to review best practices, DURING skill structuring to optimize content organization, AFTER completing a skill draft to validate triggers and structure, or when users mention "create a skill", "skill not working", or "skill.md". NOT for using existing skills.
---
# Skill Creation Best Practices
@@ -10,94 +10,82 @@ description: Guide for creating effective Claude Agent Skills with best practice
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
- Debugging why a skill isn't triggering
- Optimizing skill structure for token efficiency
- Before, during, and after skill creation
## Core Principle: Progressive Disclosure
**Progressive disclosure is the fundamental design pattern for Agent Skills.** It works in three layers:
**The fundamental design pattern for Agent Skills.**
### 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
### Three Layers
### 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
1. **Metadata** (Always Loaded ~100 tokens)
- YAML frontmatter: `name` and `description`
- Triggers skill activation
### 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
2. **Instructions** (Triggered ~800-1000 tokens)
- Main SKILL.md content
- Workflows and guidance
3. **Resources** (On-Demand)
- Additional files loaded when needed
- Examples, reference docs, scripts
## Skill Structure Requirements
### Mandatory: SKILL.md File
Every skill MUST have a `SKILL.md` file with YAML frontmatter:
### Mandatory: SKILL.md
```yaml
---
name: Your Skill Name
description: Clear description of what this does and when to use it
name: Your Skill Name # Max 64 chars
description: What it does and when to use it # Max 1024 chars
---
```
**Critical Constraints:**
- Name: Maximum 64 characters
- Description: Maximum 1024 characters
- **The description is crucial** - it determines when Claude triggers the skill
**Critical**: The description determines when Claude triggers the skill.
### Optional: Additional Resources
Structure additional files strategically:
### Optional: Additional Files
```
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
├── SKILL.md # Required entry point
├── examples.md # Working code samples
├── reference.md # Deep API docs
└── workflows/
├── beginner.md
└── advanced.md
```
## 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
The `description` is your trigger mechanism.
### Template
```
[Action verb] [specific domain/task] [with/for/using] [key capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios].
[Action] [domain/task] [with capabilities].
Use when [trigger scenario]. PROACTIVELY when [context].
```
**Example:** "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports."
### Examples
## Best Practices for SKILL.md Content
**✓ Good**:
```yaml
description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building reports or data analysis.
### 1. Start with "When to Use This Skill"
description: Debug Swift applications using LLDB for crashes, memory issues, and runtime errors. Use PROACTIVELY when encountering Swift bugs.
```
Immediately clarify trigger scenarios:
**✗ Poor**:
```yaml
description: Helps with coding
description: Python utilities
description: Security checker
```
## Essential SKILL.md Structure
### 1. When to Use This Skill
```markdown
## When to Use This Skill
@@ -105,142 +93,126 @@ Immediately clarify trigger scenarios:
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]
- [Common confusion]
- [Different tool]
```
### 2. Structure for Scannability
Use clear hierarchies and action-oriented headers:
### 2. Quick Start
```markdown
## Quick Start
[Minimal example to get started]
Minimal working example:
```[language]
[code]
```
**Result**: [What this achieves]
```
### 3. Core Workflows
```markdown
## Core Workflows
### Workflow 1: [Name]
1. Step one
2. Step two
### Workflow 2: [Name]
1. Step one
2. Step two
1. [Step]
2. [Step]
3. [Step]
## Advanced Techniques
[Less common but powerful approaches]
## Common Pitfalls
[Known issues and how to avoid them]
**Example**:
```[language]
[code]
```
```
### 3. Include Concrete Examples
Always provide working examples, not abstract descriptions:
### 4. Additional Resources
```markdown
## Example: Creating a User Authentication Module
## Additional Resources
**Scenario**: Building JWT-based auth for a Flask API
**Need more?**
- [Examples](examples.md) - Working code samples
- [Reference](reference.md) - API documentation
- [Advanced Workflows](workflows/advanced.md)
**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
💡 **Tip**: These load only when referenced.
```
### 4. Reference Additional Files Explicitly
## Token Optimization
When you need to split content, reference it clearly:
### Target Sizes
- SKILL.md: 800-1000 tokens (~200-250 lines)
- Supplementary files: As needed
```markdown
## Deep Dive: Advanced Patterns
### When to Split
For comprehensive examples of [topic], see [examples.md](examples.md).
**Keep in SKILL.md**:
- Needed 80%+ of time
- Under 1000 tokens
- Sequential steps
For API reference, consult [reference.md](reference.md).
```
**Move to separate file**:
- Mutually exclusive content
- Reference material
- Advanced/edge cases
## Optimizing for Token Efficiency
### Compression Techniques
### 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.
1. **Bullet points > Paragraphs** (50% more efficient)
2. **Code examples > Prose** (show don't tell)
3. **References > Embedding** (load on-demand)
4. **Concrete > Abstract** (examples beat theory)
## Development Workflow
### 1. Start with Evaluation
### 1. Identify Need
**Don't guess what skills you need.** Instead:
Don't guess - observe:
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. Find repeated questions or struggles
3. Capture successful patterns
4. Codify into skill
### 2. Iterate with Claude
### 2. Start Minimal
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
```yaml
---
name: My Skill
description: [Specific, clear trigger description]
---
### 3. Monitor Trigger Accuracy
## When to Use This Skill
[Clear scenarios]
After creating a skill, test whether it triggers correctly:
## Quick Start
[One minimal example]
**Test scenarios:**
- Direct requests that SHOULD trigger it
- Similar requests that SHOULD trigger it
- Related requests that should NOT trigger it
## Core Workflow
[3-5 essential steps]
```
If triggering is unreliable, refine the `description` field.
### 3. Test Triggering
### 4. Start Simple, Grow Organically
**Positive tests** (should activate):
- "Create X using Y"
- "[Domain-specific request]"
Begin with a minimal SKILL.md:
- Clear metadata
- One core workflow
- A few examples
**Negative tests** (should NOT activate):
- "[Related but different domain]"
- "[Different tool's purpose]"
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
### 4. Grow Organically
Add only when needed:
- More examples from actual usage
- Advanced workflows when requested
- Reference docs when API is complex
- Scripts for repeated commands
## Common Patterns by Domain
@@ -248,28 +220,25 @@ Add complexity only when you encounter actual needs:
```markdown
---
name: [Framework/Language] [Pattern] Guide
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
name: [Framework] [Pattern] Guide
description: [Action] [framework] applications following [pattern]. Use when building [type] with [requirements].
---
## When to Use This Skill
Use when building [specific project type] with [language/framework]
[Specific project types]
## Project Structure
[Standard directory layout]
[Standard layout]
## Core Workflows
### Create New [Component Type]
[Step-by-step process]
### Common Patterns
[Frequently used code patterns with examples]
### Create [Component]
[Steps]
## Testing Strategy
[How to test this type of code]
[How to test]
```
### Workflow/Process Skills
### Workflow Skills
```markdown
---
@@ -277,135 +246,71 @@ 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]
[What's needed]
## Step-by-Step Process
### Phase 1: [Name]
[Detailed steps]
### Phase 2: [Name]
[Detailed steps]
[Steps]
## Quality Checklist
- [ ] [Verification step]
- [ ] [Verification step]
- [ ] [Verification]
```
### 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
**Fix description**:
```yaml
# ❌ Too vague
description: Python development helpers
**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."`
# ✓ Specific with triggers
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
**Add negatives**:
```markdown
## When to Use This Skill
Use when:
- [Specific scenario]
Do NOT use for:
- [Broader scenario that should use different skill]
```
### 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
**Check references**:
- Verify file paths are correct
- Ensure .md files exist in skill directory
- Use relative paths from skill root
## Skill Metadata Checklist
## Skill Checklist
Before finalizing a skill, verify:
Before finalizing:
- [ ] 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
- [ ] Name under 64 characters
- [ ] Description under 1024 characters, includes triggers
- [ ] SKILL.md has YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example
- [ ] No sensitive information
- [ ] File references work
- [ ] Tested positive trigger scenarios
- [ ] Tested negative scenarios (doesn't over-trigger)
- [ ] Size under 1000 tokens for SKILL.md
## Quick Start Template
Use this template to begin a new skill:
```markdown
---
name:
description:
name: [Skill Name]
description: [Action] [domain] [with capabilities]. Use when [scenario]. PROACTIVELY when [context].
---
# [Skill Name]
@@ -413,11 +318,11 @@ description:
## When to Use This Skill
Use this skill when:
-
-
- [Primary scenario]
- [Secondary scenario]
Do NOT use this skill for:
-
- [Common confusion]
## Quick Start
@@ -427,30 +332,43 @@ Do NOT use this skill for:
### Workflow 1: [Name]
1.
2.
3.
1. [Step]
2. [Step]
3. [Step]
**Example:**
**Example**:
```
[Code or command]
[code]
```
**Result:** [What this achieves]
**Result**: [What this achieves]
## Common Pitfalls
### Issue: [Problem]
**Solution:** [How to avoid/fix]
**Solution**: [Fix]
### Issue: [Problem]
**Solution:** [How to avoid/fix]
## Additional Resources
## Advanced Topics
**Need more?**
- [Examples](examples.md) - Working samples
- [Reference](reference.md) - API docs
- [Advanced](workflows/advanced.md) - Complex patterns
[Optional: complex scenarios or optimizations]
💡 **Tip**: [Key insight]
```
## Additional Resources
**Need more?**
- [Skill Examples](examples.md) - Complete working skills
- [Best Practices Guide](best-practices.md) - Comprehensive guidelines
- [Templates](templates.md) - Ready-to-use templates
- [Checklist](checklist.md) - Validation checklist
- [Official Docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
💡 **Tip**: Best skills emerge from real usage. Start simple, iterate based on actual needs, prioritize clarity over comprehensiveness.
---
**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.
**Remember**: Specific descriptions trigger correctly. Progressive disclosure saves tokens. Test thoroughly. Start minimal and grow organically.