Creates and updates Agent Skills (SKILL.md directories) with proper YAML frontmatter, progressive disclosure patterns, and tool restrictions. Use when creating skills, authoring Agent Skills, building reusable capabilities, or when users mention skills, SKILL.md, skill development, agent capabilities, or progressive disclosure.
Creates and updates Agent Skills (SKILL.md directories) with proper YAML frontmatter, progressive disclosure patterns, and tool restrictions. Use when creating skills, authoring Agent Skills, building reusable capabilities, or when users mention skills, SKILL.md, skill development, agent capabilities, or progressive disclosure.
/plugin marketplace add outfitter-dev/agents/plugin install agent-kit@outfitterThis skill inherits all available tools. When active, it can use any tool Claude has access to.
EXAMPLES.mdREFERENCE.mdscripts/README.mdscripts/scaffold-skill.shscripts/validate-skill.shCreate Agent Skills that package expertise into discoverable, reusable capabilities for Claude Code.
Agent Skills are different from slash commands and plugins:
/command)Skills consist of a SKILL.md file with instructions plus optional supporting files.
allowed-tools# Create skill directory
mkdir -p .claude/skills/my-skill
cd .claude/skills/my-skill
# Create SKILL.md
cat > SKILL.md << 'EOF'
---
name: My Skill Name
description: What this skill does and when to use it. Include trigger keywords.
---
# My Skill Name
## Instructions
Step-by-step guidance for Claude on how to use this skill.
## Examples
Concrete examples showing skill usage.
EOF
---
name: Safe Code Reviewer
description: Review code for best practices without making changes. Use when reviewing code, checking quality, or auditing codebase.
allowed-tools: Read, Grep, Glob
---
# Safe Code Reviewer
## Review Checklist
1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage
When activated, analyze code using read-only tools only.
my-skill/
├── SKILL.md (required - main instructions)
├── REFERENCE.md (optional - detailed documentation)
├── EXAMPLES.md (optional - comprehensive examples)
├── scripts/
│ └── helper.sh (optional - utility scripts)
└── templates/
└── config.yaml (optional - templates)
~/.claude/skills/).claude/skills/)plugin/skills/)---
name: skill-name
description: What it does and when to use it, with trigger keywords
---
---
name: skill-name
description: Detailed description with trigger keywords
allowed-tools: Read, Grep, Glob, Bash(git *)
version: 1.0.0
---
# Skill Name
## Quick Start
Brief introduction and basic usage
## Instructions
Step-by-step guidance for Claude
## Examples
Concrete usage examples
## Advanced Usage
See [REFERENCE.md](REFERENCE.md) for detailed documentation
See [EXAMPLES.md](EXAMPLES.md) for more examples
The description field is essential for skill discovery.
description: Helps with documents
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
Excel Analysis:
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
Git Workflows:
description: Automate git workflows including branch management, commit formatting, and PR creation. Use when managing git repositories, creating branches, or handling commits.
API Testing:
description: Test REST APIs with validation and reporting. Use when testing APIs, endpoints, or HTTP services, or when user mentions API testing or endpoint validation.
Limit which tools Claude can use when skill is active:
---
name: Read-Only Analyzer
description: Analyze code without making modifications
allowed-tools: Read, Grep, Glob
---
Benefits:
Common Patterns:
# Read-only skills
allowed-tools: Read, Grep, Glob
# Git operations
allowed-tools: Bash(git *), Read, Write
# Safe bash commands
allowed-tools: Bash(find:*), Bash(wc:*), Read
# File modifications
allowed-tools: Read, Edit, Write
# Complete workflow
allowed-tools: Read, Edit, Write, Bash(git *), Bash(bun test:*)
Keep SKILL.md under 500 lines by referencing supporting files:
# My Complex Skill
## Quick Start
Basic usage instructions here (keep brief)
## Common Operations
Most frequent use cases
## Advanced Topics
For detailed information:
- See [REFERENCE.md](REFERENCE.md) for complete API documentation
- See [EXAMPLES.md](EXAMPLES.md) for real-world examples
- See [scripts/README.md](scripts/README.md) for utility scripts
## Scripts
Run helper scripts:
```bash
./scripts/analyze.sh input.txt
./scripts/format-output.py results.json
## Supporting Files
### REFERENCE.md (Optional)
- Complete API documentation
- Detailed configuration options
- Integration guides
- Troubleshooting
### EXAMPLES.md (Optional)
- Real-world use cases
- Common patterns
- Step-by-step tutorials
- Edge cases
### scripts/ Directory (Optional)
- Utility scripts
- Helper functions
- Data processors
- Must be executable: `chmod +x scripts/*.sh`
### templates/ Directory (Optional)
- Configuration templates
- Code templates
- File structure examples
## Best Practices
### 1. Focused Skills
**Good: Focused**
✅ pdf-form-filling ✅ excel-pivot-tables ✅ api-endpoint-testing
**Bad: Too Broad**
❌ document-processing ❌ data-analysis ❌ testing
### 2. Clear Descriptions
```yaml
# ❌ Vague
description: Helps with files
# ✅ Specific
description: Process JSON files including parsing, validation, transformation, and formatting. Use when working with JSON data or when user mentions JSON processing.
# ✅ Good: Brief main file
Quick start (20 lines)
Common operations (50 lines)
Reference to REFERENCE.md for details
# ❌ Bad: Everything in SKILL.md
Complete documentation (2000 lines)
All examples (500 lines)
Every edge case (300 lines)
# ✅ Appropriate restrictions
allowed-tools: Read, Grep, Glob # For analysis skills
# ❌ Too restrictive
allowed-tools: Read # Can't search effectively
# ❌ Too permissive
# (no allowed-tools when Read-only intent)
---
name: my-skill
description: Skill description
version: 1.2.0 # Semantic versioning
---
Add changelog in SKILL.md content:
## Version History
### 1.2.0 (2025-10-20)
- Added support for TypeScript
- Improved error handling
### 1.1.0 (2025-09-15)
- Initial release
# Enable debug mode
claude --debug
# Look for skill loading messages
# Should see: "Loaded skill: my-skill from ..."
# Ask Claude something that should trigger your skill
"Can you help me process this PDF?"
# For PDF skill, Claude should activate it automatically
# If skill has allowed-tools: [Read, Grep, Glob]
# Ask Claude to analyze a file
# Should NOT ask permission for Read/Grep/Glob
# SHOULD ask permission for Edit/Write
# Create test files
# Invoke skill naturally
# Verify behavior matches expectations
---
name: code-complexity-analyzer
description: Analyze code complexity and suggest refactoring. Use when reviewing code complexity, finding code smells, or improving maintainability.
allowed-tools: Read, Grep, Glob
---
# Code Complexity Analyzer
## Analysis Criteria
1. Cyclomatic complexity
2. Function length
3. Nesting depth
4. Code duplication
Provide refactoring suggestions for complex code.
---
name: markdown-formatter
description: Format and lint Markdown documents following best practices. Use when working with Markdown files or when user mentions Markdown formatting or linting.
allowed-tools: Read, Edit, Write
---
# Markdown Formatter
## Formatting Rules
1. Consistent heading hierarchy
2. Proper list formatting
3. Code block language tags
4. Link validation
Apply formatting to Markdown files.
---
name: test-generator
description: Generate unit tests from code. Use when writing tests, adding test coverage, or when user mentions test generation.
allowed-tools: Read, Write, Bash(bun test:*)
---
# Test Generator
## Test Generation Strategy
1. Identify functions to test
2. Generate test cases
3. Add edge cases
4. Include error scenarios
Generate comprehensive test suites.
Check file location:
# Personal skill
ls ~/.claude/skills/my-skill/SKILL.md
# Project skill
ls .claude/skills/my-skill/SKILL.md
Validate YAML frontmatter:
# Must have opening ---
# Must have closing ---
# No tabs (use spaces)
# Valid YAML syntax
Improve description specificity:
# Before: Too vague
description: Process files
# After: Specific with triggers
description: Parse and validate JSON files, including schema validation and formatting. Use when working with JSON data, .json files, or when user mentions JSON parsing or validation.
Add trigger keywords:
.json, .xlsx, PDFparse, validate, format, testAPI, database, spreadsheetVerify tool names (case-sensitive):
# ✅ Correct
allowed-tools: Read, Grep, Glob
# ❌ Incorrect
allowed-tools: read, grep, glob
Check bash patterns:
# ✅ Correct
allowed-tools: Bash(git *), Bash(npm *)
# ❌ Incorrect
allowed-tools: Bash(git), Bash(npm)
Enable debug mode:
claude --debug
# Shows skill loading errors and issues
Check dependencies:
chmod +x scripts/*.shscripts/helper.sh# Create new skill
mkdir -p .claude/skills/my-skill
./scripts/scaffold-skill.sh my-skill
# Validate skill
./scripts/validate-skill.sh .claude/skills/my-skill
# Test skill discovery
claude --debug
See REFERENCE.md for:
See EXAMPLES.md for:
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.