---

description: Create a new Claude Code skill from a description argument-hint: <skill-name> "<description/purpose>" [doc-url...]

Create New Skill

You will create a new skill for Claude Code based on the provided name, description, and optional documentation URLs.

Arguments: $ARGUMENTS

Important:

• First argument: skill name (kebab-case)
• Second argument: description/purpose (in quotes)
• Remaining arguments (optional): documentation URLs to analyze

Your Task

Follow these steps to create the skill:

Step 1: Parse Arguments

Extract from $ARGUMENTS:

• Skill Name: The first argument (kebab-case identifier, e.g., pdf-processor)
• Description/Purpose: The second argument (in quotes) describing what the skill does
• Documentation URLs: Any remaining arguments (optional)

Examples:

• /create-skill pdf-processor "Extract text and tables from PDF files"
• /create-skill temporal-workflow "Build durable workflows" https://docs.temporal.io https://typescript.temporal.io

Step 2: Gather Context

If documentation URLs were provided: Launch technical-researcher agents in parallel (one per URL) to analyze the documentation. Each researcher should investigate:

• Key concepts, APIs, and patterns relevant to the skill's purpose
• Best practices and conventions
• Common workflows and use cases
• Important implementation details
• Configuration examples and templates that should be bundled

IMPORTANT: Do NOT use WebFetch directly. Always use the technical-researcher agent to ensure comprehensive analysis and proper extraction of reusable content.

If NO documentation URLs were provided: Use the AskUserQuestion tool to gather more information. Ask about:

• What specific problem does this skill solve?
• Are there documentation URLs or references to analyze?
• What tools will the skill need access to? (Read-only? Bash access?)
• What are the key workflows and steps?
• What trigger keywords should activate this skill?

Adapt questions based on the description provided - skip questions that are already answered.

Step 3: Copy Skeleton Template

Copy the skeleton template from templates/skill-skeleton/ to .claude/skills/<skill-name>/:

• This provides the base directory structure
• You'll customize the placeholders based on gathered context

Step 4: Generate SKILL.md

Create the main skill file with proper YAML frontmatter:

---
name: skill-name-here
description: Clear description of what it does AND when to use it
allowed-tools: Tool1, Tool2  # Only if restrictions needed
---

Required sections in SKILL.md:

• ⚠️ BEFORE YOU START: Metrics table (setup time, error count, token usage) and numbered list of prevented issues
• Quick Start: 3 steps with code examples and "Why this matters" explanations
• Critical Rules: ✅ Always Do and ❌ Never Do with visual indicators, plus Common Mistakes (wrong vs correct code)
• Known Issues Prevention: Table with Issue, Root Cause, Solution columns
• Configuration Reference: Example configs with key settings explained
• Common Patterns: Code examples for typical usage
• Bundled Resources: Linked scripts/, references/, templates/ contents (if created)
• Dependencies: Required and optional packages with versions
• Troubleshooting: Problem/symptom/solution pairs
• Setup Checklist: Verification items before using

Step 5: Generate README.md (REQUIRED)

Always include README.md with discovery-focused content:

Required sections:

• Metadata table: Status, Version, Last Updated, Confidence (X/5), Production Tested URL
• What This Skill Does: Core capabilities list
• Auto-Trigger Keywords: Primary, Secondary, and Error-based keywords
• Known Issues Prevention: Table format
• When to Use: "Use for" and "Don't use for" lists
• Quick Usage: Single code example
• Token Efficiency: Table comparing manual vs skill-assisted approach
• File Structure: Directory tree
• Dependencies: Package versions with verification dates
• Related Skills: Links to complementary skills

Step 6: Evaluate and Create Optional Directories

Create templates/ when the skill involves:

• Configuration files (wrangler.jsonc, docker-compose.yaml, terraform.tf)
• Starter templates users would copy
• Example project structures

Create scripts/ when the skill has:

• Repeatable validation commands that run locally
• Setup automation (install dependencies, configure tools)
• Diagnostic utilities (API queries, config validation)

Create references/ when:

• Documentation URLs were provided (extract key API patterns, examples)
• Complex reference material should be bundled for offline use

Create assets/ when:

• Static resources are needed (images, diagrams, data files)

For simpler skills: Remove directories that aren't needed. A small skill may only have SKILL.md and README.md.

Step 7: Validate

Before completing, verify:

• [ ] SKILL.md has valid YAML frontmatter
• [ ] Name uses only lowercase letters, numbers, hyphens (max 64 chars)
• [ ] Description includes what AND when with specific trigger keywords
• [ ] allowed-tools is appropriate (or omitted to inherit all)
• [ ] Instructions are clear and actionable
• [ ] README.md exists with auto-trigger keywords
• [ ] Evaluated need for templates/ (config-heavy skills)
• [ ] Evaluated need for scripts/ (automation opportunities)
• [ ] Evaluated need for references/ (if docs URLs provided)
• [ ] Token efficiency documented in README.md
• [ ] Unnecessary skeleton directories removed

Best Practices

Description Writing

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.

Bad:

description: Helps with documents

Tool Restrictions

Use allowed-tools for:

• Read-only skills (Read, Grep, Glob)
• Security-sensitive operations
• Limited-scope workflows

Omit allowed-tools to inherit all tools from main thread.

Output Location

Write all files to .claude/skills/<skill-name>/:

.claude/skills/
└── skill-name/
    ├── SKILL.md        # Required
    ├── README.md       # Required
    ├── templates/      # If config-heavy
    ├── scripts/        # If automation needed
    ├── references/     # If docs URLs provided
    └── assets/         # If static resources needed

Step 8: Report Results

Provide a summary including:

• Path to the newly created skill directory
• Skill name and description
• What the skill does and when Claude should use it
• Auto-trigger keywords (from README.md)
• Tool restrictions (if any)
• What optional directories were created and why
• Suggested test prompts to validate the skill works correctly