skill-builder

# Skill Builder

A conversational meta-skill that helps you create new Agent Skills for Claude Code through guided interaction.

## Core Purpose

Guide users through creating well-structured, discoverable Agent Skills by:
1. Understanding the skill's purpose and use cases
2. Crafting effective descriptions for model invocation
3. Determining the right structure (instruction-based vs script-powered)
4. Creating all necessary files with best practices
5. Iteratively refining based on user feedback

## When This Skill Activates

- User runs `/new-skill` command
- User asks about creating, building, or designing a new skill
- User wants to build custom Claude Code capabilities
- User needs help with skill structure or organization

## Official Documentation

**If you need clarification on skill features, YAML fields, or best practices**, fetch the official documentation:

- **Primary reference**: https://docs.claude.com/en/docs/claude-code/skills.md

Use the WebFetch tool to get the latest information when:
- Unsure about YAML frontmatter fields
- Need clarification on allowed-tools behavior
- Want to verify skill structure requirements
- Need examples from official docs

## Complete User Journey

### Step 1: Initial Understanding
**Ask clarifying questions to understand the user's needs:**

```markdown
I'll help you create the **[skill-name]** skill. Let me ask a few questions to design it well:

1. **What should this skill do?**
   - What specific capability or expertise are you adding?
   - What problem does it solve?

2. **When should Claude use this skill?**
   - What keywords or scenarios should trigger it?
   - What types of user requests should activate it?

3. **Scope:**
   - Personal skill (just for you: ~/.claude/skills/)
   - Project skill (shared with team: .claude/skills/)
```

**Important:** Listen carefully to the user's responses. Their context might reveal:
- Whether they need scripts or just instructions
- Dependencies they'll need
- Tool restrictions that make sense
- Supporting files that would help

### Step 2: Description Crafting
**Work with the user to create an effective description (max 1024 characters):**

The description is THE MOST CRITICAL part of a skill. It must include:
- **What the skill does** (capabilities)
- **When to use it** (trigger keywords, scenarios, file types)
- **Dependencies** (if any packages are required)

**Good description pattern:**
```
[Action verbs describing capabilities]. Use when [trigger scenarios, keywords, file types]. [Optional: Requires X packages/tools].
```

**Example (good):**
```
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. Requires pypdf and pdfplumber packages.
```

**Example (bad - too vague):**
```
Helps with documents
```

**Present the description to the user and ask:**
```markdown
Here's the description I've crafted:

"[description]"

Does this accurately capture when Claude should use this skill? Any adjustments?
```

### Step 3: Structure Determination
**Determine what files are needed:**

**Ask the user:**
```markdown
Now let's determine the structure:

**Does this skill need custom scripts/tooling?**
- Python scripts for data processing, API calls, custom logic
- Bash scripts for system operations
- Templates for file generation
- Reference documentation

Or is it primarily instruction-based (teaching Claude how to do something)?
```

**Based on response, plan the structure:**

**Instruction-based skill (simple):**
```
skill-name/
└── SKILL.md
```

**Script-powered skill:**
```
skill-name/
├── SKILL.md
└── scripts/
    └── [script-name].py
```

**Comprehensive skill:**
```
skill-name/
├── SKILL.md
├── REFERENCE.md
└── scripts/
    └── [script-name].py
```

### Step 4: Tool Restrictions (Optional)
**Ask if the skill should restrict tools:**

```markdown
**Should this skill restrict which tools Claude can use?**

Common patterns:
- **Read-only** (Read, Grep, Glob) - for analysis/review skills
- **File operations** (Read, Write, Edit, Glob, Grep) - for documentation
- **No restrictions** - Claude asks permission as normal

This uses the `allowed-tools` frontmatter field.
```

If user wants restrictions, add to SKILL.md frontmatter:
```yaml
allowed-tools: Read, Grep, Glob
```

### Step 5: Create the Skill
**Now create all the files:**

**5.1 - Determine the full path based on scope:**
- Personal: `~/.claude/skills/[skill-name]/`
- Project: `[repo-root]/.claude/skills/[skill-name]/`

For personal-os repo, project skills go in: `[repo-root]/skills/[skill-name]/`

**5.2 - Create SKILL.md with proper structure:**

```yaml
---
name: [skill-name]
description: [crafted description]
[optional: allowed-tools: Tool1, Tool2]
---

# [Skill Title]

[Brief overview of what this skill does]

## Requirements
[If scripts/dependencies needed]
```bash
pip install package1 package2
```

## Instructions

[Step-by-step instructions for Claude on how to use this skill]

1. [First step]
2. [Second step]
3. [etc.]

## Examples

[Concrete examples of using this skill]

**Example 1:**
[Show a usage example]

**Example 2:**
[Show another example]
```

**5.3 - Create scripts if needed:**

If the user wants Python scripts, create self-contained scripts that use `uv` for dependency management.

**IMPORTANT: Python scripts must be self-contained and runnable via `uv run`**

```python
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "package-name>=1.0.0",
# ]
# ///
"""
[Script purpose]

Usage:
    uv run scripts/[name].py [arguments]

Description:
    [What this script does]

Dependencies are managed via inline metadata (PEP 723).
uv will automatically install dependencies when the script runs.
"""

import argparse
import sys
from pathlib import Path


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(description="[purpose]")
    parser.add_argument("input", help="