Stay Updated!

Get the latest posts and insights delivered directly to your inbox

← Back to Claude Prompts

Create Skill

Instruction Claude
#skill #claude-code #automation #agent

Slash command to generate new Claude Skills with proper structure, YAML frontmatter, and bundled resources

💡 Use Case:
Use when creating reusable skills for workflows, file operations, or specialized tasks that Claude can invoke automatically

Prompt Content

description: Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference argument-hint: [skill-name] [description]

/create-skill

Purpose

Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference

Contract

Inputs:

  • $1 — SKILL_NAME (lowercase, kebab-case, max 64 characters)
  • $2 — DESCRIPTION (what the skill does and when to use it, max 1024 characters)
  • --personal — create in ~/.claude/skills/ (default)
  • --project — create in .claude/skills/

Outputs: STATUS=<CREATED|EXISTS|FAIL> PATH=<path>

Instructions

  1. Validate inputs:

    • Skill name: lowercase letters, numbers, hyphens only (max 64 chars)
    • Description: non-empty, max 1024 characters, no angle brackets (< or >)
    • Description should include both WHAT the skill does and WHEN to use it
    • If user provides additional frontmatter properties, validate against allowed list:
      • Allowed: name, description, license, allowed-tools, metadata
      • Warning (not error) for unexpected properties like version, author, tags
      • Inform user that unexpected properties may cause issues during packaging

  2. Determine target directory:

    • Personal (default): ~/.claude/skills/{{SKILL_NAME}}/
    • Project: .claude/skills/{{SKILL_NAME}}/

  3. Check if skill already exists:

    • If exists: output STATUS=EXISTS PATH=<path> and stop

  4. Analyze what bundled resources this skill needs:

    Based on the skill name and description, intelligently determine which bundled resources would be valuable:

    Create scripts/ directory when:

    • Skill involves file manipulation (PDF, images, documents, etc.)
    • Skill requires deterministic operations (data processing, conversions)
    • Same code would be rewritten repeatedly
    • Examples: pdf-editor, image-processor, data-analyzer, file-converter

    Create references/ directory when:

    • Skill needs reference documentation (API docs, schemas, specifications)
    • Detailed information would make SKILL.md too long (>5k words)
    • Domain knowledge needs to be documented (company policies, standards)
    • Examples: api-client, database-query, brand-guidelines, coding-standards

    Create assets/ directory when:

    • Skill uses templates or boilerplate code
    • Skill needs brand assets (logos, fonts, images)
    • Skill creates documents from templates (presentations, reports)
    • Examples: frontend-builder, brand-guidelines, document-generator, presentation-maker

    Questions to ask user for clarification (only if unclear):

    • “Will this skill need to run any scripts repeatedly?” (→ scripts/)
    • “Does this skill need reference documentation like API docs or schemas?” (→ references/)
    • “Will this skill use templates or assets like logos/fonts/boilerplate?” (→ assets/)

    Communicate the decision: After analysis, inform the user which directories will be created and why:

    • Example: “Based on the description, I’ll create scripts/ for PDF manipulation utilities and references/ for schema documentation.”
    • Be transparent about the reasoning
    • It’s better to include a directory with placeholders than to omit one that might be needed

  5. Create skill directory structure based on analysis:

    Always create:

    {{SKILL_NAME}}/
└── SKILL.md (required)

    Conditionally create based on Step 4 analysis:

    ├── scripts/ (if determined needed)
│   └── example.py (executable placeholder with TODO)
├── references/ (if determined needed)
│   └── README.md (documentation placeholder with guidance)
└── assets/ (if determined needed)
    └── README.md (asset placeholder with examples)

  6. Generate SKILL.md using this template:

    ---
name: { { SKILL_NAME } }
description: { { DESCRIPTION } }
# Optional fields (uncomment if needed):
# allowed-tools: ["Read", "Write", "Bash"]  # Restrict to specific tools
# metadata:
#   category: "development"
#   version: "1.0.0"  # For tracking in your project
# license: "MIT"  # For shared skills
---

# {{Title Case Skill Name}}

## Overview

[TODO: 1-2 sentences explaining what this skill does and why it's valuable]

## When to Use

[TODO: Specific triggers and scenarios where this skill should be invoked]

## Structuring This Skill

Choose an organizational pattern:

**Workflow-Based** (sequential) - TDD workflows, git commits, deployments

- Structure: Overview → Step 1 → Step 2 → Step 3...

**Task-Based** (operations) - File tools, API operations, data transforms

- Structure: Overview → Quick Start → Operation A → Operation B...

**Reference-Based** (guidelines) - Brand standards, coding rules, checklists

- Structure: Overview → Guidelines → Specifications → Examples

**Capabilities-Based** (integrated) - Product management, debugging, systems

- Structure: Overview → Core Capabilities → Feature 1 → Feature 2...

Patterns can be mixed. Delete this section after choosing.

[TODO: Delete this "Structuring This Skill" section after choosing your approach]

## Instructions

[TODO: Provide clear, step-by-step guidance using imperative/infinitive language]

[TODO: Reference any bundled resources (scripts, references, assets) so Claude knows how to use them]

Example structure:

1. First major step
2. Second major step
3. Third major step

## Bundled Resources

[TODO: Document bundled resources. Delete unused subsections.]

**scripts/** - Executable code run directly (not loaded into context)

- Example: `scripts/process_data.py` - Processes CSV and generates reports

**references/** - Documentation loaded into context when needed

- Example: `references/api_docs.md` - API endpoint documentation

**assets/** - Files used in output (not loaded into context)

- Example: `assets/template.pptx` - Presentation template

## Examples

[TODO: Show concrete examples with realistic user requests]

    User: “Help me [specific task]” Claude: [How the skill responds]

    
## Progressive Disclosure

Keep SKILL.md <5k words. Move detailed info to references/. Three-level loading:
1. Metadata (~100 words) - Always in context
2. SKILL.md - Loaded when triggered
3. Bundled resources - Loaded as needed

  7. Create bundled resource placeholders (based on Step 4 analysis):

    For each directory determined in Step 4, create appropriate placeholder files:

    scripts/ → Create scripts/example.py (executable Python template with TODO comment) references/ → Create references/README.md (documentation template explaining purpose) assets/ → Create assets/README.md (asset placeholder explaining common types)

    Make scripts executable: chmod +x scripts/*.py

  8. Follow official guidelines:

    • Name: lowercase, numbers, hyphens only (max 64 chars)
    • Description: Include triggers and use cases (max 1024 chars)
    • Instructions: Clear, step-by-step guidance
    • Keep skills focused on single capabilities
    • Make descriptions specific with trigger keywords

  9. Output:

    • Print: STATUS=CREATED PATH={{full_path}}
    • Summarize what was created and why (list directories + reasoning)
    • Remind user to populate placeholders and complete [TODO] items

Constraints

  • Skills are model-invoked (Claude decides when to use them)
  • Description must be specific enough for Claude to discover when to use it
  • One skill = one capability (stay focused)
  • Use forward slashes in all file paths
  • Valid YAML syntax required in frontmatter

Frontmatter Properties

Required:

  • name - Lowercase hyphen-case identifier (max 64 chars, matches directory name)
  • description - What it does + when to use it (max 1024 chars, no angle brackets)

Optional:

  • allowed-tools: ["Read", "Write", "Bash"] - Restrict Claude to specific tools
  • metadata: {category: "dev", version: "1.0"} - Custom tracking fields
  • license: "MIT" - License for shared skills

Prohibited (causes warnings):

  • version, author, tags - Use metadata or description instead

Examples

Simple workflow skill:

/create-skill commit-helper "Generate clear git commit messages from diffs. Use when writing commits or reviewing staged changes."

Claude will determine: No bundled resources needed - just workflow guidance

File manipulation skill:

/create-skill pdf-processor "Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction."

Claude will determine: Needs scripts/ directory for PDF manipulation utilities

API integration skill:

/create-skill api-client "Make REST API calls and handle responses. Use for API testing and integration work with the company API."

Claude will determine: Needs references/ directory for API documentation and schemas

Image processing skill:

/create-skill image-processor "Resize, rotate, and convert images. Use when editing images or batch processing files."

Claude will determine: Needs scripts/ directory for image manipulation operations

Brand guidelines skill:

/create-skill brand-guidelines "Apply company brand guidelines to designs. Use when creating presentations, documents, or marketing materials."

Claude will determine: Needs references/ for guidelines + assets/ for logos, fonts, templates

Frontend builder skill:

/create-skill frontend-builder "Build responsive web applications with React. Use when creating new frontend projects or components." --project

Claude will determine: Needs scripts/ for build tools + assets/ for boilerplate templates

Database query skill:

/create-skill database-query "Query and analyze database tables. Use when working with SQL, BigQuery, or data analysis tasks." --project

Claude will determine: Needs references/ for schema documentation

How Claude determines what’s needed:

  • Mentions “PDF”, “images”, “documents”, “convert” → scripts/
  • Mentions “API”, “database”, “guidelines”, “standards” → references/
  • Mentions “templates”, “boilerplate”, “brand”, “presentations” → assets/
  • Simple workflow/process skills → SKILL.md only

Adding optional frontmatter properties:

After creating a skill, you can manually edit SKILL.md to add optional frontmatter properties:

---
name: database-query
description: Query and analyze database tables. Use when working with SQL, BigQuery, or data analysis tasks.
allowed-tools: ["Bash", "Read", "Grep"]
metadata:
  category: "data"
  version: "1.0.0"
  team: "analytics"
license: "MIT"
---

Post-Creation Workflow

1. Edit - Complete [TODO] placeholders, populate bundled resources, add concrete examples

2. Test - Restart Claude Code, test with trigger queries matching description

3. Validate - Check frontmatter properties, description clarity, no sensitive data

4. Iterate - Use on real tasks, update based on struggles/feedback

Optional:

  • Package for distribution: Use packaging tools or /create-plugin
  • Share with team: Distribute .zip or via plugin marketplace

Example: Well-Structured Skill

Here’s an example of a production-quality skill to demonstrate best practices:

artifacts-builder - A skill for creating complex React/TypeScript artifacts with shadcn/ui

artifacts-builder/
├── SKILL.md (focused, ~75 lines)
└── scripts/
    ├── init-artifact.sh (323 lines - initializes React+Vite+shadcn project)
    ├── bundle-artifact.sh (54 lines - bundles to single HTML)
    └── shadcn-components.tar.gz (pre-packaged shadcn/ui components)

SKILL.md structure:

---
name: artifacts-builder
description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
license: Complete terms in LICENSE.txt
---

# Artifacts Builder

To build powerful frontend claude.ai artifacts, follow these steps:

1. Initialize the frontend repo using `scripts/init-artifact.sh`
2. Develop your artifact by editing the generated code
3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
4. Display artifact to user
5. (Optional) Test the artifact

**Stack**: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui

## Design & Style Guidelines

VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.

## Quick Start

### Step 1: Initialize Project

Run the initialization script to create a new React project:

```bash
bash scripts/init-artifact.sh <project-name>
cd <project-name>
```

This creates a fully configured project with:

  • ✅ React + TypeScript (via Vite)
  • ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
  • ✅ Path aliases (@/) configured
  • ✅ 40+ shadcn/ui components pre-installed
  • ✅ All Radix UI dependencies included
  • ✅ Parcel configured for bundling
  • ✅ Node 18+ compatibility

Step 2: Develop Your Artifact

To build the artifact, edit the generated files. See Common Development Tasks below for guidance.

Step 3: Bundle to Single HTML File

To bundle the React app into a single HTML artifact:

bash scripts/bundle-artifact.sh

This creates bundle.html - a self-contained artifact with all JavaScript, CSS, and dependencies inlined.

Step 4: Share Artifact with User

Finally, share the bundled HTML file in conversation with the user so they can view it as an artifact.

Step 5: Testing/Visualizing the Artifact (Optional)

Note: This is a completely optional step. Only perform if necessary or requested.

Reference


**What makes this skill excellent:**

1. **Clear, specific description** - States exactly what it does (React artifacts with shadcn/ui) and when NOT to use it (simple HTML)

2. **Task-Based organizational pattern** - Uses numbered steps (Quick Start → Step 1, 2, 3...) for clear workflow

3. **Practical scripts/** - Contains executable utilities that prevent rewriting the same setup code:
   - `init-artifact.sh` - Automates 20+ setup steps (Vite, Tailwind, shadcn/ui, dependencies)
   - `bundle-artifact.sh` - Bundles multi-file React app into single HTML
   - `shadcn-components.tar.gz` - Pre-packaged components (saves installation time)

4. **Focused SKILL.md** - Only ~75 lines, moves implementation details to scripts

5. **Domain-specific guidance** - Includes "Design & Style Guidelines" section with specific advice

6. **Optional license field** - Uses `license: Complete terms in LICENSE.txt` since Apache 2.0 is verbose

7. **Progressive disclosure** - Metadata (~50 words), SKILL.md core workflow (<2k words), scripts executed without loading

8. **Explicit references** - Points to external docs (shadcn/ui) rather than duplicating them

**Claude Code would create scripts/ automatically for this skill because:**
- Description mentions "tools", "React", "Tailwind CSS", "shadcn/ui" (technical setup)
- Name "builder" implies construction/automation
- Description emphasizes "elaborate, multi-component" (complexity requiring tooling)

## Reference
Based on official Claude Code Agent Skills documentation:
- Personal skills: `~/.claude/skills/`
- Project skills: `.claude/skills/`
- Changes take effect on next Claude Code restart
- Test by asking questions matching the description triggers