skill-writer
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
When & Why to Use This Skill
The Skill Writer is a specialized assistant designed to streamline the creation, validation, and optimization of Claude Code skills. It ensures that all SKILL.md files adhere to official best practices, including precise YAML frontmatter configuration, strict naming conventions, and proper project-agnostic declarations, enabling developers to build robust and discoverable AI capabilities efficiently.
Use Cases
- Automating the generation of standardized SKILL.md templates with correct YAML frontmatter and required fields.
- Validating skill names and descriptions against character limits and regex constraints to ensure they load correctly in Claude Code.
- Determining the appropriate 'project-agnostic' status for a skill based on its dependencies and directory structure.
- Identifying and fixing common anti-patterns, such as unsafe bash execution sequences or excessive tool permissions that compromise security.
- Optimizing trigger keywords within descriptions to improve the discoverability and activation accuracy of custom skills.
| 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 |
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:
- Claude Sonnet - primary model
- Claude Opus - complex reasoning
- Claude Haiku - quick tasks
Test Cases
For each skill, verify:
- Trigger activation: Skill activates on expected keywords
- Tool usage: Only uses allowed tools
- Output format: Produces expected output structure
- 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-agnosticfield is explicitly set (REQUIRED) -
project-agnostic: trueonly if skill has zero project dependencies -
project-agnostic: falsedocuments 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
- Define purpose and scope (narrow > broad)
- Choose minimal required tools
- Write third-person description with triggers
- Create directory:
.claude/skills/{name}/ - Write SKILL.md with frontmatter
- Add supporting files if needed (one level deep)
- Validate against checklist
- 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