Skill Writer

Expert guide for creating Claude Code skills. Reference: https://code.claude.com/docs/en/skills

Quick Reference

YAML Frontmatter Template

---
name: skill-name
description: Third-person description under 1024 chars. Triggers on keywords: keyword1, keyword2
project-agnostic: false  # REQUIRED: explicitly set true for reusable skills, false for project-specific
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
---

Directory Structure

.claude/skills/
  skill-name/
    SKILL.md           # Required - main skill definition
    supporting-file.md # Optional - one level deep only

Project-Agnostic Field

REQUIRED FIELD - Must be explicitly set for every skill.

Default: false - Assumes skills are project-specific unless explicitly marked otherwise.

Set to true when the skill:

• •Contains no project-specific paths, structures, or conventions
• •Can be copied to any project without modification
• •Has no dependencies on specific project tooling or workflows

Set to false when the skill depends on:

• •Project-specific directory structures or paths
• •Project-specific configuration files or conventions
• •Project-specific tooling or workflows

When project-agnostic: false, the skill MUST document:

• •What project-specific dependencies exist
• •What assumptions are made about project structure
• •What configuration or setup is required

Validation Checklist

Before creating any skill, verify:

Name Validation Regex

import re
def validate_name(name: str) -> bool:
    if len(name) > 64:
        return False
    if not re.match(r'^[a-z0-9-]+$', name):
        return False
    if 'anthropic' in name or 'claude' in name:
        return False
    return True

Content Safety Validation

import re
def has_unsafe_bash_pattern(content: str) -> bool:
    """Detects exclamation-mark-backtick pattern that triggers bash execution during skill loading."""
    return bool(re.search(r'!\`', content))

Skill Patterns

Pattern 1: Simple Read-Only Skill

For skills that only need to read and analyze.

---
name: code-reviewer
description: Performs code review on specified files. Analyzes style, patterns, and potential issues. Triggers on keywords: review code, code review, check code quality
project-agnostic: true
allowed-tools:
  - Read
  - Glob
  - Grep
---

Pattern 2: Documentation Skill

For skills that read, analyze, and write documentation.

---
name: api-documenter
description: Generates API documentation from source code. Extracts function signatures, docstrings, and usage examples. Triggers on keywords: document API, API docs, generate documentation
project-agnostic: true
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
---

Pattern 3: Multi-File Refactoring Skill

For skills that need to edit multiple files.

---
name: import-organizer
description: Organizes and sorts imports across Python files. Groups stdlib, third-party, and local imports. Triggers on keywords: organize imports, sort imports, fix imports
project-agnostic: true
allowed-tools:
  - Read
  - Edit
  - Glob
  - Grep
---

Pattern 4: Workflow Skill with Bash

For skills that need to run commands.

---
name: test-runner
description: Executes test suites and analyzes results. Runs pytest with coverage and reports failures. Triggers on keywords: run tests, execute tests, test suite
project-agnostic: false
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
---

Writing Effective Descriptions

Formula

[Action verb] + [what it does] + [how/with what]. [Additional capability]. Triggers on keywords: [comma-separated keywords]

Good Examples

• •"Generates TypeScript interfaces from JSON schemas. Handles nested objects and arrays. Triggers on keywords: json to typescript, generate types, schema conversion"
• •"Analyzes Python code for security vulnerabilities. Checks for injection, auth issues, and data exposure. Triggers on keywords: security audit, vulnerability scan, code security"

Bad Examples

• •"I help you write better code" (first person, vague)
• •"A tool for doing stuff with files" (vague, no triggers)
• •"This skill will assist the user in..." (second person)

Trigger Keywords

• •Include 3-7 natural phrases users might say
• •Mix specific and general terms
• •Include synonyms and variations

Anti-Patterns to Avoid

1. Overly Broad Skills

# Bad - too broad, unfocused
name: code-helper
description: Helps with all coding tasks

# Good - focused purpose
name: python-type-annotator
description: Adds type annotations to Python functions. Infers types from usage and docstrings. Triggers on keywords: add types, type hints, annotate python
project-agnostic: true

2. Excessive Tool Permissions

# Bad - grants all tools for simple task
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

# Good - minimal permissions
allowed-tools:
  - Read
  - Glob

3. Bloated SKILL.md Files

• •Include only information Claude does not already know
• •Avoid restating general programming knowledge
• •Focus on project-specific patterns and conventions

4. Reserved Name Usage

# Invalid - contains reserved word
name: claude-assistant
name: anthropic-helper

5. Deep File Nesting

# Invalid - nested too deep
.claude/skills/my-skill/templates/python/base.md

# Valid - one level only
.claude/skills/my-skill/python-template.md

6. Missing Trigger Keywords

# Bad - no discoverability
description: Formats SQL queries

# Good - discoverable
description: Formats SQL queries with consistent style. Handles SELECT, INSERT, UPDATE, DELETE. Triggers on keywords: format sql, sql formatter, pretty print sql

7. Bash Execution Pattern in Content

# Bad - causes bash execution error during skill loading
# Error: Bash command failed for pattern "[BANG-backtick][backtick]": (eval):1: command not found
description: Shows slash command syntax like [BANG-backtick] ls -la [backtick]

# Good - use safe alternatives
description: Shows slash command syntax using text like "BANG-backtick: ls -la" or describe textually

When documenting slash commands or examples that include exclamation marks:

• •Problem: The pattern exclamation-mark-backtick (visually: [BANG][backtick]) triggers bash execution during skill loading
• •Error message: Bash command failed for pattern "![backtick][backtick]": [stderr] (eval):1: command not found:
• •Safe alternatives:
  • •Use text: "BANG-backtick: command here"
  • •Use placeholder: [BANG-backtick: command]
  • •Describe textually without showing the exact syntax

8. Missing Project-Agnostic Field

# Bad - missing required field
name: my-skill
description: Does something useful
allowed-tools:
  - Read
# ERROR: project-agnostic field is missing

# Good - explicit declaration
name: my-skill
description: Does something useful
project-agnostic: false  # Explicitly marks as project-specific
allowed-tools:
  - Read

Testing Recommendations

Cross-Model Testing

Test skills across different Claude models to ensure consistent behavior:

1. •Claude Sonnet - primary model
2. •Claude Opus - complex reasoning
3. •Claude Haiku - quick tasks

Test Cases

For each skill, verify:

1. •Trigger activation: Skill activates on expected keywords
2. •Tool usage: Only uses allowed tools
3. •Output format: Produces expected output structure
4. •Edge cases: Handles empty files, missing data, errors

Manual Testing Script

# Test skill discovery
ls -la .claude/skills/

# Verify SKILL.md line count
wc -l .claude/skills/skill-name/SKILL.md

# Validate YAML frontmatter
head -20 .claude/skills/skill-name/SKILL.md

Pre-Share Checklist

Before distributing a skill:

• • Name is max 64 chars, lowercase/numbers/hyphens only
• • Name does not contain "anthropic" or "claude"
• • Description is max 1024 chars, third person only
• • Description includes trigger keywords
• • project-agnostic field is explicitly set (REQUIRED)
• • project-agnostic: true only if skill has zero project dependencies
• • project-agnostic: false documents what project dependencies exist
• • SKILL.md is under 500 lines
• • All file references are one level deep
• • All paths use forward slashes
• • Only necessary tools are in allowed-tools
• • Tested on target Claude model(s)
• • Contains only project-specific knowledge

Creating a New Skill

Step-by-Step Process

1. •Define purpose and scope (narrow > broad)
2. •Choose minimal required tools
3. •Write third-person description with triggers
4. •Create directory: .claude/skills/{name}/
5. •Write SKILL.md with frontmatter
6. •Add supporting files if needed (one level deep)
7. •Validate against checklist
8. •Test with representative prompts

Minimal Viable Skill

---
name: example-skill
description: Performs a specific task on target files. Triggers on keywords: example, demo skill
project-agnostic: true
allowed-tools:
  - Read
  - Glob
---

# Example Skill

Brief description of what this skill does.

## Usage

When to use this skill and expected inputs.

## Output

What the skill produces.

Supporting Files

Skills can reference additional files for:

• •Templates
• •Schemas
• •Examples
• •Configuration

Reference Syntax

See [template](./template.md) for the output format.

Constraints

• •Files must be in same directory as SKILL.md
• •Maximum one level of nesting
• •Use forward slashes in paths
• •Keep supporting files focused and concise