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

297
claude-code/skills/claude-skills/best-practices.md Normal file
View File

@@ -0,0 +1,297 @@
# Skill Best Practices
Comprehensive guidelines for creating effective Agent Skills.
## Progressive Disclosure Architecture
Skills work 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
### Layer 2: Instructions (Triggered)
- **What**: Main SKILL.md content
- **When**: Loads when Claude determines skill applies
- **Cost**: Variable (keep under 1000 tokens)
- **Purpose**: Procedural guidance, workflows
### Layer 3: Resources (On-Demand)
- **What**: Additional files, scripts, reference materials
- **When**: Only when explicitly needed
- **Cost**: Only when accessed
- **Purpose**: Deep reference, examples
## 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
```
[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."
## Skill File Structure
### Mandatory: SKILL.md
```yaml
---
name: Your Skill Name # Max 64 chars
description: Clear description of usage # Max 1024 chars
---
```
### Optional: Additional Resources
```
my-skill/
├── SKILL.md # Main entry (required)
├── reference.md # Deep reference
├── examples.md # Code samples
├── workflows/ # Step-by-step procedures
│ ├── advanced.md
│ └── beginner.md
└── scripts/ # Executable utilities
└── helper.sh
```
## SKILL.md Content Structure
### 1. Start with "When to Use This Skill"
```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
```markdown
## Quick Start
[Minimal example to get started]
## Core Workflows
### Workflow 1: [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
```markdown
## Deep Dive: Advanced Patterns
For comprehensive examples, 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 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:
```bash
./scripts/init-project.sh my-app
```
This creates [description of what's created].
```
Claude can execute this without 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 triggering:
**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 minimal SKILL.md:
- Clear metadata
- One core workflow
- A few examples
Add complexity only when needed:
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when repeating same commands
- Create reference files for API documentation
## Common Anti-Patterns
### ❌ Generic Description
```yaml
description: Helps with coding
```
**Fix**: Be specific about domain and triggers
### ❌ No Process Defined
```markdown
You are a code reviewer. Review code.
```
**Fix**: Define step-by-step process
### ❌ All Tools Granted
```yaml
# Omitting tools when only reads needed
```
**Fix**: Whitelist minimum required tools
### ❌ Verbose Prompt
```markdown
You are an expert developer with 20 years of experience... [3000 words]
```
**Fix**: Be concise, focus on process and format
## Testing Skills
### Test Plan Template
```markdown
# Positive Tests (Should Activate)
1. "Create REST endpoint for user auth"
Expected: Activates
Actual: ___
# Negative Tests (Should NOT Activate)
1. "Write unit tests for API"
Expected: Does not activate
Actual: ___
## Results
- Precision: X%
- Recall: Y%
```
## Security Considerations
### Never Include
- 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?
## Skill Metadata Checklist
Before finalizing:
- [ ] Name is under 64 characters
- [ ] Description is under 1024 characters
- [ ] Description includes specific use cases
- [ ] Description mentions when to trigger
- [ ] SKILL.md has YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example
- [ ] No sensitive information
- [ ] File references are accurate
- [ ] Tested triggering scenarios
- [ ] Tested NOT triggering scenarios
## Summary
**Best practices in order of importance:**
1. **Write specific descriptions** with clear triggers
2. **Structure progressively** (metadata → core → details)
3. **Start simple** and grow based on actual needs
4. **Test thoroughly** with positive and negative scenarios
5. **Optimize tokens** by splitting appropriately
6. **Provide examples** not just theory
7. **Monitor usage** and refine based on feedback