skill-creator

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks - they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

```

skill-name/

├── SKILL.md (required)

│ ├── YAML frontmatter metadata (required)

│ │ ├── name: (required)

│ │ └── description: (required)

│ └── Markdown instructions (required)

└── Bundled Resources (optional)

├── scripts/ - Executable code (Python/Bash/etc.)

├── references/ - Documentation loaded into context as needed

└── assets/ - Files used in output (templates, icons, fonts)

```

---

Scripts (`scripts/`)

Executable code for tasks requiring deterministic reliability or repeated execution.

• When to include: Same code rewritten repeatedly, or deterministic reliability needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may execute without loading into context

References (`references/`)

Documentation and reference material loaded as needed into context.

• When to include: Documentation Claude should reference while working
• Examples: Database schemas, API docs, domain knowledge, company policies
• Best practice: If >10k words, include grep search patterns in SKILL.md
• Avoid duplication: Information lives in SKILL.md OR references, not both

Assets (`assets/`)

Files used within output Claude produces (not loaded into context).

• When to include: Files needed in final output
• Examples: Templates, images, icons, boilerplate code, fonts
• Benefits: Separates output resources from documentation

---

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited*)

*Unlimited because scripts can execute without reading into context.

---

Follow these steps in order, skipping only if clearly not applicable.

Step 1: Understand the Skill with Concrete Examples

Goal: Clearly understand how the skill will be used.

Ask questions like:

• "What functionality should this skill support?"
• "Can you give examples of how this skill would be used?"
• "What would a user say that should trigger this skill?"

Conclude when: You have a clear sense of the functionality the skill should support.

Step 2: Plan the Reusable Skill Contents

Goal: Identify what scripts, references, and assets would be helpful.

For each example use case:

1. Consider how to execute it from scratch
2. Identify what would be helpful when executing repeatedly

Example analysis:

| Skill | Use Case | Reusable Resource |

|-------|----------|-------------------|

| pdf-editor | "Rotate this PDF" | scripts/rotate_pdf.py |

| frontend-builder | "Build me a todo app" | assets/hello-world/ template |

| big-query | "How many users logged in?" | references/schema.md documentation |

Conclude with: A list of reusable resources to include (scripts, references, assets).

Step 3: Initialize the Skill

Run the initialization script to create the skill structure:

```bash

scripts/init_skill.py --path

```

The script creates:

• Skill directory at specified path
• SKILL.md template with proper frontmatter and TODO placeholders
• Example resource directories: scripts/, references/, assets/
• Example files that can be customized or deleted

Skip this step if: Updating an existing skill (proceed to Step 4).

Step 4: Edit the Skill

Remember: The skill is for another Claude instance to use. Include information that would be beneficial and non-obvious.

#### Start with Reusable Contents

1. Create the identified scripts, references, and assets
2. Delete example files/directories not needed
3. Request user input if needed (e.g., brand assets, documentation)

#### Update SKILL.md

Writing Style: Use imperative/infinitive form (verb-first instructions), not second person.

• ✅ "To accomplish X, do Y"
• ❌ "You should do X"

Answer these questions:

1. What is the purpose of the skill? (few sentences)
2. When should the skill be used?
3. How should Claude use the skill? (reference all bundled resources)

Metadata Quality: The name and description in YAML frontmatter determine when Claude uses the skill. Be specific about what the skill does and when to use it. Use third-person:

• ✅ "This skill should be used when..."
• ❌ "Use this skill when..."

Step 5: Package the Skill

Package into a distributable zip file:

```bash

scripts/package_skill.py

```

Optional output directory:

```bash

scripts/package_skill.py ./dist

```

The script will:

1. Validate - Check YAML frontmatter, naming conventions, structure
2. Package - Create zip file with proper directory structure

If validation fails, fix errors and run again.

Step 6: Iterate

After testing the skill:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or resources should be updated
4. Implement changes and test again

---

```markdown

---

name: skill-name

description: Brief description of what this skill does and when to use it. Use third-person (e.g., "This skill should be used when..."). Be specific about triggers and use cases.

---

# Skill Name

[One paragraph explaining the skill's purpose and core philosophy]

[What this skill accomplishes]

• [Trigger 1]
• [Trigger 2]
• [Trigger 3]

Not for: [What this skill should NOT be used for]

---

Step 1: [First Step]

[Instructions]

Step 2: [Second Step]

[Instructions]

[Continue as needed]

---

• scripts/[name].py - [What it does]
• references/[name].md - [What it contains]
• assets/[name]/ - [What it includes]

---

• skill-name - [How it relates]

---

[Brief closing note or key reminder]

```

---

SKILL.md Guidelines

• Keep it focused: One clear purpose per skill
• Be specific about triggers: When should this skill activate?
• Use imperative voice: "To do X, do Y" not "You should do X"
• Reference all resources: Explain how to use bundled scripts/references/assets
• Include examples: Show expected inputs and outputs
• Add quality checks: Checklists for validating output

Frontmatter Best Practices

• name: Lowercase, hyphenated (e.g., anti-ai-writing)
• description: 1-3 sentences, third-person, specific triggers

- ✅ "This skill transforms raw transcripts into polished documents. Use when processing podcast or interview recordings."

- ❌ "A transcript processing skill"

Resource Organization

• scripts/: Executable code only, no documentation
• references/: Documentation only, loaded as needed
• assets/: Output resources only, never loaded into context

Context Management

• Keep SKILL.md under 5k words
• Move detailed reference material to references/
• Include grep patterns for large reference files
• Avoid duplication between SKILL.md and references

---

Workflow Skills

```markdown

Phase 1: [Name]

Goal: [What this phase accomplishes]

#### Step 1: [Action]

[Instructions]

#### Step 2: [Action]

[Instructions]

Phase 2: [Name]

[Continue...]

```

Reference Skills (Knowledge Base)

```markdown

[Concept 1]

[Explanation]

[Concept 2]

[Explanation]

[Guidance on when to use this knowledge]

```

Tool Integration Skills

```markdown

[Prerequisites and installation]

[Command/Function 1]

```bash

[Example command]

```

[Explanation]

[Command/Function 2]

[Continue...]

```

---

This skill includes helper scripts:

• scripts/init_skill.py - Initialize new skill with template structure
• scripts/package_skill.py - Validate and package skill for distribution
• scripts/quick_validate.py - Quick validation check

Usage

```bash

# Initialize new skill

./scripts/init_skill.py my-new-skill --path ./skills/

# Package for distribution

./scripts/package_skill.py ./skills/my-new-skill

# Quick validation

./scripts/quick_validate.py ./skills/my-new-skill

```

---

• voice-analyzer - Create voice style skills
• anti-ai-writing - Example of a well-structured skill

---

Skills are modular, self-contained, and focused. One clear purpose, specific triggers, and all resources referenced in SKILL.md.