Claude Code Skill Design Best Practices

Claude Code Skill Design Best Practices

Comprehensive guide to designing effective, maintainable, and secure skills.

Design Philosophy

Single Responsibility Principle

Each skill should do one thing well.

✅ Good - Focused Skills:

code-analyzer         → Analyzes code quality
test-generator        → Generates tests
doc-writer            → Writes documentation
commit-helper         → Helps with commits

❌ Bad - Too Broad:

code-helper          → What does it help with?
developer-tool       → Too vague
swiss-army-knife     → Does everything (poorly)

Why?

• Easier to maintain
• Clearer expectations
• Better reusability
• Simpler testing

Composability Over Monoliths

Build small skills that work together:

✅ Good - Composable:

# skill: code-analyzer
- Analyzes code, reports issues

# skill: code-fixer
- Takes analysis results, applies fixes
- Uses: Skill (invokes code-analyzer)

# skill: code-review
- Orchestrates full review workflow
- Uses: Skill (invokes code-analyzer and code-fixer)

❌ Bad - Monolithic:

# skill: do-everything
- Analyzes, fixes, tests, documents, deploys...
- Impossible to maintain

Naming Conventions

Pattern: [domain]-[capability]

Format: kebab-case Structure: <domain>-<action> or <domain>-<noun>

Good Examples:

python-test-generator
react-component-analyzer
api-doc-writer
git-commit-helper
sql-query-optimizer
dockerfile-validator

Bad Examples:

pytestgen              → Unclear abbreviation
helper                 → Too generic
codeAnalyzer           → Wrong case
my_tool                → Underscores, too generic

Be Specific, Not Generic

✅ Specific:

react-hook-validator
typescript-interface-generator
kubernetes-manifest-validator

❌ Generic:

validator
generator
helper
tool
utility

Avoid Acronyms

✅ Spell Out:

api-doc-generator
continuous-integration-helper
pull-request-reviewer

❌ Acronyms:

adg
ci-helper
prr

Exception: Well-known acronyms (api, sql, html, css)

Tool Selection

Principle: Least Privilege

Only request tools you'll actually use.

✅ Minimal & Specific:

# Code analysis (read-only)
allowed-tools:
  - Read
  - Glob
  - Grep

❌ Too Many:

# "Just in case" approach
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
  - AskUserQuestion

Tool Patterns by Use Case

1. Code Analysis (Read-Only):

allowed-tools:
  - Read      # Examine files
  - Glob      # Find files by pattern
  - Grep      # Search for patterns

2. File Generation:

allowed-tools:
  - Read      # Load templates
  - Write     # Create new files
  - Glob      # Find templates

3. Code Refactoring:

allowed-tools:
  - Read      # Understand code
  - Edit      # Modify in-place
  - Glob      # Find files to refactor

4. Interactive Workflows:

allowed-tools:
  - AskUserQuestion    # Gather requirements
  - Read               # Process input
  - Write              # Generate output

5. System Automation:

allowed-tools:
  - Bash      # Run commands
  - Read      # Check files

6. Meta-Skills (Create Things):

allowed-tools:
  - AskUserQuestion    # Interactive wizard
  - Write              # Create files
  - Bash               # File operations

Security Considerations

Bash Tool - Use Carefully:

• Can execute arbitrary commands
• Validate inputs
• Avoid user-controlled command strings
• Document what commands you'll run

Write/Edit Tools - Validate Paths:

• Check file paths before writing
• Avoid overwriting critical files
• Confirm destructive operations
• Use project-relative paths when possible

Skill Content Structure

Recommended Template

# [Skill Name]: [Brief Purpose]

You are an expert [role] specializing in [domain]. Your role is to [primary task].

## Core Responsibilities

1. **Primary Function**: Main capability
2. **Supporting Functions**: Additional capabilities
3. **Output**: What users receive

## Workflow

### Phase 1: [Understanding/Discovery/Preparation]
1. Concrete step
2. Concrete step
3. Concrete step

### Phase 2: [Analysis/Processing/Execution]
1. Concrete step
2. Concrete step

### Phase 3: [Delivery/Reporting/Completion]
1. Concrete step
2. Concrete step

## Best Practices

When executing this skill:
- Specific guideline 1
- Specific guideline 2
- Specific guideline 3

## Examples

### Example 1: [Common Use Case]
\```
User: "[Realistic request]"

You should:
1. [Specific action with tool]
2. [Specific action with tool]
3. [Expected output]
\```

## Tool Usage

[Explain how you use each tool and why]

## Edge Cases

- **Situation 1**: How to handle
- **Situation 2**: How to handle

## Output Format

[Template or example of typical output]

## Notes

- Important considerations
- Limitations
- Prerequisites

Be Explicit, Not Vague

✅ Explicit:

## Workflow

### Phase 1: Find Python Files
1. Use Glob with pattern: "**/*.py"
2. Exclude: "**/test_*.py", "**/__pycache__/**"
3. Sort results alphabetically

### Phase 2: Analyze Each File
1. Use Read to load file contents
2. Use Grep to find functions: pattern "^def "
3. For each function:
   - Check docstring presence
   - Verify type hints
   - Count lines (complexity)

### Phase 3: Generate Report
1. Format as markdown table
2. Include: file, function, issues, severity
3. Sort by severity: high → medium → low
4. Add summary statistics

❌ Vague:

## Workflow

1. Find the files
2. Look at them
3. Find problems
4. Tell the user

Include Concrete Examples

✅ Good Examples:

## Example: Analyzing Auth Module

User: "Analyze the auth module for security issues"

You should:

1. **Find auth files:**
   - Use Glob: "src/auth/**/*.py"
   - Expected: auth/login.py, auth/validators.py, auth/tokens.py

2. **Analyze each file:**
   - Use Read to load contents
   - Use Grep to find patterns:
     * SQL queries: "SELECT .* FROM"
     * Password handling: "password"
     * Token generation: "jwt|token"

3. **Check for issues:**
   - SQL injection: Raw SQL with string formatting
   - Weak passwords: Length < 8, no complexity
   - Token security: Weak secrets, no expiration

4. **Report findings:**
   \```
   ## Security Analysis: auth module

   ### Files Analyzed: 3
   - auth/login.py
   - auth/validators.py
   - auth/tokens.py

   ### Issues Found: 2

   1. **HIGH**: SQL Injection Risk
      - File: auth/login.py:45
      - Code: `f"SELECT * FROM users WHERE email='{email}'"`
      - Fix: Use parameterized queries

   2. **MEDIUM**: Weak Password Requirements
      - File: auth/validators.py:12
      - Issue: Minimum length is 6 characters
      - Recommendation: Increase to 12, require complexity

   ### Summary:
   - 1 high severity issue (immediate action required)
   - 1 medium severity issue (should address soon)
   \```

Documentation

README.md Essentials

Every skill should have a README.md:

# [Skill Name]

[One paragraph description]

## What It Does

[2-3 sentences explaining capabilities]

## How to Use

\```
[Example invocations]
\```

## Examples

[Concrete examples with input/output]

## Requirements

[Prerequisites, dependencies]

## Tips

[Usage tips, gotchas, best practices]

When to Add Examples Directory

Add examples/ when:

• Skill has multiple usage modes
• Output format needs demonstration
• Common patterns should be shown
• Skill is complex or novel

When to Add Templates Directory

Add templates/ when:

• Skill generates files from templates
• Multiple output formats supported
• Reusable boilerplate provided

When to Add Scripts Directory

Add scripts/ when:

• Helper scripts simplify skill logic
• External validation needed
• Command-line utilities support skill

Versioning Strategy

Follow semantic versioning (semver):

Version Format: MAJOR.MINOR.PATCH

MAJOR (X.0.0) - Breaking changes:

• Changed skill behavior incompatibly
• Removed functionality
• Changed output format significantly
• Changed tool requirements substantially

MINOR (1.X.0) - New features (backward compatible):

• Added new capabilities
• Added optional parameters
• Enhanced existing features
• Added new tool permissions

PATCH (1.0.X) - Bug fixes:

• Fixed incorrect behavior
• Improved error messages
• Updated documentation
• Performance improvements

Examples:

1.0.0 → 1.0.1   (Fixed bug in file parsing)
1.0.1 → 1.1.0   (Added support for TypeScript files)
1.1.0 → 2.0.0   (Changed output format from JSON to markdown)

When to Bump Version:

Changed allowed-tools?              → MAJOR
Added new workflow phase?           → MINOR
Fixed typo in output?               → PATCH
Improved documentation?             → PATCH
Added new file type support?        → MINOR
Changed how results are formatted?  → MAJOR
Optimized performance?              → PATCH
Added optional feature?             → MINOR

Testing Strategy

Before Release:

1. Unit Testing: Does skill respond to direct invocation?
2. Integration Testing: Works with other skills?
3. Edge Cases: Handles errors gracefully?
4. Performance: Efficient with large inputs?

Test Cases to Consider:

Happy Path:

• Normal, expected usage
• Typical input sizes
• Standard scenarios

Edge Cases:

• Empty input
• Very large input
• Missing files
• Permission denied
• Invalid syntax
• Network failures (for WebFetch)

Error Handling:

• Graceful failures
• Clear error messages
• Partial results when possible
• No silent failures

Common Patterns

Pattern: Progressive Disclosure

Start simple, add complexity as needed:

Version 1.0.0 - Minimal:

name: code-analyzer
description: Analyzes Python code for issues
allowed-tools: [Read, Glob]
# Basic analysis only

Version 1.1.0 - Enhanced:

name: code-analyzer
description: Analyzes Python code for issues
allowed-tools: [Read, Glob, Grep]
# Added pattern matching

Version 2.0.0 - Comprehensive:

name: code-analyzer
description: Analyzes Python code for issues with auto-fix suggestions
allowed-tools: [Read, Glob, Grep, Edit]
# Added auto-fix capability (breaking change: new tool)

Pattern: Configuration via AskUserQuestion

For flexible workflows:

allowed-tools:
  - AskUserQuestion
  - Read
  - Write

## Workflow

### Phase 1: Gather Configuration
1. Use AskUserQuestion: "Which file types?" → user selects
2. Use AskUserQuestion: "Severity level?" → user chooses
3. Use AskUserQuestion: "Output format?" → user picks

### Phase 2: Execute Based on Configuration
[Use gathered config to customize behavior]

Pattern: Skill Composition

Skills invoking other skills:

name: comprehensive-review
description: Full code review with analysis, testing, and documentation
allowed-tools:
  - Skill
  - Write
dependencies:
  - code-analyzer
  - test-generator
  - doc-writer

## Workflow

### Phase 1: Analysis
1. Use Skill to invoke: code-analyzer
2. Collect analysis results

### Phase 2: Testing
1. Use Skill to invoke: test-generator
2. Generate tests for uncovered code

### Phase 3: Documentation
1. Use Skill to invoke: doc-writer
2. Generate docs for undocumented code

### Phase 4: Summary Report
1. Compile all results
2. Use Write to create comprehensive report

Performance Tips

1. Use Glob Efficiently

✅ Specific patterns:

**/*.py           → All Python files
src/**/*.js       → JavaScript in src only
tests/**/test_*.py → Test files only

❌ Too broad:

**/*              → Everything (slow)

2. Batch Operations

✅ Batch reads:

1. Use Glob to collect all file paths
2. Read files in logical groups
3. Process batch before moving to next

❌ One at a time:

1. Find file
2. Read file
3. Process file
4. Repeat (inefficient)

3. Early Exit

✅ Stop when done:

1. Search for critical issue
2. If found: report immediately, exit
3. Don't continue unnecessary work

4. Avoid Redundant Reads

✅ Cache results:

1. Read file once
2. Store relevant data
3. Reuse for multiple checks

❌ Re-read multiple times:

1. Read file for check 1
2. Read same file for check 2
3. Read same file for check 3

Security Best Practices

1. Validate Inputs

When using Bash or Write:

## Before executing:
1. Validate file paths (no ../../../etc/passwd)
2. Sanitize user inputs
3. Check file extensions
4. Verify permissions

2. Least Privilege

# ✅ Only what's needed
allowed-tools:
  - Read
  - Glob

# ❌ "Just in case"
allowed-tools:
  - Bash  # Can execute anything!
  - Write # Can create files anywhere!
  - Edit  # Can modify anything!

3. Document Security Implications

## Security Notes

This skill uses Bash to:
- Run `git status` (read-only, safe)
- Run `git diff` (read-only, safe)
- Does NOT run: git push, git commit, rm, etc.

This skill uses Write to:
- Create files in `.claude/generated/` only
- Does NOT write to: system directories, user files

Maintenance

Regular Reviews

Quarterly:

• Update documentation
• Review for outdated patterns
• Check tool usage is current
• Update examples

On Claude Code Updates:

• Check if new tools available
• Verify existing tools still work
• Update allowed-tools if beneficial

Deprecation

If deprecating a skill:

1. Mark in README:

   # ⚠️ DEPRECATED
   
   This skill is deprecated. Use `new-skill` instead.
   
   **Migration Guide:**
   - Old: `use old-skill for X`
   - New: `use new-skill for X`
   

2. Update version:

   version: 2.1.0-deprecated
   

3. Keep functional during transition

4. Remove after sufficient notice (e.g., 3 months)

Anti-Patterns to Avoid

❌ Swiss Army Knife

name: developer-helper
description: Helps with everything
# TOO BROAD - split into focused skills

❌ Unclear Naming

name: helper
description: Helps with stuff
# VAGUE - be specific

❌ Too Many Tools

allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
  - AskUserQuestion
  - TodoWrite
# EXCESSIVE - use only what you need

❌ Vague Instructions

## Workflow
1. Look at the code
2. Find problems
3. Tell user
# NOT ACTIONABLE - be explicit

❌ No Examples

# Just theory, no concrete examples
# ADD EXAMPLES - show don't tell

Checklist for Quality Skills

Before releasing a skill:

• Name is descriptive kebab-case
• Description is one clear sentence
• Version follows semver
• Only necessary tools requested
• Workflow is explicit and detailed
• Concrete examples included
• Edge cases documented
• Error handling specified
• README.md explains usage
• Validated with validation script
• Tested with realistic scenarios
• Security implications documented

Next Steps

• Review skill-structure.md for anatomy reference
• Read frontmatter-reference.md for field details
• Examine examples/simple-skill/ for working code
• Use skill-builder to create validated skills
• Start simple, iterate based on usage