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

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