## What Skills Provide Skills fill the gap between what an AI model knows generally and what it needs to know specifically: 1. **Domain Expertise**: Specialized knowledge for particular tools, frameworks, or domains 2. **Procedural Knowledge**: Step-by-step workflows that encode best practices 3. **Tool Instructions**: How to use specific scripts, APIs, or utilities 4. **Quality Standards**: Expected outputs, formats, and criteria 5. **Examples**: Concrete demonstrations of desired behavior ## Core Principles ### 1. Concise is Key ``` ❌ WRONG: Write everything you know about the domain ✅ RIGHT: Include only what's needed to perform the task Skills should be MINIMAL yet COMPLETE: - No unnecessary background information - Every word should serve a purpose - Reference external resources rather than duplicating - Trust the AI's base knowledge ``` ### 2. Set Appropriate Degrees of Freedom ``` Consider what should be: FIXED (Skill defines exactly): - Output formats and structures - Required steps in a workflow - Quality criteria and standards - Tool usage patterns VARIABLE (User can customize): - Input parameters - Scope and context - Optional enhancements - Trade-off decisions ``` ### 3. Progressive Disclosure ``` Design skills to load information on-demand: IMMEDIATE (In SKILL.md): - Core workflow steps - Essential patterns - Quick-start instructions DEFERRED (In supporting files): - Detailed examples - Edge case handling - Reference documentation - Helper scripts ``` ## Anatomy of a Skill ### SKILL.md Structure ```markdown --- name: my-skill description: A clear, one-sentence description that helps the AI know when to apply this skill. Include trigger keywords. license: Optional license information --- ## Core Workflow [Main procedural steps] ## Key Patterns [Essential patterns and examples] ## Best Practices [Quality guidelines] ## Resources [Links to supporting files and documentation] ``` ### Supporting Structure ``` my-skill/ ├── SKILL.md # Main entry point (required) ├── examples/ # Concrete examples (optional) │ ├── basic-usage.md │ └── advanced-patterns.md ├── scripts/ # Helper scripts (optional) │ ├── helper.py │ └── validate.sh └── resources/ # Reference materials (optional) └── templates/ ``` ## Skill Creation Process ### Step 1: Understand with Concrete Examples ``` Before creating a skill, gather: 1. **3-5 Real Examples** - Actual tasks someone would perform - Input/output pairs showing expected behavior - Edge cases and variations 2. **Anti-Examples** - What the skill should NOT do - Common mistakes to avoid - Out-of-scope requests 3. **Success Criteria** - How do you know the skill worked correctly? - What quality bar must be met? ``` ### Step 2: Plan the Reusable Skill ``` Define the skill's scope: 1. **Fixed Elements** - What output format is required? - What steps are always necessary? - What quality standards apply? 2. **Variable Elements** - What inputs does the user provide? - What options are configurable? - What decisions depend on context? 3. **Supporting Resources** - What examples help demonstrate patterns? - What scripts automate common tasks? - What references provide deeper guidance? ``` ### Step 3: Write the SKILL.md ``` Craft an effective skill description: 1. **Name**: Clear, action-oriented (verb-noun format) - ✅ "pdf-creator", "api-tester", "code-reviewer" - ❌ "pdf-stuff", "api-things", "code-helper" 2. **Description**: Trigger-rich, specific - Include keywords that identify use cases - Be specific about capabilities - Mention target platforms/formats 3. **Content**: Minimal but complete - Essential workflow steps - Key patterns with examples - References to supporting materials ``` ### Step 4: Test and Iterate ``` Validate the skill: 1. **Trigger Testing** - Does the skill activate for intended use cases? - Does it stay dormant for unrelated requests? 2. **Quality Testing** - Do outputs meet expected standards? - Are edge cases handled correctly? 3. **Usability Testing** - Is the skill easy to understand? - Are instructions clear? 4. **Iteration** - Refine based on test results - Add examples for unclear patterns - Remove unnecessary content ``` ## Example: Creating a Code Review Skill ````markdown --- name: code-review description: Perform thorough code reviews on pull requests. Use when asked to review code, check for bugs, evaluate code quality, or provide PR feedback. --- ## Review Process 1. **Understand Context** - What is this code trying to do? - What patterns does the codebase use? 2. **Check for Issues** - Logic errors and bugs - Security vulnerabilities - Performance problems - Code style violations 3. **Provide Feedback** - Be specific and actionable - Explain the "why" not just the "what" - Prioritize by severity ## Feedback Format ```markdown ## Summary [1-2 sentence overall assessment] ## Critical Issues 🔴 [Must fix before merge] ## Suggestions 🟡 [Should consider fixing] ## Nitpicks 🟢 [Optional improvements] ## What's Good ✨ [Positive feedback] ``` ```` ## Best Practices - Always explain reasoning - Suggest specific fixes - Balance criticism with praise ``` ## Best Practices for Skill Authors 1. **Start Small**: Begin with the minimal viable skill, expand based on feedback 2. **Use Progressive Disclosure**: Don't front-load everything into SKILL.md 3. **Provide Examples**: Show, don't just tell 4. **Test Trigger Words**: Ensure the description activates for right use cases 5. **Iterate Based on Usage**: Refine based on real-world application 6. **Document Dependencies**: Clearly state required tools or setup 7. **Version Your Skills**: Track changes for team coordination ## Skill Distribution ``` Skills can be shared via: 1. **Git Repositories** - Clone into ~/.claude/skills/ or equivalent - Version controlled and collaborative 2. **Skill Marketplaces** - SkillsMP.com - Skillstore.io 3. **Team Distribution** - Shared drives or internal registries - Company skill libraries ``` ## Related Resources - [Anthropic Skills Repository](https://github.com/anthropics/skills) - [Agent Skills Specification](https://github.com/anthropics/skills/tree/main/spec) - [Awesome Claude Skills](https://github.com/travisvn/awesome-claude-skills) ```