Guide for creating effective Claude Code skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
/plugin marketplace add charlesjones-dev/claude-code-plugins-dev/plugin install ai-plugins@claude-code-plugins-devThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides guidance for creating effective Claude Code skills.
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 that no model can fully possess.
This skill should be used when:
skills/{skill-name}/SKILL.md directory/command-namecommands/{command-name}.md fileDecision Guideline: Use a skill for providing ongoing expertise or guidelines. Use a command for one-time interactive setup.
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, etc.)
Critical Requirements:
SKILL.md file (case-sensitive)SKILL.md file must begin with YAML frontmatter containing name and descriptionMetadata Quality: The name and description in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use third-person form (e.g., "This skill should be used when..." instead of "Use this skill when...").
scripts/)Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
scripts/rotate_pdf.py for PDF rotation tasksreferences/)Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
references/finance.md for financial schemas, references/api_docs.md for API specifications, references/policies.md for company policiesassets/)Files not intended to be loaded into context, but rather used within the output Claude produces.
assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typographyThe SKILL.md file must begin with YAML frontmatter containing required and optional fields:
---
name: Skill Name Here
description: Clear explanation of what this skill does and when to use it
---
Field Specifications:
name (required, max 64 characters)
description (required, max 200 characters)
Good Description Examples:
description: Guide for creating and managing Azure DevOps work items (Features, User Stories, Tasks) using proper hierarchy, naming conventions, and formatting. This skill should be used when creating ADO work items.
description: Guide for applying company brand guidelines to documents. This skill should be used when ensuring consistent colors, fonts, logos, and tone across marketing materials.
Bad Description Examples:
description: Helps with Azure DevOps # Too vague, doesn't specify what it helps with
description: Work items # Too short, no context, no third-person form
---
name: Skill Name
description: What it does and when to use it
dependencies: python>=3.8, pandas>=1.5.0
---
version (optional)
dependencies (optional)
python>=3.8, pandas>=1.5.0, node>=18.0.0Skills use a three-level loading system to manage context efficiently:
*Unlimited because scripts can be executed without reading into context window.
Design Principle: Structure the skill so that SKILL.md body provides everything needed for common cases, with bundled resources (references/, scripts/, assets/) for detailed specifications, deterministic operations, and output files.
Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
The markdown content in SKILL.md should answer these key questions:
# Skill Name
This skill provides [brief description of capability].
## When to Use This Skill
This skill should be used when:
- [Specific use case 1]
- [Specific use case 2]
- [Specific use case 3]
## Core Guidelines
### Primary Topic
To accomplish [task], follow these steps:
1. [Step 1]
2. [Step 2]
3. [Step 3]
**Key Rules:**
- [Rule 1 with rationale]
- [Rule 2 with rationale]
### Using Bundled Resources
**Scripts:** To [perform deterministic task], execute `scripts/script_name.py`
**References:** For detailed [specifications/schemas/documentation], read `references/reference_name.md`
**Assets:** To [create output], use the template at `assets/template_name.ext`
## Examples
**Good approach:**
[Example of correct approach]
**Bad approach:**
[Example of incorrect approach]
## Best Practices
1. **Practice Name:** Why this matters and how to apply it
2. **Practice Name:** Why this matters and how to apply it
ado-work-items, brand-guidelines, pdf-creatorCreate files in the references/ directory when:
Reference from SKILL.md:
For detailed field specifications, read references/field_specs.md.
Include executable scripts when:
Script Organization:
skills/my-skill/
SKILL.md
scripts/
parse_data.py # Python utilities
format_output.js # JavaScript utilities
Reference from SKILL.md:
To parse the data, use the provided Python script at scripts/parse_data.py.
To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
To turn concrete examples into an effective skill, analyze each example by:
Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:
scripts/rotate_pdf.py script would be helpful to store in the skillExample: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skillExample: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:
references/schema.md file documenting the table schemas would be helpful to store in the skillTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
Create the skill directory structure:
mkdir -p skills/{skill-name}
mkdir -p skills/{skill-name}/scripts # If needed
mkdir -p skills/{skill-name}/references # If needed
mkdir -p skills/{skill-name}/assets # If needed
Plugin Context: When creating a skill within a Claude Code plugin, place it in plugins/{plugin-name}/skills/{skill-name}/
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
To begin implementation, start with the reusable resources identified in Step 2: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.
Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language.
To complete SKILL.md, answer the following questions:
After creating the skill, test it with realistic scenarios:
Validation checklist:
Plugin Context: If creating a skill within a Claude Code plugin, update plugin documentation to mention the skill.
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
Iteration workflow:
Use Case: Providing expert knowledge for a specific domain (e.g., ADO work items, brand guidelines)
Structure:
---
name: Domain Name Expert
description: Expert guidance for [specific task] using [domain-specific concepts and rules]
---
# Domain Name Expert Skill
This skill provides expert guidance on [domain].
## When to Use This Skill
Invoke this skill when:
- Working with [domain-specific tools]
- Creating [domain-specific artifacts]
- Following [domain-specific processes]
## Core Concepts
[Domain knowledge organized by topic]
## Best Practices
[Domain-specific best practices]
Use Case: Working with specific file formats (PDF, Excel, Word)
Structure:
---
name: Format Name Processor
description: Create, read, and manipulate [format] files with proper formatting and structure
dependencies: [required packages]
---
# Format Name Processor Skill
This skill helps you work with [format] files.
## When to Use This Skill
Invoke this skill when:
- Creating new [format] documents
- Reading data from [format] files
- Modifying existing [format] documents
## File Format Specifications
[Format-specific details]
## Common Operations
[How to perform common tasks]
## Example Scripts
Use the provided scripts at scripts/[script-name] for [purpose].
Use Case: Standardizing repeatable workflows (e.g., meeting notes, reports)
Structure:
---
name: Workflow Name Automation
description: Automate [workflow name] by following company standards for [specific outputs]
---
# Workflow Name Automation Skill
This skill automates [workflow].
## When to Use This Skill
Invoke this skill when:
- Starting a new [workflow instance]
- Following the standard [process name]
## Workflow Steps
1. **Step Name:** Description and guidelines
2. **Step Name:** Description and guidelines
## Templates
[Provide templates or examples]
references/scripts/assets/Before finalizing a skill, verify:
Frontmatter:
Content Structure:
Quality:
Integration:
---
name: My Skill Name
description: Brief description of what this skill does and when to use it (max 200 chars)
dependencies: python>=3.8
---
# My Skill Name Skill
This skill provides [brief description of capability and purpose].
## When to Use This Skill
Invoke this skill when:
- [Specific use case 1]
- [Specific use case 2]
- [Specific use case 3]
## Core Guidelines
### Primary Topic
[Main instructions and guidelines]
**Key Rules:**
- [Rule 1 with rationale]
- [Rule 2 with rationale]
- [Rule 3 with rationale]
### Secondary Topic
[Additional instructions]
## Examples
**Example 1: Common Use Case**
Good approach:
[Code or text showing correct approach]
Bad approach:
[Code or text showing incorrect approach]
**Example 2: Edge Case**
[Another example with explanation]
## Best Practices
1. **Practice Name:** Why this matters and how to apply it
2. **Practice Name:** Why this matters and how to apply it
3. **Practice Name:** Why this matters and how to apply it
## Supporting Resources
For detailed specifications, read references/specifications.md.
For data processing utilities, execute scripts/process_data.py.
## Troubleshooting
**Problem:** Common issue description
**Solution:** How to resolve it
When asked to create a new skill, follow these steps:
Ask the user:
mkdir -p skills/{skill-name}
Create the YAML frontmatter:
Structure the markdown:
Add:
Review:
If part of a plugin:
Skills can reference each other:
For authentication guidelines, the authentication-standards skill provides detailed guidance.
Skills can provide context-dependent guidance:
If working in a production environment:
- [Production-specific rules]
If working in a development environment:
- [Development-specific rules]
Skills can provide guidance for MCP tool usage:
When using the Azure DevOps MCP server tools (mcp__ado__*):
- [Tool-specific guidelines]
Possible Causes:
Solution:
Possible Causes:
Solution:
Possible Causes:
Solution:
When creating skills:
Skills execute in Claude Code's environment with file and code execution access - treat them with appropriate security caution.
Skills are modular packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. To create effective skills:
By following the Skill Creation Process and these best practices, skills will enhance Claude Code's capabilities for specialized tasks while maintaining token efficiency and usability.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.