---

name: skill-writer description: Expert assistant for authoring Claude Code skills. Creates precise SKILL.md files with proper YAML frontmatter, validates naming conventions, and applies official best practices. Triggers on keywords: writing skills, creating skills, skill authoring, SKILL.md, new skill, skill template, skill validation, skill structure, create skill, update skill project-agnostic: true allowed-tools:

• Read
• Write
• Edit
• Glob
• Grep

---

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:

Field	Constraint	Check
name	Max 64 chars	len(name) <= 64
name	Lowercase, numbers, hyphens only	/^[a-z0-9-]+$/
name	No reserved words	No "anthropic" or "claude"
description	Max 1024 chars	len(description) <= 1024
description	Third person only	No "I", "you", "we"
project-agnostic	Boolean, REQUIRED	Must be explicitly set (true/false)
SKILL.md	Under 500 lines	wc -l < 500
SKILL.md	No bash execution pattern	No exclamation-mark-backtick sequence
File refs	One level deep	No nested directories
Paths	Forward slashes only	No backslashes

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