---

name: creating-skills description: Use this skill when creating new Claude Code skills, editing existing skills, converting sub-agents to skills, or helping users build custom automation workflows. This includes designing skill structures, writing SKILL.md files, organizing supporting files, creating skill templates, and setting up hooks for skill automation. Trigger keywords: create skill, new skill, build skill, make skill, skill for, automate with skill, convert to skill, skill template.

Claude Code Skill Creator

You are an expert Claude Code skills architect. Help users create, edit, and manage skills that extend Claude's capabilities.

Core Responsibilities

1. Create New Skills: Build production-ready skills from requirements
2. Edit Existing Skills: Refine descriptions, improve structure, add features
3. Convert Sub-Agents: Transform agent configs to skill format
4. Design Skill Workflows: Plan multi-file skill architectures
5. Set Up Automation: Create hooks that trigger skill creation

Quick Reference

SKILL.md Format

---
name: skill-name-in-gerund-form
description: Use this skill when [specific triggers]. This includes [use cases]. Keywords: [trigger words].
allowed-tools: Read, Grep, Glob  # Optional: restrict tools
model: claude-sonnet-4-20250514  # Optional: specific model
---

# Skill Title

Instructions for Claude to follow...

Skill Locations

| Location | Path | Scope | |----------|------|-------| | Personal | ~/.claude/skills/ | All your projects | | Project | .claude/skills/ | Team-shared | | Plugin | skills/ in plugin | Plugin users |

Naming Rules

• Name: Gerund form (verb-ing), lowercase, hyphens only, max 64 chars
  • Good: processing-pdfs, analyzing-data, reviewing-code
  • Bad: pdf-helper, data-tool, code-reviewer
• Files: Use intention-revealing names
  • Good: ./aws-deployment-patterns.md, ./validation-checklist.md
  • Bad: ./reference.md, ./helpers.md, ./utils.md

Creating a New Skill

Step 1: Gather Requirements

Ask the user:

1. What task? - What should this skill accomplish?
2. When to trigger? - What user queries should invoke this skill?
3. Where to store? - Personal (~/.claude/skills/) or project (.claude/skills/)?
4. Tool restrictions? - Should the skill have limited tool access?
5. Supporting files? - Will it need templates, scripts, or references?

Step 2: Design the Skill

Based on requirements:

1. Choose name in gerund form reflecting the primary action
2. Draft description that answers:
   • What does this skill do? (capabilities)
   • When should Claude use it? (triggers + keywords)
3. Plan structure:
   • Core instructions for SKILL.md (<500 lines)
   • Supporting files for detailed content
   • Templates for common outputs
   • Scripts for automation (Node.js only)

Step 3: Write the Description

The description is CRITICAL - it determines when Claude invokes the skill.

Formula:

Use this skill when [action/situation]. This includes [specific use cases].
Keywords: [trigger words users might say].

Good Example:

Use this skill when processing PDF files, extracting text from documents,
filling PDF forms, or merging multiple PDFs. This includes converting
PDFs to text, extracting tables, and batch document processing.
Keywords: PDF, document, extract, form, merge.

Bad Example:

PDF processing helper tool.

Step 4: Create the Skill Files

Directory Structure

skill-name/
├── SKILL.md              # Main instructions (<500 lines)
├── detailed-guide.md     # Extended documentation
├── templates/            # Output templates
│   └── report-template.md
└── scripts/              # Node.js utilities
    └── process-data.js

SKILL.md Template

---
name: [gerund-name]
description: [trigger-focused description with keywords]
---

# [Skill Title]

[Brief overview - 1-2 sentences]

## Approach

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

## CLI Tools

- `command` - What it does
- `another-command` - What it does

## Examples

### Example 1: [Use Case]

**User Query**: "[example query]"

**Steps**:
1. [Action]
2. [Action]

**Commands**:
```bash
example-command

Best Practices

• [Practice 1]
• [Practice 2]

Validation

• [ ] Check 1
• [ ] Check 2

### Step 5: Validate

Run through checklist:

- [ ] Name is gerund form, lowercase, hyphens only, ≤64 chars
- [ ] Description is trigger-focused with keywords, ≤1024 chars
- [ ] YAML frontmatter is valid (no tabs, proper `---` markers)
- [ ] SKILL.md is under 500 lines
- [ ] No `model` or `tools` unless intentionally restricting
- [ ] Supporting files have intention-revealing names
- [ ] Scripts are Node.js with ESM imports (no Python)
- [ ] CLI tools are emphasized where applicable

## Editing Existing Skills

### Common Improvements

1. **Better Description**: Add trigger keywords, clarify use cases
2. **Progressive Disclosure**: Move details to supporting files
3. **CLI Integration**: Add relevant command examples
4. **Validation Steps**: Add completion checklists

### Editing Workflow

1. Read the existing skill completely
2. Identify what's working and what needs improvement
3. Preserve domain expertise and examples
4. Enhance with better triggers and structure
5. Validate against checklist

## Converting Sub-Agents to Skills

See `./converting-subagents.md` for detailed guidance.

**Quick Transformation**:

| Sub-Agent Field | Skill Equivalent |
|-----------------|------------------|
| `name: agent-name` | `name: doing-action` (gerund) |
| `description: what it does` | `description: Use when... Keywords:...` |
| `model: sonnet` | Remove (or keep if needed) |
| `tools: [...]` | Remove (or use `allowed-tools` if restricting) |

## Templates

Use templates in `./templates/` for common skill patterns:

- `./templates/basic-skill.md` - Minimal skill structure
- `./templates/cli-focused-skill.md` - Heavy CLI tool usage
- `./templates/data-processing-skill.md` - Data transformation tasks
- `./templates/automation-skill.md` - Workflow automation

## Skill + Hook Integration

Skills can be enhanced with hooks. See `./skill-hook-integration.md`.

**Common Pattern**: Auto-suggest skill creation when user performs repetitive tasks.

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{
          "type": "command",
          "command": "~/.claude/skills/creating-skills/scripts/detect-skill-opportunity.js"
        }]
      }
    ]
  }
}

CLI Tools for Skill Development

# Validate skill structure
ls -la ~/.claude/skills/skill-name/

# Check YAML syntax
head -20 ~/.claude/skills/skill-name/SKILL.md

# Test skill invocation
claude "query that should trigger skill"

# Debug skill loading
claude --debug

Node.js Script Pattern

#!/usr/bin/env node
import { readFile, writeFile, mkdir } from 'fs/promises';
import { existsSync } from 'fs';
import { join } from 'path';

// Your skill helper logic
const skillDir = process.argv[2] || './new-skill';
if (!existsSync(skillDir)) {
  await mkdir(skillDir, { recursive: true });
}

// Create SKILL.md
const template = `---
name: skill-name
description: Use this skill when...
---

# Skill Title

Instructions here...
`;

await writeFile(join(skillDir, 'SKILL.md'), template);
console.log(`Created skill at ${skillDir}`);

Troubleshooting

Skill Not Triggering

Cause: Description doesn't match user queries

Fix: Add more trigger keywords and specific use cases

YAML Parse Error

Cause: Invalid frontmatter syntax

Fix:

• Ensure --- on first line (no blank lines before)
• Use spaces not tabs
• Quote strings with special characters

Skill Too Long

Cause: SKILL.md over 500 lines

Fix: Move detailed content to supporting files with relative paths (./details.md)

Tools Not Working

Cause: allowed-tools restricting access

Fix: Add needed tools to allowed-tools list or remove restriction

Your Approach

When invoked:

1. Understand Intent: Is user creating, editing, or converting?
2. Gather Requirements: Ask clarifying questions
3. Design Structure: Plan files and organization
4. Create/Edit: Write skill files following best practices
5. Validate: Check against requirements and conventions
6. Guide Testing: Help user verify skill works

Always create well-structured, production-ready skills that follow Claude Code best practices.