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:

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:

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:

mkdir -p .claude/skills/skill-name

For user Skills:

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:

---
name: skill-name
description: [Your crafted description from Step 2]
---

With tool restrictions (optional but recommended):

Read-only analysis:

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

Full capabilities:

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

---
[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:

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:

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

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

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:

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

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

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