zhongwei/gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:00:42 +08:00
commit cc49e355bc
37 changed files with 10917 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

649
skills/skill-builder/reference/best-practices.md Normal file
View File

@@ -0,0 +1,649 @@
# Best Practices for Writing Claude Skills
Comprehensive guide to creating effective, maintainable, and discoverable skills.
## Core Principles
### 1. Be Concise
**Why**: Skills extend Claude's knowledge. Claude already has extensive capabilities - only add what's truly new.
**How**:
- Challenge every sentence: "Does Claude really need this?"
- Remove obvious information
- Keep SKILL.md under 500 lines
- Move extensive details to reference files
**Examples**:
```markdown
# Too verbose
## Processing Files
When you need to process files, first you should read them using the Read tool.
The Read tool is a built-in capability that allows you to access file contents.
After reading, analyze the content carefully.
# Concise (Claude knows this)
## Processing Files
Extract key metrics from each file and aggregate results.
```
### 2. Set Appropriate Degrees of Freedom
**Why**: Match specificity to task complexity and fragility.
**High Freedom**: For flexible, creative tasks where Claude can adapt
```markdown
Analyze the codebase and suggest architectural improvements.
```
**Low Freedom**: For fragile, sequence-critical, or safety-critical operations
```markdown
1. Backup database to `backups/db_YYYYMMDD.sql`
2. Run migration: `npm run migrate:up`
3. Verify migration: check `schema_version` table
4. If verification fails, rollback: `npm run migrate:down`
```
**Balance**:
```markdown
# Too restrictive (micro-managing)
1. Open the file
2. Read line 1
3. Parse the date
4. Store in variable called 'date'
# Appropriate
Extract the date from the first line using format YYYY-MM-DD.
Validate it's a valid date before proceeding.
```
### 3. Clear Naming
**Skill Names** (in frontmatter):
- Use gerund form (verb + -ing)
- Be specific and descriptive
- Avoid vague terms
```yaml
# Good
name: Analyzing Performance Metrics
name: Generating API Documentation
name: Processing Invoice PDFs
# Avoid
name: Helper
name: Utils
name: Manager
name: Processor
```
**Directory Names**:
```
# Good
performance-analyzer/
api-doc-generator/
invoice-processor/
# Avoid
helper/
utils/
thing/
```
### 4. Specific Descriptions
**Why**: The description determines when Claude chooses to use your skill.
**Formula**: [Action] [specific task] [key context/constraints]
```yaml
# Excellent
description: Analyzes React components for performance anti-patterns including unnecessary re-renders, missing memoization, and inefficient hooks usage
# Good
description: Processes invoice PDFs to extract vendor, date, items, and total with validation
# Too vague (Claude won't know when to use it)
description: Helps with documents
description: A useful utility
```
**Include key terms**:
```yaml
# Include technology names
description: Creates TypeScript React components with styled-components and Jest tests
# Include output formats
description: Converts CSV data to validated JSON following schema.org format
# Include constraints
description: Generates API documentation from JSDoc comments preserving examples and types
```
## Writing Effective Instructions
### Structure Your Instructions
```markdown
# Good structure
## Overview
Brief 1-2 sentence summary
## Prerequisites
What must exist or be true before starting
## Workflow
1. Step one with specifics
2. Step two with validation
3. Step three with output format
## Validation
How to verify success
## Examples
Concrete examples
```
### Be Specific About Outputs
```markdown
# Vague
Generate a report.
# Specific
Generate a report in markdown with:
- Summary section with key findings
- Metrics table with columns: metric, value, threshold, status
- Recommendations list ordered by priority
```
### Include Validation Steps
```markdown
# Without validation
1. Parse the configuration
2. Apply settings
3. Restart service
# With validation
1. Parse the configuration
2. Validate required fields exist: host, port, api_key
3. Apply settings
4. Verify service starts successfully (check port is listening)
```
### Provide Context for Decisions
```markdown
# No context
Use the fast algorithm.
# With context
Use the fast algorithm for files under 10MB.
For larger files, use the streaming algorithm to avoid memory issues.
```
## Progressive Disclosure
### When to Use Reference Files
Use reference files when:
- Background information exceeds 100 lines
- API documentation is comprehensive
- Multiple detailed examples are needed
- Content is optional/advanced
### Self-Contained Skills
**IMPORTANT**: Skills must be completely self-contained within their own directory.
**DO:**
- Reference files within the skill directory: `reference/api-docs.md`
- Include all necessary content within the skill structure
- Duplicate information if needed across multiple skills
**DON'T:**
- Reference files outside the skill directory (e.g., `../../CLAUDE.md`)
- Reference project files (e.g., `../other-skill/reference.md`)
- Depend on external documentation not in the skill directory
Why: Skills may be used in different contexts (personal, project, plugin) and must work independently without external dependencies.
### How to Reference
```markdown
# Good: Clear purpose, internal reference
For complete API reference, see `reference/api-docs.md`
See `reference/examples.md` for 10+ real-world examples
# Bad: External reference
See the project CLAUDE.md for more details
Refer to ../../docs/guide.md
# Too vague
More info in reference folder
```
### What Stays in SKILL.md
Keep in SKILL.md:
- Core workflow (the "what" and "how")
- Essential constraints
- 1-2 key examples
- Validation steps
- References to detailed docs (within skill directory)
Move to reference files:
- Extended background ("why" and history)
- Comprehensive API documentation
- Many examples
- Edge cases
- Troubleshooting guides
## Documentation Patterns
### Avoid Time-Sensitive Information
```markdown
# Avoid (will become outdated)
Use the new React hooks API introduced in version 16.8
# Better (timeless)
Use React hooks for state management
```
### Use Consistent Terminology
Pick terms and stick with them:
```markdown
# Inconsistent
1. Parse the document
2. Extract data from the file
3. Process the input
# Consistent
1. Parse the document
2. Extract data from the document
3. Process the document
```
### Write for the Model
Remember: Skills are for Claude, not humans.
```markdown
# Too human-centric
This is a really helpful tool that makes your life easier!
Everyone loves this workflow because it's so intuitive.
# Model-focused
Extract structured data from unstructured logs using these patterns.
```
### Provide Concrete Examples
```markdown
# Abstract
Process dates correctly.
# Concrete
Convert dates to ISO 8601 format:
- Input: "Jan 15, 2024" → Output: "2024-01-15"
- Input: "3/7/24" → Output: "2024-03-07"
```
## Tool Restrictions
### When to Restrict
Restrict tools (`allowed-tools`) when:
1. **Safety-critical operations**: Prevent unintended modifications
```yaml
allowed-tools: [Read, Grep, Glob] # Read-only analysis
```
2. **Enforcing workflow**: Must use specific tools in order
```yaml
allowed-tools: [Bash] # Only run provided scripts
```
3. **Compliance**: Must not modify certain files
```yaml
allowed-tools: [Read, Grep] # Audit mode
```
### Common Patterns
```yaml
# Analysis only
allowed-tools: [Read, Grep, Glob]
# File operations
allowed-tools: [Read, Write, Edit, Glob, Grep]
# Development
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
# Script execution
allowed-tools: [Bash, Read]
```
### Don't Over-Restrict
```yaml
# Too restrictive (Claude can't be effective)
allowed-tools: [Read]
# Better (if editing is needed)
allowed-tools: [Read, Edit, Grep, Glob]
```
## Script Best Practices
### When to Use Scripts
Use scripts for:
- Deterministic operations (same input → same output)
- Complex calculations
- API calls
- System operations
- Validation logic
Don't use scripts for:
- What Claude can do better (analysis, decision-making)
- Simple operations
- One-off tasks
### Script Structure
```python
#!/usr/bin/env python3
"""
Brief description of what this script does.
Usage:
python script.py input.json output.json
Exit codes:
0: Success
1: Validation error
2: File error
"""
import sys
import json
def main():
# Clear error handling
if len(sys.argv) != 3:
print("Usage: script.py input.json output.json", file=sys.stderr)
sys.exit(1)
# Validate inputs
# Process data
# Output results
if __name__ == "__main__":
main()
```
### Script Documentation
In SKILL.md:
```markdown
## Validation
Run `scripts/validate.py` to verify output format:
\`\`\`bash
python scripts/validate.py output.json
\`\`\`
Returns exit code 0 on success, 1 on validation errors.
```
## Testing Skills
### Create Test Scenarios
Before writing extensive documentation:
```markdown
# Test scenarios
1. Input: Simple case
Expected: Standard output
2. Input: Edge case (empty file)
Expected: Handle gracefully
3. Input: Invalid data
Expected: Clear error message
```
### Iterative Development
1. Start with minimal SKILL.md
2. Test with Claude on real task
3. Note what Claude struggles with
4. Add specific guidance for those areas
5. Repeat until effective
### Evaluation Questions
- Does Claude discover the skill appropriately?
- Does Claude understand when NOT to use it?
- Are outputs consistent and correct?
- Does Claude handle edge cases?
- Is the skill too restrictive or too loose?
## Common Mistakes
### Mistake 1: Over-Explaining
```markdown
# Bad
The Read tool is a powerful capability that allows you to read files.
You should use it when you need to access file contents. Files are
stored on disk and contain data...
# Good
Read the configuration file and extract the database settings.
```
### Mistake 2: Vague Descriptions
```yaml
# Bad
description: Helps with things
# Good
description: Converts CSV sales data to quarterly revenue reports with charts
```
### Mistake 3: Missing Examples
```markdown
# Bad
Format the output appropriately.
# Good
Format output as JSON:
{
"metric": "response_time",
"value": 245,
"unit": "ms"
}
```
### Mistake 4: No Validation
```markdown
# Bad
1. Parse config
2. Apply changes
3. Done
# Good
1. Parse config
2. Validate required fields: api_key, endpoint, timeout
3. Apply changes
4. Verify: curl endpoint returns 200
```
### Mistake 5: Monolithic SKILL.md
```markdown
# Bad: Everything in SKILL.md (800 lines)
[200 lines of background]
[300 lines of API docs]
[300 lines of examples]
# Good: Progressive disclosure
# SKILL.md (200 lines)
- Core workflow
- Key example
- Reference to `reference/api-docs.md`
- Reference to `reference/examples.md`
```
## Skill Maintenance
### Versioning
If distributing via plugin:
- Increment plugin version in `plugin.json`
- Document changes in plugin changelog
- Test with current Claude model
### Evolution
As skills mature:
1. Monitor usage patterns
2. Refine based on real usage
3. Add missing edge cases
4. Remove unnecessary verbosity
5. Update examples
### Deprecation
When deprecating:
1. Update description: "DEPRECATED: Use skill-name-v2 instead"
2. Keep functional for transition period
3. Document migration path
4. Remove after transition
## Performance Optimization
### Reduce Token Usage
```markdown
# Higher token usage
Detailed explanation of every step with comprehensive background
information that Claude likely already knows from pre-training.
# Optimized
[Concise instructions referencing detailed docs in reference/ as needed]
```
### Faster Discovery
Make skills discoverable with specific descriptions:
```yaml
# Faster discovery (specific terms)
description: Processes Stripe webhook events for payment.succeeded and payment.failed
# Slower discovery (vague)
description: Handles webhooks
```
## Collaboration
### Team Skills
When creating skills for teams:
- Document project-specific conventions
- Include team workflow patterns
- Reference team tools and systems
- Use consistent terminology across team skills
### Skill Libraries
Organize related skills:
```
.claude/skills/
├── data-processing/
│ ├── csv-processor/
│ ├── json-transformer/
│ └── xml-parser/
└── code-generation/
├── react-components/
└── api-endpoints/
```
## Advanced Patterns
### Skill Composition
Reference other skills:
```markdown
This skill builds on the "Processing CSVs" skill.
First use that skill to parse the data, then apply the transformations below.
```
### Conditional Workflows
```markdown
If dataset < 1000 rows:
Process in-memory using standard algorithm
If dataset >= 1000 rows:
1. Split into chunks of 1000 rows
2. Process each chunk
3. Aggregate results
```
### Feedback Loops
```markdown
1. Generate initial output
2. Validate against schema
3. If validation fails:
- Review error messages
- Adjust output
- Re-validate
4. Repeat until valid
```
## Checklist for High-Quality Skills
Before finalizing a skill:
- [ ] Name uses gerund form and is specific
- [ ] Description is clear, specific, includes key terms
- [ ] SKILL.md is under 500 lines
- [ ] Examples are concrete and helpful
- [ ] Validation steps are included
- [ ] Tool restrictions are appropriate (if any)
- [ ] Scripts have error handling and documentation
- [ ] Reference files are well-organized
- [ ] Tested with real scenarios
- [ ] No time-sensitive information
- [ ] Consistent terminology throughout
- [ ] Clear when to use / when not to use
## Key Principles Summary
1. **Be concise**: Only what Claude doesn't know
2. **Be specific**: Clear names, descriptions, examples
3. **Be practical**: Test with real scenarios
4. **Be progressive**: Start simple, add detail as needed
5. **Be consistent**: Terminology, formatting, style
6. **Be validated**: Include verification steps
7. **Be discovered**: Specific descriptions with key terms
8. **Be maintained**: Update based on usage
Remember: Skills are extensions of Claude's capabilities. Make them focused, discoverable, and effective by following these practices.

815
skills/skill-builder/reference/examples.md Normal file
View File

@@ -0,0 +1,815 @@
# Skill Examples
Real-world examples of well-crafted skills demonstrating best practices.
## Example 1: Simple Focused Skill
A single-purpose skill with everything in SKILL.md.
### Directory Structure
```
changelog-generator/
└── SKILL.md
```
### SKILL.md
```markdown
---
name: Generating Changelog Entries
description: Creates standardized changelog entries from git commits following Keep a Changelog format with semantic versioning categories
---
# Generating Changelog Entries
Creates changelog entries in Keep a Changelog format from git commit history.
## Workflow
1. Review git commits since last release
2. Categorize commits:
- **Added**: New features
- **Changed**: Changes to existing functionality
- **Deprecated**: Soon-to-be removed features
- **Removed**: Removed features
- **Fixed**: Bug fixes
- **Security**: Security improvements
3. Format as markdown under appropriate headings
4. Include commit hashes as references
## Output Format
\`\`\`markdown
## [Version] - YYYY-MM-DD
### Added
- New feature description [abc123]
### Fixed
- Bug fix description [def456]
\`\`\`
## Examples
### Input Commits
```
abc123 feat: Add user authentication
def456 fix: Resolve login timeout issue
ghi789 docs: Update README
```
### Output
```markdown
## [1.2.0] - 2024-01-15
### Added
- User authentication system [abc123]
### Fixed
- Login timeout issue [def456]
```
## Validation
Ensure:
- All commits are categorized
- Date is in YYYY-MM-DD format
- Version follows semantic versioning
- Each entry includes commit hash
```
**Why this works**:
- Focused on one task
- Clear categorization
- Specific format
- Concrete example
- Validation checklist
## Example 2: Skill with Reference Documentation
A skill using progressive disclosure for complex information.
### Directory Structure
```
api-doc-generator/
├── SKILL.md
└── reference/
├── jsdoc-patterns.md
└── openapi-spec.md
```
### SKILL.md
```markdown
---
name: Generating API Documentation
description: Creates comprehensive API documentation from JSDoc comments including endpoints, parameters, responses, and examples in OpenAPI 3.0 format
---
# Generating API Documentation
Generates API documentation in OpenAPI 3.0 format from JSDoc-annotated code.
## Overview
Extracts API information from JSDoc comments and produces OpenAPI specification with:
- Endpoint descriptions
- Request/response schemas
- Authentication requirements
- Example payloads
## Workflow
1. Scan codebase for JSDoc-annotated API endpoints
2. Extract route, method, parameters, responses
3. Generate OpenAPI schema definitions
4. Create example requests/responses
5. Validate against OpenAPI 3.0 specification
## JSDoc Pattern
Expected JSDoc format:
\`\`\`javascript
/**
* @api {get} /users/:id Get User
* @apiParam {String} id User ID
* @apiSuccess {Object} user User object
* @apiSuccess {String} user.name User name
*/
\`\`\`
For detailed JSDoc patterns, see `reference/jsdoc-patterns.md`.
## Output Format
Generate OpenAPI 3.0 YAML. For complete specification reference, see `reference/openapi-spec.md`.
Basic structure:
\`\`\`yaml
openapi: 3.0.0
info:
title: API Name
version: 1.0.0
paths:
/users/{id}:
get:
summary: Get User
parameters:
- name: id
in: path
required: true
schema:
type: string
\`\`\`
## Validation
1. Validate YAML syntax
2. Verify against OpenAPI 3.0 schema
3. Ensure all referenced schemas are defined
4. Check examples match schema definitions
```
### reference/jsdoc-patterns.md
```markdown
# JSDoc Patterns for API Documentation
Complete reference for supported JSDoc annotations.
## Basic Endpoint
\`\`\`javascript
/**
* @api {method} /path Description
* @apiName UniqueName
* @apiGroup GroupName
*/
\`\`\`
## Parameters
[... detailed parameter documentation ...]
## Responses
[... detailed response documentation ...]
## Examples
[... 20+ examples of different patterns ...]
```
**Why this works**:
- Core workflow in SKILL.md
- Extended details in reference files
- Clear references to additional docs
- Progressive disclosure
## Example 3: Skill with Scripts
A skill using deterministic scripts for validation.
### Directory Structure
```
invoice-processor/
├── SKILL.md
├── scripts/
│ ├── extract-data.py
│ └── validate-output.py
└── templates/
└── invoice-output.json
```
### SKILL.md
```markdown
---
name: Processing Invoice PDFs
description: Extracts structured data from invoice PDFs including vendor, date, line items, and totals with validation against expected schema
---
# Processing Invoice PDFs
Extracts and validates invoice data from PDF files.
## Workflow
1. Use `scripts/extract-data.py` to extract text from PDF
2. Parse extracted text for key fields:
- Vendor name
- Invoice number
- Date (YYYY-MM-DD)
- Line items (description, quantity, unit price, total)
- Subtotal, tax, total
3. Structure as JSON matching `templates/invoice-output.json`
4. Validate using `scripts/validate-output.py`
## Extraction Script
\`\`\`bash
python scripts/extract-data.py input.pdf output.txt
\`\`\`
Outputs raw text from PDF for parsing.
## Output Format
Follow the schema in `templates/invoice-output.json`:
\`\`\`json
{
"vendor": "Company Name",
"invoice_number": "INV-001",
"date": "2024-01-15",
"line_items": [
{
"description": "Item description",
"quantity": 2,
"unit_price": 50.00,
"total": 100.00
}
],
"subtotal": 100.00,
"tax": 8.00,
"total": 108.00
}
\`\`\`
## Validation
Run validation script:
\`\`\`bash
python scripts/validate-output.py output.json
\`\`\`
Validates:
- All required fields present
- Date format is YYYY-MM-DD
- Calculations are correct (line totals, subtotal, tax, total)
- Numbers are properly formatted
Exit code 0 = valid, 1 = validation errors (prints details).
## Error Handling
If extraction fails:
1. Check PDF is not password-protected
2. Verify PDF contains text (not scanned image)
3. Review raw extracted text for parsing issues
```
### scripts/validate-output.py
```python
#!/usr/bin/env python3
"""
Validates invoice JSON output.
Usage:
python validate-output.py invoice.json
Exit codes:
0: Valid
1: Validation errors
"""
import sys
import json
from datetime import datetime
def validate_invoice(data):
errors = []
# Required fields
required = ['vendor', 'invoice_number', 'date', 'line_items', 'total']
for field in required:
if field not in data:
errors.append(f"Missing required field: {field}")
# Date format
try:
datetime.strptime(data['date'], '%Y-%m-%d')
except ValueError:
errors.append(f"Invalid date format: {data['date']}")
# Calculate totals
calculated_total = sum(item['total'] for item in data['line_items'])
if abs(calculated_total - data['subtotal']) > 0.01:
errors.append(f"Subtotal mismatch: {data['subtotal']} != {calculated_total}")
return errors
def main():
if len(sys.argv) != 2:
print("Usage: validate-output.py invoice.json", file=sys.stderr)
sys.exit(1)
with open(sys.argv[1]) as f:
data = json.load(f)
errors = validate_invoice(data)
if errors:
print("Validation errors:", file=sys.stderr)
for error in errors:
print(f" - {error}", file=sys.stderr)
sys.exit(1)
print("Validation successful")
sys.exit(0)
if __name__ == "__main__":
main()
```
**Why this works**:
- Scripts handle deterministic operations
- Clear script usage documentation
- Template provides expected format
- Validation ensures correctness
- Error handling guidance
## Example 4: Tool-Restricted Skill
A skill with restricted tool access for safety.
### Directory Structure
```
security-audit/
└── SKILL.md
```
### SKILL.md
```markdown
---
name: Auditing Security Configurations
description: Reviews configuration files for security vulnerabilities including exposed secrets, weak permissions, and insecure defaults without modifying any files
allowed-tools: [Read, Grep, Glob]
---
# Auditing Security Configurations
Performs read-only security audit of configuration files.
## Tool Restrictions
This skill is read-only. Only these tools are available:
- Read: Read files
- Grep: Search for patterns
- Glob: Find files
This ensures no accidental modifications during security audit.
## Audit Checklist
### 1. Secrets Exposure
Search for potential secrets:
\`\`\`bash
grep -r "api_key\|password\|secret\|token" .
\`\`\`
Check for:
- Hardcoded passwords
- API keys in code
- Exposed tokens
- Committed .env files
### 2. File Permissions
Review files that should have restricted permissions:
- Private keys (.pem, .key)
- Configuration files with secrets
- Database credentials
### 3. Insecure Defaults
Check configurations for:
- Debug mode enabled in production
- CORS set to allow all origins
- Disabled authentication
- Exposed admin interfaces
## Output Format
Generate markdown report:
\`\`\`markdown
# Security Audit Report
## Critical Issues
- [Issue description] - [File:Line]
## Warnings
- [Issue description] - [File:Line]
## Recommendations
1. [Recommendation]
2. [Recommendation]
\`\`\`
## Examples
### Finding: Exposed Secret
\`\`\`
## Critical Issues
- Hardcoded API key in source code - config/api.js:12
\`\`\`
const API_KEY = "sk_live_abc123xyz"
\`\`\`
Recommendation: Move to environment variable
```
**Why this works**:
- Tool restrictions prevent modifications
- Clear audit methodology
- Structured output format
- Safety-critical workflow
## Example 5: Complex Multi-File Skill
A comprehensive skill with full progressive disclosure.
### Directory Structure
```
react-component-generator/
├── SKILL.md
├── reference/
│ ├── typescript-patterns.md
│ ├── testing-guide.md
│ └── styling-conventions.md
├── scripts/
│ └── validate-component.sh
└── templates/
├── component.tsx
├── component.test.tsx
└── component.styles.ts
```
### SKILL.md
```markdown
---
name: Creating React Components
description: Generates TypeScript React components following project conventions including component structure, PropTypes, styled-components, and comprehensive Jest tests with React Testing Library
---
# Creating React Components
Generates production-ready React components with TypeScript, tests, and styles.
## Overview
Creates a complete React component with:
- TypeScript component file
- Styled-components styling
- Jest + React Testing Library tests
- Prop validation
- JSDoc documentation
## Workflow
1. Create component file using `templates/component.tsx` as base
2. Define TypeScript interface for props
3. Implement component logic
4. Create styled-components in `templates/component.styles.ts` pattern
5. Write tests following `templates/component.test.tsx`
6. Validate with `scripts/validate-component.sh`
## Component Structure
See `templates/component.tsx` for complete structure. Key elements:
\`\`\`typescript
interface ComponentProps {
// Props with JSDoc
}
export const Component: React.FC<ComponentProps> = ({ props }) => {
// Implementation
}
\`\`\`
## TypeScript Patterns
For TypeScript best practices, see `reference/typescript-patterns.md`.
Key patterns:
- Use interfaces for props
- Avoid 'any' type
- Leverage union types for variants
- Use generics for reusable components
## Styling
Follow styled-components patterns in `reference/styling-conventions.md`.
Basic pattern from `templates/component.styles.ts`:
\`\`\`typescript
import styled from 'styled-components'
export const Container = styled.div\`
// Styles
\`
\`\`\`
## Testing
Follow testing guide in `reference/testing-guide.md`.
Use template from `templates/component.test.tsx`:
- Test rendering
- Test interactions
- Test edge cases
- Test accessibility
## Validation
Run validation:
\`\`\`bash
./scripts/validate-component.sh src/components/MyComponent
\`\`\`
Checks:
- TypeScript compiles
- Tests pass
- Linting passes
- No console errors
## File Naming
\`\`\`
src/components/MyComponent/
├── MyComponent.tsx
├── MyComponent.test.tsx
├── MyComponent.styles.ts
└── index.ts
\`\`\`
```
### reference/typescript-patterns.md
```markdown
# TypeScript Patterns for React Components
[Detailed TypeScript patterns, 200+ lines]
```
### reference/testing-guide.md
```markdown
# Testing Guide for React Components
[Comprehensive testing patterns, 300+ lines]
```
### reference/styling-conventions.md
```markdown
# Styling Conventions with styled-components
[Detailed styling patterns, 150+ lines]
```
### templates/component.tsx
```typescript
import React from 'react'
import { Container } from './ComponentName.styles'
interface ComponentNameProps {
/**
* Description of prop
*/
propName: string
}
/**
* ComponentName description
*
* @example
* <ComponentName propName="value" />
*/
export const ComponentName: React.FC<ComponentNameProps> = ({
propName
}) => {
return (
<Container>
{propName}
</Container>
)
}
```
**Why this works**:
- Concise SKILL.md (under 500 lines)
- Progressive disclosure to reference docs
- Templates provide starting points
- Validation script ensures quality
- Clear file organization
## Example 6: Workflow-Driven Skill
A skill focused on a multi-step workflow with validation.
### Directory Structure
```
database-migration/
└── SKILL.md
```
### SKILL.md
```markdown
---
name: Managing Database Migrations
description: Creates and applies database migrations with automated backup, validation, and rollback capabilities for PostgreSQL using Prisma
allowed-tools: [Read, Write, Bash, Grep, Glob]
---
# Managing Database Migrations
Safe database migration workflow with backup and rollback.
## Prerequisites
- Prisma CLI installed
- Database connection configured
- Write access to database
## Migration Workflow
### Creating a Migration
1. **Backup current schema**
\`\`\`bash
pg_dump -s database_name > backups/schema_$(date +%Y%m%d_%H%M%S).sql
\`\`\`
2. **Create migration**
\`\`\`bash
npx prisma migrate dev --name migration_name
\`\`\`
3. **Review generated SQL**
- Check migration file in `prisma/migrations/`
- Verify no unexpected changes
- Ensure data integrity preserved
4. **Validate migration**
- Test on local database first
- Verify data not corrupted
- Check application still works
### Applying to Production
1. **Create production backup**
\`\`\`bash
pg_dump database_name > backups/prod_backup_$(date +%Y%m%d_%H%M%S).sql
\`\`\`
2. **Run migration**
\`\`\`bash
npx prisma migrate deploy
\`\`\`
3. **Verify migration applied**
\`\`\`bash
npx prisma migrate status
\`\`\`
4. **Validate data integrity**
- Run integrity checks
- Verify critical queries still work
- Check row counts match expectations
### Rollback Procedure
If migration fails:
1. **Stop application** (prevent writes)
2. **Restore from backup**
\`\`\`bash
psql database_name < backups/prod_backup_TIMESTAMP.sql
\`\`\`
3. **Verify restoration**
- Check row counts
- Run test queries
- Verify application works
4. **Investigate failure**
- Review migration SQL
- Check error logs
- Fix issue before retrying
## Safety Checklist
Before applying migration:
- [ ] Local backup created
- [ ] Migration tested on development database
- [ ] Migration SQL reviewed
- [ ] Production backup created
- [ ] Rollback procedure documented
- [ ] Maintenance window scheduled (if needed)
## Validation Queries
After migration, verify:
\`\`\`sql
-- Check table exists
SELECT EXISTS (
SELECT FROM information_schema.tables
WHERE table_name = 'table_name'
);
-- Verify row counts
SELECT COUNT(*) FROM critical_table;
-- Test critical queries
SELECT * FROM users WHERE id = 1;
\`\`\`
## Common Issues
### Issue: Migration fails mid-apply
**Solution**: Restore from backup, fix migration, retry
### Issue: Data type mismatch
**Solution**: Add explicit type conversion in migration
### Issue: Foreign key constraint violation
**Solution**: Ensure related data exists or use ON DELETE CASCADE
## Examples
### Example 1: Adding a Column
\`\`\`sql
ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT false;
\`\`\`
### Example 2: Creating a Table
\`\`\`sql
CREATE TABLE audit_logs (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id),
action VARCHAR(255),
created_at TIMESTAMP DEFAULT NOW()
);
\`\`\`
```
**Why this works**:
- Clear step-by-step workflow
- Safety measures at each step
- Validation checkpoints
- Rollback procedure
- Tool restrictions for safety
- Common issues documented
## Key Takeaways from Examples
1. **Simple skills**: Everything in SKILL.md, focused on one task
2. **Reference-based skills**: Core in SKILL.md, details in reference/
3. **Scripted skills**: Use scripts for deterministic operations
4. **Tool-restricted skills**: Limit tools for safety-critical tasks
5. **Complex skills**: Full progressive disclosure with templates
6. **Workflow skills**: Step-by-step with validation and rollback
Each example demonstrates:
- Clear, specific descriptions
- Concrete examples
- Validation steps
- Appropriate level of detail
- Progressive disclosure when needed
- Focused purpose
Use these patterns as starting points for your own skills.

756
skills/skill-builder/reference/skill-review.md Normal file
View File

@@ -0,0 +1,756 @@
# Reviewing Claude Skills
Comprehensive guide for reviewing skills for correctness, best practices, adherence to conventions, and effectiveness.
## Review Objectives
When reviewing a skill, assess:
1. **Correctness**: Instructions are accurate and achievable
2. **Discoverability**: Name and description enable Claude to find and use it appropriately
3. **Clarity**: Instructions are unambiguous and specific
4. **Efficiency**: Appropriate use of progressive disclosure and conciseness
5. **Effectiveness**: Skill actually helps Claude accomplish the intended task
6. **Maintainability**: Well-organized and easy to update
## Review Checklist
Use this checklist for systematic skill reviews:
### Frontmatter & Metadata
- [ ] **Name format**: Uses gerund form (verb + -ing)
- [ ] **Name specificity**: Specific and descriptive, not vague
- [ ] **Description length**: Under 1024 characters
- [ ] **Description clarity**: Third person, specific, includes key terms
- [ ] **Description discoverability**: Contains terms that match when skill should be used
- [ ] **Tool restrictions**: `allowed-tools` used appropriately (if needed)
- [ ] **No missing fields**: Required fields present (name, description)
### File Structure
- [ ] **SKILL.md exists**: Primary file is present
- [ ] **Line count**: SKILL.md under 500 lines (excluding reference files)
- [ ] **Reference files**: Used for extended documentation (if needed)
- [ ] **File organization**: Logical structure (reference/, scripts/, templates/)
- [ ] **File naming**: Consistent and clear naming conventions
- [ ] **Templates**: Provide good starting points (if included)
- [ ] **Scripts**: Well-documented with error handling (if included)
### Content Quality
- [ ] **Conciseness**: No obvious information Claude already knows
- [ ] **Specificity**: Clear examples and concrete instructions
- [ ] **Completeness**: All necessary information included
- [ ] **Progressive disclosure**: Details in reference files, essentials in SKILL.md
- [ ] **Examples**: Concrete, helpful examples provided
- [ ] **Validation steps**: How to verify success is documented
- [ ] **Error handling**: Common issues and solutions addressed
- [ ] **Terminology**: Consistent throughout all files
### Instructions
- [ ] **Clarity**: Unambiguous and specific
- [ ] **Actionability**: Each step is actionable
- [ ] **Appropriate freedom**: Right level of specificity for task type
- [ ] **Workflow**: Logical sequence of steps
- [ ] **Prerequisites**: Dependencies and requirements stated
- [ ] **Output format**: Expected outputs clearly defined
- [ ] **Validation**: Verification steps included
### Documentation
- [ ] **No time-sensitive info**: No version numbers or dates that become outdated
- [ ] **Model-focused**: Written for Claude, not humans
- [ ] **No redundancy**: Information not duplicated across files
- [ ] **Clear references**: References to other files are specific and helpful
- [ ] **Up-to-date**: Information is current and accurate
## Detailed Review Guidelines
### 1. Reviewing Name and Description
The name and description determine discoverability. Poor naming means the skill won't be used.
#### Name Review
**Check for gerund form**:
```yaml
# Good
name: Processing Invoice PDFs
name: Generating API Documentation
name: Analyzing Performance Metrics
# Bad (fix these)
name: Invoice Processor
name: API Docs
name: Performance
```
**Check for specificity**:
```yaml
# Good
name: Creating React Components
name: Managing Database Migrations
# Too vague (needs improvement)
name: Helper Functions
name: Utilities
name: Manager
```
**Action**: If name is vague, suggest specific alternative based on what the skill actually does.
#### Description Review
**Check for key terms**:
```yaml
# Good - includes specific technologies and outputs
description: Generates TypeScript React components following project conventions including component structure, PropTypes, styled-components, and comprehensive Jest tests with React Testing Library
# Bad - too vague, missing key terms
description: Helps create components
# Fix needed - add specific technologies and what it produces
```
**Check for third person**:
```yaml
# Good
description: Creates standardized changelog entries from git commits
# Bad (imperative, not third person)
description: Create standardized changelog entries from git commits
```
**Check length**:
```yaml
# If over 1024 characters, needs to be condensed
# Keep key terms, remove unnecessary words
```
**Action**: Rewrite vague descriptions to include:
- Specific action (what it does)
- Key technologies/tools involved
- Output format or result
- Important constraints or validation
### 2. Reviewing File Structure
Good file organization enables maintenance and progressive disclosure.
#### SKILL.md Length
**Check line count**:
```bash
wc -l SKILL.md
```
If over 500 lines:
- Identify content that could move to reference files
- Look for extended examples → `reference/examples.md`
- Look for API documentation → `reference/api-docs.md`
- Look for background information → separate reference file
#### Reference File Organization
**Good structure**:
```
my-skill/
├── SKILL.md # Under 500 lines, essential info
├── reference/
│ ├── detailed-guide.md # Extended documentation
│ └── examples.md # Many examples
├── scripts/
│ └── helper.py # Well-documented scripts
└── templates/
└── output.json # Clear templates
```
**Issues to flag**:
```
my-skill/
├── SKILL.md # 800 lines - TOO LONG
├── stuff/ # Vague directory name
│ └── things.md # Vague file name
└── script.py # No documentation
```
**Action**: Recommend reorganization with specific suggestions for what to move where.
### 3. Reviewing Instructions
Instructions must be clear, actionable, and appropriately specific.
#### Clarity Check
**Look for ambiguity**:
```markdown
# Ambiguous
Process the files appropriately.
# Clear
Extract the date field from the first line of each file using format YYYY-MM-DD.
```
**Look for missing steps**:
```markdown
# Incomplete
1. Read the data
2. Output results
# Complete
1. Read the data from input.json
2. Validate required fields: id, name, email
3. Transform to output format (see examples below)
4. Write to output.json
5. Verify with validation script
```
#### Degrees of Freedom Check
**Too restrictive** (micromanaging):
```markdown
# Bad - over-specified
1. Open the file
2. Read line 1
3. Store in a variable called 'firstLine'
4. Parse the date from firstLine
5. Store in a variable called 'parsedDate'
# Better - appropriate specificity
Extract the date from the first line using format YYYY-MM-DD.
```
**Too loose** (for fragile operations):
```markdown
# Bad - too vague for database migration
Apply the database migration.
# Better - specific steps for fragile operation
1. Backup database: pg_dump db > backup_$(date +%Y%m%d).sql
2. Run migration: npm run migrate:up
3. Verify schema_version table updated
4. If verification fails, rollback: psql db < backup_TIMESTAMP.sql
```
**Action**: Identify whether freedom level matches task fragility and suggest adjustments.
#### Validation Review
Every skill should include validation steps.
**Missing validation** (needs improvement):
```markdown
## Workflow
1. Parse configuration
2. Apply settings
3. Restart service
```
**Includes validation** (good):
```markdown
## Workflow
1. Parse configuration
2. Validate required fields: host, port, api_key
3. Apply settings
4. Verify service started successfully (check port is listening)
```
**Action**: If validation is missing, suggest specific validation steps appropriate to the task.
### 4. Reviewing Examples
Examples should be concrete and helpful.
#### Example Quality
**Poor example** (too abstract):
```markdown
Extract the data appropriately.
```
**Good example** (concrete):
```markdown
Extract dates to ISO 8601 format:
- Input: "Jan 15, 2024" → Output: "2024-01-15"
- Input: "3/7/24" → Output: "2024-03-07"
- Input: "2024-12-25" → Output: "2024-12-25" (already correct)
```
#### Example Coverage
Check that examples cover:
- [ ] Basic/common case
- [ ] Edge cases (if applicable)
- [ ] Input → Output transformations
- [ ] Expected formats
**Action**: If examples are missing or too abstract, suggest concrete examples based on the skill's purpose.
### 5. Reviewing Progressive Disclosure
Skills should start concise and reference detailed docs as needed.
#### Good Progressive Disclosure
```markdown
# SKILL.md (concise)
## Workflow
1. Extract API information from JSDoc comments
2. Generate OpenAPI 3.0 specification
3. Validate against schema
For detailed JSDoc patterns, see `reference/jsdoc-patterns.md`.
For complete OpenAPI specification reference, see `reference/openapi-spec.md`.
# reference/jsdoc-patterns.md (detailed)
[200+ lines of JSDoc patterns and examples]
# reference/openapi-spec.md (detailed)
[300+ lines of OpenAPI documentation]
```
#### Poor Progressive Disclosure
```markdown
# SKILL.md (monolithic - 800 lines)
[Everything crammed into one file]
[200 lines of background]
[300 lines of detailed API docs]
[300 lines of examples]
```
**Action**: Identify sections that should move to reference files and suggest the organization.
### 6. Reviewing Tool Restrictions
Tool restrictions should be intentional and appropriate.
#### When Tool Restrictions Are Appropriate
**Read-only analysis**:
```yaml
allowed-tools: [Read, Grep, Glob]
```
✅ Good for security audits, code analysis, reporting
**File operations without execution**:
```yaml
allowed-tools: [Read, Write, Edit, Glob, Grep]
```
✅ Good for file transformations, code generation
**Safety-critical workflows**:
```yaml
allowed-tools: [Read, Bash] # Only run specific scripts
```
✅ Good for database migrations with pre-built scripts
#### Issues to Flag
**Over-restricted**:
```yaml
allowed-tools: [Read]
```
❌ Too restrictive - Claude can't be effective with only Read
**Unnecessary restrictions**:
```yaml
# For a component generator that needs to write files
allowed-tools: [Read, Grep]
```
❌ Missing necessary tools (Write, Edit)
**Action**: Verify tool restrictions match the skill's purpose and suggest adjustments.
### 7. Reviewing Scripts
Scripts should be well-documented and robust.
#### Script Documentation
**Poor documentation**:
```python
#!/usr/bin/env python3
import sys
import json
def main():
data = json.load(open(sys.argv[1]))
# ... processing ...
```
**Good documentation**:
```python
#!/usr/bin/env python3
"""
Validates invoice JSON output.
Usage:
python validate-output.py invoice.json
Exit codes:
0: Valid
1: Validation errors
2: File not found
"""
import sys
import json
def main():
if len(sys.argv) != 2:
print("Usage: validate-output.py invoice.json", file=sys.stderr)
sys.exit(1)
# ... processing with error handling ...
```
#### Script Error Handling
Check for:
- [ ] Argument validation
- [ ] Clear error messages
- [ ] Appropriate exit codes
- [ ] File handling errors
- [ ] Input validation
**Action**: Note missing error handling and documentation issues.
### 8. Reviewing Content Quality
#### Conciseness Check
**Over-explained** (Claude already knows this):
```markdown
The Read tool is a powerful capability that allows you to read files
from the filesystem. You should use it when you need to access file
contents. Files are stored on disk and contain data...
```
**Concise** (appropriate):
```markdown
Read the configuration file and extract database settings.
```
**Action**: Flag over-explained content that Claude already knows.
#### Time-Sensitive Information
**Avoid**:
```markdown
Use the new React hooks API introduced in version 16.8 (2019)
```
**Better**:
```markdown
Use React hooks for state management
```
**Action**: Flag time-sensitive references that will become outdated.
#### Terminology Consistency
**Inconsistent** (confusing):
```markdown
1. Parse the document
2. Extract data from the file
3. Process the input
4. Transform the content
```
**Consistent** (clear):
```markdown
1. Parse the document
2. Extract data from the document
3. Validate the document
4. Transform the document
```
**Action**: Note terminology inconsistencies and suggest consistent terms.
## Common Review Findings
### Critical Issues (Must Fix)
1. **Missing or vague description**: Skill won't be discovered
2. **No validation steps**: No way to verify success
3. **Ambiguous instructions**: Claude won't know what to do
4. **Over 500 lines in SKILL.md**: Needs progressive disclosure
5. **Broken references**: References to non-existent files
6. **Scripts without error handling**: Will fail ungracefully
### Important Issues (Should Fix)
1. **Vague examples**: Replace with concrete examples
2. **Inappropriate freedom level**: Too restrictive or too loose
3. **Missing edge cases**: Common issues not addressed
4. **Poor file organization**: Unclear structure
5. **Time-sensitive information**: Will become outdated
6. **Inconsistent terminology**: Confusing
### Minor Issues (Nice to Fix)
1. **Could be more concise**: Some unnecessary verbosity
2. **Could use better examples**: Examples work but could be clearer
3. **Minor naming improvements**: Name is okay but could be more specific
4. **Documentation could be clearer**: Functional but could improve
## Review Process
### Step-by-Step Review
1. **Initial scan**
- Read frontmatter
- Check file structure
- Note line count
2. **Name & description review**
- Check gerund form
- Assess specificity
- Verify key terms present
- Test mental model: "Would Claude find this when needed?"
3. **Structure review**
- Check SKILL.md length
- Review file organization
- Assess progressive disclosure
- Verify references are valid
4. **Content review**
- Read through instructions
- Check for clarity and specificity
- Verify examples are concrete
- Assess degrees of freedom
- Look for validation steps
5. **Technical review**
- Review tool restrictions (if any)
- Check scripts (if any)
- Verify templates (if any)
- Test any examples
6. **Quality review**
- Check for over-explanation
- Look for time-sensitive info
- Verify terminology consistency
- Assess overall effectiveness
### Writing Review Feedback
Structure feedback as:
```markdown
## Skill Review: [Skill Name]
### Critical Issues
- [Issue 1 with specific location]
- [Issue 2 with specific location]
### Important Issues
- [Issue 1 with suggestion]
- [Issue 2 with suggestion]
### Suggestions
- [Optional improvement 1]
- [Optional improvement 2]
### Strengths
- [What works well]
- [Good patterns to maintain]
### Overall Assessment
[Brief summary and recommendation: Approve / Needs revision / Major rework needed]
```
## Example Reviews
### Example 1: Skill with Issues
**SKILL.md**:
```yaml
---
name: Helper
description: Helps with stuff
---
# Helper
This skill helps you process things.
## Instructions
1. Read the files
2. Do the processing
3. Output results
```
**Review**:
```markdown
## Skill Review: Helper
### Critical Issues
- **Vague name**: "Helper" doesn't indicate what the skill does. Change to gerund form describing the specific task (e.g., "Processing Invoice Data", "Generating Reports")
- **Non-descriptive description**: "Helps with stuff" provides no discoverability. Should specify what is being processed, input format, output format, and key technologies
- **Ambiguous instructions**: Steps 1-3 are too vague. What files? What processing? What output format?
### Important Issues
- **No validation**: No way to verify the output is correct
- **No examples**: No concrete examples of input → output
- **Missing specifics**: No file formats, no output structure, no error handling
### Suggestions
- Add concrete examples showing expected inputs and outputs
- Define specific file formats and output structure
- Include validation steps
- Consider what Claude doesn't already know and focus on that
### Overall Assessment
Major rework needed. The skill needs a complete rewrite with specific name, detailed description, clear instructions, and concrete examples.
```
### Example 2: Good Skill
**SKILL.md**:
```yaml
---
name: Generating Changelog Entries
description: Creates standardized changelog entries from git commits following Keep a Changelog format with semantic versioning categories
---
# Generating Changelog Entries
Creates changelog entries in Keep a Changelog format from git commit history.
## Workflow
1. Review git commits since last release
2. Categorize commits:
- **Added**: New features
- **Changed**: Changes to existing functionality
- **Fixed**: Bug fixes
3. Format as markdown under appropriate headings
4. Include commit hashes as references
## Output Format
\`\`\`markdown
## [Version] - YYYY-MM-DD
### Added
- New feature description [abc123]
### Fixed
- Bug fix description [def456]
\`\`\`
## Validation
Ensure:
- All commits are categorized
- Date is in YYYY-MM-DD format
- Version follows semantic versioning
- Each entry includes commit hash
```
**Review**:
```markdown
## Skill Review: Generating Changelog Entries
### Strengths
- **Clear name**: Gerund form, specific task
- **Excellent description**: Specific format (Keep a Changelog), includes key terms (semantic versioning, categories)
- **Concrete workflow**: Clear categorization with examples
- **Output format**: Specific format with example
- **Validation included**: Clear checklist for verification
- **Appropriate length**: Concise, focused, under 500 lines
### Suggestions
- Consider adding an example section showing sample commits → output transformation
- Could mention how to handle commits that don't fit standard categories (e.g., docs, chores)
### Overall Assessment
Excellent skill. Follows all best practices. Ready to use. The minor suggestions are optional enhancements.
```
## Reviewing Your Own Skills
Self-review checklist:
1. **Wait before reviewing**: Review skills after a break, not immediately after writing
2. **Test with Claude**: Actually use the skill and see if it works as intended
3. **Check against checklist**: Use the complete review checklist above
4. **Read aloud**: Unclear writing becomes obvious when read aloud
5. **Compare to examples**: Does it match the quality of the example skills?
6. **Ask key questions**:
- Would Claude find this skill when needed?
- Are the instructions clear enough to follow?
- Is there enough information but not too much?
- Can success be verified?
## Review Anti-Patterns
Avoid these when reviewing:
### Anti-Pattern 1: Accepting Vague Descriptions
```yaml
# Don't accept this
description: Utility for processing data
# Require this level of specificity
description: Transforms CSV sales data to quarterly JSON reports with revenue calculations and trend analysis
```
### Anti-Pattern 2: Overlooking Missing Validation
Every skill needs validation steps. Don't approve skills without them.
### Anti-Pattern 3: Accepting Monolithic Skills
Skills over 500 lines need progressive disclosure. Don't accept:
```
skill/
└── SKILL.md (800 lines)
```
Require:
```
skill/
├── SKILL.md (200 lines)
└── reference/
└── detailed-guide.md (600 lines)
```
### Anti-Pattern 4: Ignoring Ambiguity
Don't overlook vague instructions like "Process appropriately" or "Handle correctly". Require specificity.
### Anti-Pattern 5: Skipping Real-World Testing
Don't approve skills based only on reading. Test them with Claude on actual tasks.
## Quick Review Reference
Use this quick reference during reviews:
**Name**: Gerund form? Specific? ✓
**Description**: Under 1024 chars? Key terms? Third person? ✓
**Length**: SKILL.md under 500 lines? ✓
**Examples**: Concrete? Helpful? ✓
**Validation**: Steps included? ✓
**Clarity**: Unambiguous? Actionable? ✓
**Freedom**: Appropriate for task type? ✓
**Organization**: Logical structure? ✓
**Scripts**: Documented? Error handling? ✓
**References**: Valid? Clear purpose? ✓
## Conclusion
Effective skill review ensures:
- Skills are discoverable when needed
- Instructions are clear and actionable
- Examples are concrete and helpful
- Validation steps ensure correctness
- Organization supports maintainability
- Content is concise and focused
Use this guide systematically to review skills and provide constructive, specific feedback that improves skill quality.

448
skills/skill-builder/reference/skill-structure.md Normal file
View File

@@ -0,0 +1,448 @@
# Skill Structure Reference
Complete guide to organizing and structuring Claude Code skills for maximum effectiveness.
## Directory Locations
Skills can be placed in three locations:
### Personal Skills
- **Location**: `~/.claude/skills/`
- **Scope**: Available across all projects for the user
- **Use case**: Personal utilities, workflows, preferences
### Project Skills
- **Location**: `.claude/skills/`
- **Scope**: Project-specific, shared via version control
- **Use case**: Team workflows, project conventions, tooling
### Plugin Skills
- **Location**: Within plugin `skills/` directory
- **Scope**: Bundled with plugin, shareable via plugin marketplace
- **Use case**: Reusable capabilities for distribution
## Required Structure
### Minimum Viable Skill
```
my-skill/
└── SKILL.md
```
The only required file is `SKILL.md` with YAML frontmatter:
```yaml
---
name: Skill Name
description: One-line description of what this skill does
---
# Skill content and instructions
```
### Frontmatter Fields
#### Required
- `name`: Human-readable name (max 64 characters)
- Use gerund form: "Processing", "Analyzing", "Creating"
- Be specific, avoid vague terms
- `description`: One-line explanation (max 1024 characters)
- Third person: "Guides...", "Helps...", "Provides..."
- Include key terms for discoverability
- Specify when to use this skill
#### Optional
- `allowed-tools`: Array of tool names to restrict access
```yaml
allowed-tools: [Read, Grep, Glob, Bash]
```
- Use for safety-critical operations
- Use for read-only analysis
- Omit to allow all tools
## Progressive Disclosure Structure
For complex skills, organize supporting materials:
```
my-skill/
├── SKILL.md # Entry point (concise)
├── reference/ # Detailed documentation
│ ├── concepts.md # Background information
│ ├── api-reference.md # API/interface details
│ └── examples.md # Extended examples
├── scripts/ # Utility scripts
│ ├── validator.py # Validation logic
│ └── formatter.sh # Formatting helper
└── templates/ # Starter templates
├── output.json # Expected output format
└── config.yaml # Configuration template
```
### When to Use Each Directory
#### `reference/`
Use for detailed documentation that supports SKILL.md:
- Comprehensive API documentation
- Extended conceptual explanations
- Additional examples and use cases
- Specification documents
- Background context
**Pattern**: Reference from SKILL.md with phrases like:
- "For detailed API documentation, see `reference/api-reference.md`"
- "See `reference/examples.md` for more examples"
#### `scripts/`
Use for executable utilities that perform deterministic operations:
- Data validation
- Format conversion
- File processing
- API calls
- System operations
**Best practices**:
- Handle errors explicitly
- Provide clear output/error messages
- Make scripts idempotent when possible
- Document script usage in SKILL.md or reference files
- Make scripts executable: `chmod +x scripts/script.py`
- Include proper shebang: `#!/usr/bin/env python3`
**Referencing scripts in SKILL.md**:
- Use **relative paths** from SKILL.md location: `[script.py](scripts/script.py)`
- Use **standard Markdown link syntax** for Claude to reference
- In bash code blocks, use **full absolute paths** for execution examples
- **NO special @ syntax** needed
Example in SKILL.md:
```markdown
### compare_runs.py
Run [scripts/compare_runs.py](scripts/compare_runs.py) to compare test results:
```bash
.claude/skills/bfcl-results/scripts/compare_runs.py baseline/ modified/ test_name
```
```
#### `templates/`
Use for starter files and examples:
- Output format examples
- Configuration templates
- Code scaffolding
- Document structures
**Pattern**: Reference in instructions:
- "Use `templates/output.json` as the output format"
- "Start with `templates/component.tsx` structure"
## File Organization Patterns
### Pattern 1: Simple Focused Skill
Best for single-purpose, straightforward skills:
```
focused-skill/
└── SKILL.md
```
All instructions in one concise file.
### Pattern 2: Documented Skill
For skills needing additional context:
```
documented-skill/
├── SKILL.md
└── reference/
└── details.md
```
Core instructions in SKILL.md, extended details in reference.
### Pattern 3: Scripted Skill
For skills with deterministic operations:
```
scripted-skill/
├── SKILL.md
└── scripts/
├── process.py
└── validate.sh
```
Instructions in SKILL.md, automation in scripts.
### Pattern 4: Complete Skill
For comprehensive, production-ready skills:
```
complete-skill/
├── SKILL.md
├── reference/
│ ├── concepts.md
│ ├── api-docs.md
│ └── examples.md
├── scripts/
│ ├── validator.py
│ └── helper.sh
└── templates/
└── output.json
```
Full progressive disclosure with all supporting materials.
## Content Organization in SKILL.md
### Recommended Structure
```markdown
---
name: Skill Name
description: Clear, specific description
---
# Skill Name
Brief introduction explaining what this skill does.
## Core Concepts
Essential background (if needed, otherwise move to reference/)
## Instructions
Step-by-step guidance or workflow
## Examples
2-3 concrete examples showing usage
## Validation
How to verify success or check results
## References
- `reference/file.md`: Description of what's there
- `scripts/script.py`: What the script does
```
### Content Guidelines
**Keep in SKILL.md**:
- Essential instructions
- Core workflow steps
- Key examples
- Critical constraints
- References to additional files
**Move to reference files**:
- Extensive background
- Comprehensive API docs
- Many examples
- Edge cases and variations
- Historical context
## Tool Restrictions
Control which tools Claude can use within the skill:
### Syntax
```yaml
---
name: Skill Name
description: Description here
allowed-tools: [ToolName1, ToolName2]
---
```
### Common Tool Sets
#### Read-Only Analysis
```yaml
allowed-tools: [Read, Grep, Glob]
```
#### File Operations
```yaml
allowed-tools: [Read, Write, Edit, Glob, Grep]
```
#### Development Tasks
```yaml
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
```
#### Script Execution Only
```yaml
allowed-tools: [Bash]
```
### When to Restrict Tools
Restrict tools when:
- Safety is critical (prevent unintended changes)
- Skill is analysis-only (no modifications needed)
- Enforcing specific workflow (must use provided scripts)
- Testing or validation (read-only verification)
## Naming Conventions
### Skill Directory Names
- Use kebab-case: `my-skill-name`
- Be descriptive: `react-component-generator` not `helper`
- Indicate purpose: `pdf-invoice-processor`
### File Naming
- SKILL.md: Always uppercase, always this name
- Reference files: Descriptive, kebab-case: `api-reference.md`
- Scripts: Descriptive, indicate function: `validate-output.py`
- Templates: Indicate what they template: `component-template.tsx`
### Name Field (in frontmatter)
- Use gerund form: "Processing PDFs"
- Title case: "Creating React Components"
- Specific and descriptive
## Size Guidelines
### SKILL.md
- Target: 200-400 lines
- Maximum: 500 lines
- If approaching max, move content to reference files
### Reference Files
- Keep focused on one topic per file
- Split large references into multiple files
- No hard limit, but stay organized
### Scripts
- One responsibility per script
- Document usage at top of file
- Keep maintainable
## Version Control
### What to Include
- All skill files (SKILL.md, reference, scripts, templates)
- README.md explaining the skill (optional but helpful)
- Tests for scripts (if applicable)
### What to Exclude
- Generated outputs
- User-specific configurations
- Temporary files
- Cache files
### Git Best Practices
```gitignore
# In skill directory
*.pyc
__pycache__/
.DS_Store
*.tmp
cache/
```
## Testing Your Structure
Verify your skill structure:
1. **Completeness**: SKILL.md exists with required frontmatter
2. **Clarity**: Name and description are specific
3. **Organization**: Supporting files are logically organized
4. **References**: All file references in SKILL.md are valid
5. **Scripts**: All scripts are executable and documented
6. **Size**: SKILL.md is under 500 lines
## Migration Patterns
### From Monolithic to Progressive
If SKILL.md is too large:
1. Identify sections that could be separate files
2. Create reference directory
3. Move sections to focused reference files
4. Update SKILL.md with references
5. Keep core workflow in SKILL.md
Example:
```markdown
# Before (in SKILL.md)
## API Documentation
[50 lines of API details]
# After (in SKILL.md)
## API Documentation
See `reference/api-reference.md` for complete API documentation.
```
### From Simple to Scripted
Adding automation:
1. Identify deterministic operations
2. Create scripts directory
3. Implement operations in scripts
4. Update SKILL.md to reference scripts
5. Add error handling to scripts
Example:
```markdown
# Before
Validate the output format matches the expected schema.
# After
Run `scripts/validate-output.py` to verify the output format.
```
## Advanced Patterns
### Multi-Language Scripts
```
skill/
├── SKILL.md
└── scripts/
├── process.py # Python for data processing
├── validate.sh # Bash for quick checks
└── analyze.js # Node for JSON operations
```
### Conditional References
```markdown
For basic usage, follow the instructions above.
For advanced scenarios, see:
- `reference/advanced-patterns.md`: Complex workflows
- `reference/error-handling.md`: Troubleshooting guide
```
### Shared Resources
```
skills/
├── skill-one/
│ └── SKILL.md
├── skill-two/
│ └── SKILL.md
└── shared/
├── common-scripts/
└── common-templates/
```
Reference shared resources with relative paths:
```markdown
Use `../shared/common-templates/output.json` as the format.
```
## Key Takeaways
1. Only SKILL.md is required
2. Use progressive disclosure for complex skills
3. Keep SKILL.md under 500 lines
4. Organize supporting files logically
5. Reference additional files clearly
6. Use scripts for deterministic operations
7. Restrict tools when appropriate
8. Follow naming conventions consistently
9. Test structure before distributing
10. Evolve structure as skill complexity grows