Create New Skills

Instructions

This skill helps you create new Agent Skills for Claude Code. Before starting, read the comprehensive documentation files in the docs/ directory for complete context.

Prerequisites

Required Reading - Read these files in order before creating a skill:

1. docs/claude_code_agent_skills.md - Complete guide to creating and managing skills
2. docs/claude_code_agent_skills_overview.md - Architecture and how skills work
3. docs/blog_equipping_agents_with_skills.md - Design principles and best practices

Understanding Skills

What is a Skill?

• A directory containing a SKILL.md file with YAML frontmatter
• Instructions that Claude loads on-demand when relevant
• Optional supporting files (scripts, documentation, templates)
• Like an onboarding guide for a new team member

Progressive Disclosure (3 Levels):

1. Metadata (always loaded): name and description in YAML frontmatter
2. Instructions (loaded when triggered): Main body of SKILL.md
3. Resources (loaded as needed): Additional files, scripts, templates

Key Principle: Only relevant content enters the context window at any time.

Skill Creation Workflow

Step 1: Define the Skill's Purpose

Ask the user these questions:

1. What task or domain should this skill cover?
2. When should Claude use this skill? (triggers)
3. What expertise or workflows need to be captured?
4. Does it need scripts, templates, or other resources?

Document the answers for reference.

Step 2: Create the Skill Directory Structure

Create skills in the project's .claude/skills/ directory for team sharing:

mkdir -p .claude/skills/<skill-name>

Naming conventions:

• Use lowercase with hyphens (e.g., pdf-processing, data-analysis)
• Be descriptive but concise
• Avoid generic names

Note: Project skills (.claude/skills/) are automatically shared with your team via git. For personal skills only you use, create in ~/.claude/skills/ instead.

Step 3: Design the SKILL.md Structure

Every skill must have:

---
name: Your Skill Name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude]

## Examples
[Concrete examples of using this Skill]

Frontmatter Requirements:

• name: Required, max 64 characters
• description: Required, max 1024 characters
  • Include BOTH what it does AND when to use it
  • Mention key trigger words/phrases
  • Be specific, not vague

Optional Frontmatter (Claude Code only):

• allowed-tools: Restrict which tools Claude can use (e.g., Read, Grep, Glob)

Step 4: Write the Instructions Section

Structure the instructions as:

1. Prerequisites - Required dependencies, tools, environment setup
2. Workflow - Step-by-step process (numbered steps)
3. Supporting Details - Additional context, script usage, error handling

Best Practices:

• Use clear, actionable language
• Number sequential steps
• Use bullet points for options/lists
• Include code blocks with bash commands
• Reference supporting files with relative links: [reference.md](reference.md)
• Keep focused on one capability

Example workflow format:

### Workflow

1. **First step description**:
   ```bash
   command to run

• Additional context
• Options or variations

2. Second step description:

   • Detailed instructions
   • What to look for
   • Expected outcomes

3. Third step...

#### Step 5: Write the Examples Section

Provide 2-4 concrete examples showing:
- Different use cases
- Various input formats
- Step-by-step execution
- Expected outcomes

**Example format:**
```markdown
### Example 1: Descriptive Title

User request:

User's exact request text

You would:
1. First action
2. Second action with command:
   ```bash
   actual command

3. Next steps...
4. Final result

#### Step 6: Add Supporting Files (Optional)

If the skill needs additional context:
1. Create files alongside SKILL.md
2. Reference them from instructions: `[forms.md](forms.md)`
3. Use progressive disclosure - split by topic/scenario

**Common supporting file types:**
- Additional instructions (e.g., `advanced_usage.md`)
- Reference documentation (e.g., `api_reference.md`)
- Scripts in `scripts/` directory
- Templates in `templates/` directory
- Configuration examples

**Script guidelines:**
- Make executable: `chmod +x scripts/*.py`
- Add PEP 723 inline dependencies for Python scripts
- Include usage instructions in SKILL.md
- Return clear output for Claude to parse

#### Step 7: Test the Skill

1. Verify file structure:
   ```bash
   ls -la .claude/skills/<skill-name>/

2. Check YAML frontmatter is valid:

   head -10 .claude/skills/<skill-name>/SKILL.md
   

3. Test with relevant queries:

   • Ask questions matching the skill's description
   • Verify Claude loads and uses the skill
   • Check that instructions are clear and actionable

4. Iterate based on testing:

   • Refine description if skill doesn't trigger
   • Clarify instructions if Claude struggles
   • Add examples for common edge cases

Step 8: Commit to Version Control

Since project skills are automatically shared with your team, commit them to git:

git add .claude/skills/<skill-name>
git commit -m "Add <skill-name> skill"
git push

Note: Team members will get the skill automatically when they pull the latest changes.

Best Practices Summary

Description writing:

• ✅ "Transcribes audio/video files to text using Fireworks API. Use when user asks to transcribe, convert speech to text, or needs transcripts."
• ❌ "Helps with audio"

Instruction organization:

• Keep main instructions focused (under 5k tokens ideal)
• Split complex content into linked files
• Use progressive disclosure for optional/advanced content

Skill scope:

• One skill = one capability or workflow
• Don't combine unrelated tasks
• Make focused, composable skills

File references:

• Use relative paths: [file.md](file.md) not absolute paths
• Reference scripts with full path from skill root
• Make it clear when Claude should read vs execute files

Common Patterns from Existing Skills

Pattern 1: Transcription skill

• Prerequisites section with environment setup
• Clear numbered workflow
• Multiple examples showing different formats
• Supporting file for corrections/mappings

Pattern 2: Morning debrief skill

• Two-step process (transcribe, extend)
• Reference to detailed prompt in separate file
• File organization step
• Clear output structure specification

Pattern 3: Meta-skill (this one)

• Extensive prereading documentation
• Step-by-step creation workflow
• Multiple examples with variations
• Best practices and common patterns

Examples

Example 1: Creating a Simple Code Review Skill

User request:

Create a skill that reviews Python code for best practices

You would:

1. Read the documentation files in docs/
2. Ask clarifying questions:
   • What specific best practices? (PEP 8, security, performance?)
   • Should it check only or suggest fixes?
   • Any specific frameworks or libraries?
3. Create the skill directory:

   mkdir -p .claude/skills/python-code-review
   

4. Write SKILL.md with:

   ---
   name: Python Code Review
   description: Reviews Python code for PEP 8 compliance, security issues, and performance. Use when reviewing Python code, checking code quality, or analyzing Python files.
   allowed-tools: Read, Grep, Glob
   ---
   

5. Add Instructions section with:
   • Prerequisites (none needed, uses built-in tools)
   • Workflow:
     1. Read the Python file(s)
     2. Check PEP 8 compliance
     3. Identify security issues
     4. Suggest performance i