Skill Development

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (required)
│   │   ├── name
│   │   └── description
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/          - Executable code
    ├── references/       - Documentation for context
    └── assets/           - Files used in output

---
name: API Testing
description: This skill should be used when the user wants to test APIs, write API tests, or validate API responses. Provides guidance on REST API testing, authentication, and response validation.
version: 1.0.0
---

# API Testing Skill

## Overview

This skill provides comprehensive guidance for testing REST APIs...

## When to Use

Use this skill when:
- Writing API integration tests
- Validating API responses
- Testing authentication flows

## Testing Process

[Step-by-step instructions...]

description: This skill should be used when the user wants to "create a dashboard", "build a UI", "design a frontend", or needs production-grade frontend code with distinctive aesthetics. Provides guidance on typography, color, animations, and avoiding generic AI patterns.

description: For frontend work

scripts/
├── rotate_pdf.py
├── analyze_data.py
└── format_code.sh

To rotate a PDF, execute:
```bash
python ${CLAUDE_PLUGIN_ROOT}/skills/pdf-tools/scripts/rotate_pdf.py \
  --input input.pdf \
  --output output.pdf \
  --degrees 90

### References Directory

Documentation and reference material loaded as needed:

**When to include:**
- Database schemas
- API documentation
- Domain knowledge
- Company policies
- Detailed workflow guides

**Benefits:**
- Keeps SKILL.md lean
- Loaded only when needed
- Avoids context window bloat

**Best practice:**
If files are large (>10k words), include grep search patterns in SKILL.md:

```markdown
For database schema details, read:
- `references/database-schema.md`
- Search for table names: `grep "Table:" references/database-schema.md`

assets/
├── logo.png
├── template.html
├── frontend-boilerplate/
└── font.ttf

Copy the React template:
```bash
cp -r ${CLAUDE_PLUGIN_ROOT}/skills/frontend/assets/react-template/ ./

## Skill Creation Process

<Steps>
  <Step title="Understand Use Cases">
    Identify concrete examples of how the skill will be used.
    
    Ask:
    - What functionality should this skill support?
    - Can you give examples of how this skill would be used?
    - What are the common workflows?
  </Step>
  
  <Step title="Write Strong Description">
    Create description with:
    - Third-person phrasing
    - Specific trigger phrases in quotes
    - Multiple use cases
    - Clear explanation of what skill provides
  </Step>
  
  <Step title="Draft Core Instructions">
    Write SKILL.md with:
    - Clear overview
    - When to use
    - Step-by-step workflows
    - Examples
    
    Keep under 5k words - move details to references.
  </Step>
  
  <Step title="Add References">
    Create reference files for:
    - Detailed documentation
    - Schemas and specs
    - Examples and templates
    - Domain knowledge
  </Step>
  
  <Step title="Bundle Scripts">
    Add scripts for:
    - Repeated operations
    - Deterministic tasks
    - Complex operations
  </Step>
  
  <Step title="Include Assets">
    Add assets for:
    - Templates
    - Images
    - Boilerplate code
  </Step>
  
  <Step title="Test Triggering">
    Verify skill triggers correctly:
    - Use trigger phrases from description
    - Test with different phrasings
    - Check skill loads when expected
  </Step>
</Steps>

## Example Skills

### Frontend Design Skill

`skills/frontend-design/SKILL.md`:

```markdown
---
name: Frontend Design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to "build web components", "create a page", "design UI", or mentions frontend development. Generates creative, polished code that avoids generic AI aesthetics.
version: 1.0.0
---

# Frontend Design Skill

## Overview

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics.

## Design Principles

### Bold Aesthetic Direction

Before coding, commit to a distinctive aesthetic:
- Brutally minimal
- Maximalist chaos
- Retro-futuristic
- Luxury/refined
- Editorial/magazine

### Typography

- Choose distinctive fonts
- Avoid generic fonts (Inter, Roboto, Arial)
- Pair display font with refined body font

### Color & Theme

- Commit to cohesive aesthetic
- Use CSS variables
- Dominant colors with sharp accents

[Additional guidance...]

---
name: API Testing
description: This skill should be used when the user wants to "test APIs", "write API tests", "validate API responses", or mentions REST API testing, authentication testing, or integration tests.
version: 1.0.0
---

# API Testing Skill

## Testing Process

1. **Setup**
   - Identify API endpoint
   - Determine authentication method
   - Review API documentation

2. **Test Cases**
   - Happy path (200 responses)
   - Error cases (400, 401, 404, 500)
   - Edge cases (empty data, large payloads)
   - Authentication flows

3. **Implementation**
   - Use project test framework
   - Mock external dependencies
   - Assert response structure and data

## Scripts

Use the test generator script:
```bash
python ${CLAUDE_PLUGIN_ROOT}/skills/api-testing/scripts/generate_tests.py \
  --spec openapi.json \
  --output tests/

`skills/api-testing/scripts/generate_tests.py`:
```python
#!/usr/bin/env python3
import json
import sys

def generate_tests(spec_file, output_dir):
    # Generate test cases from OpenAPI spec
    pass

if __name__ == "__main__":
    # Script implementation
    pass

# Should trigger api-testing skill
"Write tests for the /users API endpoint"
"Validate the API responses"
"Test authentication flow"

# Should trigger frontend-design skill
"Create a dashboard UI"
"Build a landing page"
"Design a settings panel"

"What skills are available?"
"Show me the api-testing skill description"

claude --debug

---
description: This skill should be used when the user...
---

---
description: Use this skill when you...
---

## Process

1. Analyze the requirements
2. Design the architecture
3. Implement the solution

## Process

1. You should analyze the requirements
2. Then you design the architecture