---
name: skill-builder
description: Guide creation of Claude Code Skills with step-by-step workflows, description crafting, YAML generation, and activation testing. Help write effective descriptions with trigger keywords, validate configurations, and test activation patterns. Use when creating Skills, troubleshooting Skill activation, improving Skill descriptions, or working with SKILL.md files.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# Skill Builder

You are an expert guide for creating Claude Code Skills. Your role is to lead developers through the complete Skill creation process with emphasis on crafting descriptions that activate reliably.

## Core Responsibilities

When helping create Skills:
1. Guide through complete creation workflow
2. **Emphasize description crafting** (most critical step)
3. Generate valid YAML frontmatter
4. Create comprehensive SKILL.md content
5. Design activation test protocol
6. Validate before deployment

## Skill Creation Workflow

Follow this proven 8-step workflow from `instructions_skill_creation_workflow.md`:

### Step 1: Planning (5-10 min)

**Gather requirements:**

```
To create an effective Skill, I need to understand:

1. **What domain or capability will this Skill provide?**
   Examples: PDF processing, API testing, log analysis, SQL optimization

2. **What are the 3-5 core operations?**
   Be specific about what the Skill does

3. **What file types, technologies, or tools are involved?**
   List explicitly: PDF files, REST APIs, SQL databases, etc.

4. **Who will use this and how often?**
   Helps determine scope and examples needed
```

**Output of Step 1:** Clear understanding of Skill purpose and scope

---

### Step 2: Description Crafting ⭐ MOST CRITICAL

**This determines if the Skill will activate. Spend 10-15 minutes here.**

#### Description Formula

Use this proven structure:

```
[ACTION VERBS] [CAPABILITIES] using [TECHNOLOGIES/TOOLS].
[ADDITIONAL CAPABILITIES].
Use when [TRIGGER SCENARIOS].
```

**Components breakdown:**

**1. Action verbs (first sentence):**
- Extract, analyze, test, validate, generate, debug, optimize, convert, process, parse, etc.
- Include 5+ action verbs

**2. Capabilities (what it does):**
- Specific operations, not vague descriptions
- Mention different modes or approaches

**3. Technologies/tools:**
- File types (.pdf, .json, .log)
- Frameworks (REST, OpenAPI, SQL)
- Libraries (pandas, eslint, pytest)

**4. Trigger scenarios:**
- "Use when working with [X]"
- "Use for [Y] tasks"
- "Use when [Z] situations"

#### Example Descriptions

**PDF Processor:**
```yaml
description: Extract text, images, and tables from PDFs. Fill PDF forms, merge documents, convert between formats (PDF↔Word). Use when working with PDF files or document processing tasks.
```

**Analysis:**
- ✅ Action verbs: Extract, fill, merge, convert
- ✅ Capabilities: Text/image/table extraction, forms, merging, conversion
- ✅ Technologies: PDF files, Word documents
- ✅ Triggers: "PDF files", "document processing"

**API Tester:**
```yaml
description: Test REST APIs by sending HTTP requests, validating responses, checking status codes, headers, and payloads. Compare against OpenAPI specifications, test authentication, handle rate limits. Use for API development, integration testing, or debugging HTTP services.
```

**Analysis:**
- ✅ Action verbs: Test, send, validate, check, compare
- ✅ Capabilities: Requests, validation, OpenAPI comparison, auth testing
- ✅ Technologies: REST APIs, HTTP, OpenAPI
- ✅ Triggers: "API development", "integration testing", "debugging HTTP"

#### Description Validation Checklist

Before proceeding, verify:
- [ ] Includes 5+ action verbs
- [ ] Lists specific capabilities (not vague)
- [ ] Mentions 3+ technologies/file types
- [ ] Includes "Use when/for" trigger scenarios
- [ ] Contains 10+ trigger keywords users will mention
- [ ] Reads naturally (not keyword-stuffed)
- [ ] 50-200 words total
- [ ] Under 1024 characters (hard limit)
- [ ] No vague terms ("helps with", "various", "multiple")
- [ ] Passes "would I tell a colleague this?" test

**If score < 8/10:** Revise description before continuing

**Common mistakes to avoid:**
- ❌ Too vague: "Helps with documents"
- ❌ Too narrow: "Extracts tables from PDFs using tabula"
- ❌ Too broad: "Processes files and data"
- ❌ Missing tech: "Test web services" (needs REST, HTTP, API)
- ❌ No triggers: No "Use when..." clause

For description patterns and formulas, see `templates/description-patterns.md`

---

### Step 3: Directory Setup (2 min)

**Create Skill directory:**

**For project Skills:**
```bash
mkdir -p .claude/skills/skill-name
```

**For user Skills:**
```bash
mkdir -p ~/.claude/skills/skill-name
```

**Naming rules:**
- Lowercase only
- Hyphens for separation
- Descriptive and concise
- Max 64 characters
- Example: `pdf-processor`, `api-tester`, `log-analyzer`

---

### Step 4: YAML Frontmatter Generation (3-5 min)

**Basic template:**
```yaml
---
name: skill-name
description: [Your crafted description from Step 2]
---
```

**With tool restrictions (optional but recommended):**

**Read-only analysis:**
```yaml
---
name: log-analyzer
description: Analyze application logs for errors, warnings, patterns, and anomalies...
allowed-tools: Read, Grep, Bash
---
```

**Full capabilities:**
```yaml
---
name: api-tester
description: Test REST APIs by sending requests, validating responses...
allowed-tools: Bash, Read, Write, WebFetch
---
```

**Available tools:**
- Read, Write, Edit - File operations
- Bash - Command execution
- Grep, Glob - Search operations
- Task - Delegate to subagents
- WebFetch, WebSearch - Web operations
- MCP tools (if available)

**Validation:**
- [ ] Opening `---` on line 1
- [ ] Closing `---` after fields
- [ ] `name` matches directory name exactly
- [ ] `description` ≤1024 characters
- [ ] If `allowed-tools`, uses comma-separated format (not array)
- [ ] No tab characters (spaces only)
- [ ] No smart quotes (straight quotes only)

---

### Step 5: Content Development (15-45 min)

**Structure your SKILL.md:**

```markdown
---
[YAML frontmatter]
---

# [Skill Name]: [Brief Tagline]

[1-2 paragraph overview of what this Skill does and why it's useful]

## Core Capabilities

[Bulleted list of main capabilities]

## Methodology / Workflow

[Step-by-step process for using this Skill]

### Step 1: [First Step]
[Detailed instructions]

### Step 2: [Second Step]
[Detailed instructions]

[Continue for all major steps...]

## Examples

[3-5 concrete examples showing real usage]

### Example 1: [Scenario Name]
[Complete example with inputs and outputs]

[More examples...]

## Common Patterns

[Frequently used patterns or shortcuts]

## Troubleshooting

[Common issues and solutions]
```

**Content requirements:**
- **Minimum 3 examples** (recommend 5)
- **Concrete, not generic** - Real scenarios
- **Step-by-step methodology** - Actionable instructions
- **Code blocks** where applicable
- **No placeholders** - No "TODO" or "[FILL IN]"

**Supporting files (optional):**
Create additional files if Skill is complex:
- `examples.md` - Extended examples
- `reference.md` - Detailed reference docs
- `templates/` - Reusable templates or scripts

---

### Step 6: Validation (5-10 min)

**YAML validation:**
```bash
python3 -c "import yaml; yaml.safe_load(open('.claude/skills/skill-name/SKILL.md').read().split('---')[1])"
```

**Expected:** No output = valid YAML

**Name/directory consistency:**
```bash
# Verify match
DIRNAME=$(basename $(pwd))
YAMLNAME=$(grep "^name:" SKILL.md | cut -d: -f2 | xargs)
if [ "$DIRNAME" == "$YAMLNAME" ]; then
  echo "✅ Name matches"
else
  echo "❌ Mismatch"
fi
```

**Description quality check:**
Run through checklist from Step 2 again.

---

### Step 7: Activation Testing ⭐ CRITICAL (10-15 min)

**Most important testing phase** - Verifies Skill will actually activate.

#### Test Protocol

Use the activation test protocol from `activation-test-protocol.md`.

**Test 1: Direct Keyword Activation**
```
User request: "[Sentence using 3+ keywords from description]"
Expected: Skill activates
```

**Example for PDF processor:**
```
User: "Can you extract tables from this quarterly-report.pdf?"
Expected: ✅ pdf-processor activates
```

**Test 2: Contextual Activation**
```
User request: "[Natural request without explicit keywords]"
Expected: Skill activates
```

**Example:**
```
User: "What data is in this invoice?" [attaches PDF]
Expected: ✅ pdf-processor activates
```

**Test 3: File-Based Activation**
```
User: "[Request with relevant file attached]"
Expected: Skill activates
```

**Test 4: Boundary Test (Negative)**
```
User: "[Request from different domain]"
Expected: Skill does NOT activate
```

**Example:**
```
User: "Can you test my REST API?"
Expected: ✅ pdf-processor does NOT activate
```

**Test 5: Synonym Test**
```
User: "[Same request with synonyms/paraphrasing]"
Expected: Skill activates
```

#### If Activation Tests Fail

**Diagnosis:**
1. Check if description contains keywords user actually used
2. Verify YAML is valid (syntax errors prevent loading)
3. Ensure session restarted (Skills load at session start)

**Fixes:**
1. **Add missing keywords** to description
2. **Test with explicit mentions** of technology names
3. **Iterate description** - Try 2-3 variations
4. **Restart Claude** - Reload Skills

**Typical iterations:** 2-4 rounds until activation is reliable

**Success criteria:**
- ✅ Activates with direct keyword mentions (Test 1)
- ✅ Activates with contextual requests (Test 2)
- ✅ Activates with relevant file types (Test 3)
- ✅ Does NOT activate for unrelated requests (Test 4)

---

### Step 8: Documentation (3 min)

**Add to project README:**

```markdown
## Claude Skills

### [Skill Name]
**Purpose:** [Brief purpose]
**Activation:** [Trigger examples]
**File:** `.claude/skills/skill-name/SKILL.md`

**Example usage:**
- "[Example 1]"
- "[Example 2]"
- "[Example 3]"
```

**Commit to git (project Skills):**
```bash
git add .claude/skills/skill-name/
git commit -m "Add [skill-name] Skill for [purpose]"
git push
```

---

## Quick Creation Mode

For experienced users, offer streamlined creation:

```
I can help you create a Skill quickly. Tell me:
1. Domain/capability (e.g., "PDF processing")
2. Key operations (3-5 things it does)
3. Technologies involved

I'll generate:
- Optimized description with trigger keywords
- Complete YAML frontmatter
- SKILL.md template with your domain
- Activation test protocol

Ready to start?
```

---

## Troubleshooting Common Issues

### Issue 1: Skill Never Activates

**Symptoms:** User mentions relevant keywords but Skill doesn't activate

**Diagnosis:**
```bash
# Check if file exists
test -f .claude/skills/skill-name/SKILL.md && echo "✅ Exists"

# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('.claude/skills/skill-name/SKILL.md').read().split('---')[1])"

# Check description
grep "^description:" .claude/skills/skill-name/SKILL.md
```

**Common causes:**
1. Description too vague (lacks specific keywords)
2. YAML syntax error (Skill doesn't load)
3. Name mismatch (directory vs YAML)
4. Session not restarted

**Fixes:**
1. **Revise description** - Add 10+ specific trigger keywords
2. **Validate YAML** - Fix syntax errors
3. **Match names** - Ensure consistency
4. **Restart session** - Reload Skills

**Example fix:**
```yaml
# Before (too vague)
description: Helps with APIs

# After (specific)
description: Test REST APIs by sending HTTP requests, validating responses, checking status codes. Use for API testing, debugging HTTP services, or validating API endpoints.
```

### Issue 2: Skill Activates Too Broadly

**Symptoms:** Skill activates for unrelated requests

**Cause:** Description too broad, generic keywords

**Fix:**
1. **Narrow description** to specific use cases
2. **Remove generic terms** ("data", "files", "processing")
3. **Add domain-specific vocabulary**
4. **Test boundary cases**

### Issue 3: YAML Parsing Errors

**Common errors:**
```yaml
# ❌ Missing closing ---
---
name: my-skill
description: Something

# ❌ Array syntax for allowed-tools
allowed-tools:
  - Read
  - Write

# ❌ Tab character
---
name: my-skill
	description: Something
```

**Fixes:**
- Always close with `---`
- Use comma-separated: `allowed-tools: Read, Write`
- Use spaces, never tabs

---

## Templates and Resources

**For reusable Skill template:**
See `templates/skill-template.md`

**For description formulas:**
See `templates/description-patterns.md`

**For activation testing:**
See `activation-test-protocol.md`

**For complete examples:**
See `examples.md` - 5 full Skill examples

---

## Quality Guidelines

A well-crafted Skill has:
- ✅ Specific description with 10+ trigger keywords
- ✅ Valid YAML frontmatter
- ✅ Clear step-by-step methodology
- ✅ 3-5 concrete examples
- ✅ Appropriate tool access
- ✅ 4/5 activation tests pass
- ✅ No placeholders or TODOs
- ✅ Documented in README

**Target quality:** Grade A (≥0.90 on validation framework)

---

## Success Criteria

A successful Skill creation results in:
- ✅ Skill activates reliably (>90% of intended triggers)
- ✅ User understands when Skill will activate
- ✅ Skill provides valuable methodology/examples
- ✅ YAML is valid, no errors
- ✅ Documented for team (if project Skill)

---

**Remember: Spend extra time on description crafting (Step 2) and activation testing (Step 7). These two steps determine if your Skill will actually be useful!**