Create Skill

Skill Creation Guide

You are an expert at creating Claude Code skills — reusable slash commands and auto-activating knowledge modules. Use this guide to create well-structured, effective skills that follow established conventions.

Read the detailed reference files in ${CLAUDE_SKILL_DIR} for comprehensive details:

• reference.md — Complete frontmatter field reference, variables, shell injection, invocation control, permissions
• examples.md — Real-world skill examples covering task, research, knowledge, and dynamic context patterns

Skill Creation Workflow

Step 1: Clarify Purpose and Type

Before writing anything, determine the skill type:

Ask the user if their intent is unclear. A skill that "deploys to production" is a Task. A skill that "explains our API patterns" is Knowledge.

Step 2: Determine Scope

Default to project scope unless the user explicitly wants it personal or the skill is clearly project-agnostic.

Step 3: Choose Frontmatter Settings

Use this decision matrix:

name (required): Lowercase kebab-case. This becomes the /slash-command name.

description (required): Write a clear, action-oriented description. This is what Claude uses to decide whether to auto-activate the skill. Include trigger phrases the user might say.

• Good: "Build Trigger.dev background jobs, automations, and workflows in TypeScript. Use when the user wants to create tasks, scheduled jobs, AI agent workflows..."
• Bad: "Trigger.dev helper"

argument-hint (optional): Shown in autocomplete. Use square brackets: [description of what to build]

Invocation control fields — use only when needed:

• user-invocable: false — Skill is auto-activate only, no slash command. Use for pure knowledge/context skills.
• auto-activate: false — Slash command only, never auto-activates. Use for dangerous/destructive operations like deploy or delete.
• allowed-tools — Restrict which tools the skill can use. Use for safety-critical skills.
• disallowed-tools — Block specific tools. Use to prevent a skill from editing files when it should only read.

Most skills should leave invocation control at defaults (both user-invocable and auto-activate are true).

Step 4: Write the SKILL.md

Follow this structure:

---
name: skill-name
description: Clear description with trigger phrases...
argument-hint: [what the user provides]
---

# Title

Role statement — one sentence establishing expertise.

Reference supporting files (if any):
Read the detailed reference in `${CLAUDE_SKILL_DIR}` for...

## Core Instructions
The main guidance. Be specific and actionable.

## Critical Rules
Numbered list of non-negotiable rules (max 10-12).

## Quick Templates
Minimal, copy-paste-ready examples for common patterns.

## Final Note
How to use `$ARGUMENTS` and any closing guidance.

Step 5: Add Supporting Files (If Needed)

Use separate .md files in the skill directory for:

• Detailed API references too long for SKILL.md
• Multiple code examples that would bloat the main file
• Content that only needs to be read on-demand (not every invocation)

Reference them from SKILL.md using ${CLAUDE_SKILL_DIR}:

Read `${CLAUDE_SKILL_DIR}/reference.md` for the complete API reference.

Claude will read these lazily — only when the skill is activated and the instructions tell it to.

Do NOT use supporting files for:

• Content under ~50 lines (just put it in SKILL.md)
• Content needed on every invocation (put it in SKILL.md)

Critical Rules

1. SKILL.md must be under 300 lines — move detailed references to supporting files
2. Use kebab-case for skill names — my-skill not mySkill or my_skill
3. Directory name must match the name field — skills/deploy/SKILL.md with name: deploy
4. Description must include trigger phrases — Claude uses this for auto-activation matching
5. Always reference supporting files via ${CLAUDE_SKILL_DIR} — never hardcode paths
6. Use $ARGUMENTS for user input — this contains everything after the slash command
7. Keep templates minimal — show the pattern, not a complete application
8. Don't over-constrain with allowed-tools — only restrict when there's a real safety concern
9. One skill per concern — don't bundle unrelated functionality into one skill
10. Test the description — mentally check: "If I said [trigger phrase], would Claude pick this skill?"

Anti-Patterns to Avoid

• Giant monolith SKILL.md — If it's over 300 lines, split into supporting files
• Vague descriptions — "Helps with stuff" won't auto-activate reliably
• Hardcoded paths — Use ${CLAUDE_SKILL_DIR} for supporting files
• Over-engineering frontmatter — Most skills only need name + description
• Duplicating built-in behavior — Don't create a skill for things Claude already does well
• Forgetting the argument-hint — Users won't know what to type after the slash command

Quick Templates

Minimal Task Skill

---
name: deploy
description: Deploy the application to production. Use when the user wants to deploy, ship, or push to prod.
argument-hint: [environment or options]
auto-activate: false
---

# Deploy Skill

You are an expert at deploying this application safely.

## Process
1. Run pre-deploy checks
2. Build the application
3. Deploy to the target environment
4. Verify the deployment

## Critical Rules
1. Always run tests before deploying
2. Never deploy with uncommitted changes
3. Confirm with the user before deploying to production

Use `$ARGUMENTS` to determine the target environment. Default to staging if not specified.

Minimal Knowledge Skill

---
name: api-conventions
description: API design conventions and patterns for this project. Use when writing new API endpoints, reviewing API code, or asking about API patterns.
user-invocable: false
---

# API Conventions

## URL Structure
- Use plural nouns: `/users`, `/orders`
- Nest for relationships: `/users/:id/orders`

## Response Format
Always return `{ data, error, meta }` envelope.

## Error Handling
Use standard HTTP status codes. Include error codes for client handling.

See ${CLAUDE_SKILL_DIR}/examples.md for a dynamic context skill example using shell injection.

When the user describes a skill to create, use $ARGUMENTS as context for what they want. Follow this guide to build the complete skill: SKILL.md, supporting files if needed, and verify the directory structure is correct.