claude-plugins/claude-skills-plugin/README.md

# Claude Skills Plugin

Meta-skill for creating effective Agent Skills with best practices, structure guidelines, and progressive disclosure principles.

## What's Included

The **claude-skills** skill provides comprehensive guidance for building high-quality Agent Skills that work efficiently with Claude Code and Claude.ai.

### claude-skills (Skill Creator)

A comprehensive guide covering:
- **Progressive disclosure** - Three-layer architecture (metadata → instructions → resources)
- **Trigger optimization** - Writing descriptions that activate at the right time
- **Token efficiency** - Strategic file splitting and on-demand loading
- **Development workflow** - Iterative approach to skill creation
- **Security considerations** - Best practices for safe skill creation and usage

**Includes:**
- `SKILL.md` - Complete best practices guide
- `examples.md` - Working examples across different domains
- `templates.md` - Ready-to-use templates for common skill types
- `checklist.md` - Quality assurance checklist
- `README.md` - Skill-specific overview

## 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

## Installation

### For Claude Code

Install from marketplace:

```bash
/plugin install claude-skills@claude-skills-marketplace
```

Or install from local directory:

```bash
/plugin install /path/to/Skills/claude-skills-plugin@local
```

### For Claude.ai

1. Zip this plugin directory
2. Go to Settings > Capabilities > Upload skill
3. Upload the zip file
4. Enable the plugin

## Usage

Once installed, the skill activates automatically when you work on skill-related tasks:

```
"Help me create a skill for Python testing"
"Why isn't my skill triggering?"
"How do I optimize my skill for token usage?"
"Review my skill structure"
```

## Key Concepts

### Progressive Disclosure

Skills use a three-layer architecture:

**Layer 1: Metadata (Always Loaded)**
- YAML frontmatter with `name` and `description`
- ~100 tokens per skill
- Used for trigger detection

**Layer 2: Instructions (Triggered)**
- Main SKILL.md content
- Procedural guidance and workflows
- Loaded when skill is relevant

**Layer 3: Resources (On-Demand)**
- Additional files, scripts, reference materials
- Loaded only when explicitly needed
- Maximizes token efficiency

### Writing Effective Descriptions

The description field determines when your skill triggers:

**Good Descriptions:**
```yaml
description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when working with .xlsx files, data analysis, or generating reports.
```

**Poor Descriptions:**
```yaml
description: Helps with coding tasks
```

### Skill Structure

Every skill MUST have:
```yaml
---
name: Your Skill Name (max 64 chars)
description: Clear description with use cases (max 1024 chars)
---

# Skill content
```

## What You'll Learn

### From SKILL.md
- When to use progressive disclosure
- How to write effective descriptions
- Structuring content for scannability
- Token optimization techniques
- Development workflow best practices
- Security considerations

### From examples.md
- Python testing with pytest
- REST API integration patterns
- Technical documentation writing
- Real-world skill structures

### From templates.md
- Code framework skill template
- Workflow/process skill template
- Reference/lookup skill template
- Tool/utility skill template

### From checklist.md
- Metadata requirements
- Content quality checks
- Trigger testing scenarios
- Security review items

## Quick Start

### Creating Your First Skill

1. Ask Claude: "Help me create a skill for [your topic]"
2. Claude will guide you through:
   - Choosing the right template
   - Writing an effective description
   - Structuring content efficiently
   - Adding concrete examples

### Improving an Existing Skill

1. Ask Claude: "Review my skill at [path]"
2. Claude will analyze:
   - Trigger accuracy
   - Structure optimization
   - Content clarity
   - Best practices alignment

## Best Practices Summary

**DO:**
- Keep SKILL.md focused and concise
- Use clear, scannable hierarchies
- Include concrete, working examples
- Reference additional files explicitly
- Start simple, expand based on need

**DON'T:**
- Create vague descriptions
- Add unnecessary complexity upfront
- Hardcode sensitive data
- Skip testing trigger scenarios

## Development Workflow

1. **Start with Evaluation** - Work with Claude on tasks, identify patterns
2. **Iterate Collaboratively** - Let Claude help structure the skill
3. **Test Triggering** - Verify activation with target scenarios
4. **Start Simple** - Begin minimal, expand based on actual needs

## Skills Checklist

Before finalizing a skill:

- [ ] Name ≤ 64 characters
- [ ] Description ≤ 1024 characters and specific
- [ ] Description includes trigger scenarios
- [ ] SKILL.md has valid YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example included
- [ ] No sensitive information hardcoded
- [ ] File references are accurate
- [ ] Tested triggering with target scenarios
- [ ] Tested NOT triggering with unrelated scenarios

## Common Patterns

### Code Development Skills
```yaml
---
name: [Framework] Development Guide
description: Build [framework] applications following [patterns]. Use when building [type] with [requirements].
---
```

### Workflow Skills
```yaml
---
name: [Task] Workflow
description: Execute [task] following [methodology]. Use when [scenario].
---
```

### Reference Skills
```yaml
---
name: [Topic] Reference
description: Quick reference for [domain]. Use when looking up [specific aspects].
---
```

## Resources

- [Official Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Engineering Blog](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)

## Version History

### 1.0.0 (Initial Release)
- Complete best practices guide (SKILL.md)
- Working examples across domains (examples.md)
- Ready-to-use templates (templates.md)
- Quality assurance checklist (checklist.md)

## Contributing

Found an issue or have improvements? See the main marketplace [CONTRIBUTING.md](../CONTRIBUTING.md).

## License

See main marketplace repository for license information.

---

**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.