Initial commit
This commit is contained in:
Zhongwei Li
286
skills/skill-builder/SKILL.md
Normal file
286
skills/skill-builder/SKILL.md
Normal file
@@ -0,0 +1,286 @@
|
||||
---
|
||||
name: Creating and Editing Claude Skills
|
||||
description: Use before creating or editing any SKILL.md files, and immediately after making skill changes to verify quality. Invoked when user asks about skill structure, descriptions, or best practices. Provides expert guidance on naming, descriptions for discoverability, progressive context reveal, and validation workflows. Critical for ensuring skills are discoverable and effective - prevents poorly structured skills that Claude won't use properly.
|
||||
---
|
||||
|
||||
# Writing Claude Skills
|
||||
|
||||
This skill provides comprehensive guidance for creating high-quality Claude Code skills that are modular, discoverable, and effective.
|
||||
|
||||
## What Are Claude Skills?
|
||||
|
||||
Skills are modular capabilities that extend Claude's functionality. They are:
|
||||
- **Model-invoked**: Claude autonomously decides when to use them based on descriptions
|
||||
- **Discoverable**: Found through descriptive `SKILL.md` files
|
||||
- **Shareable**: Can be personal, project-specific, or plugin-bundled
|
||||
|
||||
Skills differ from slash commands (user-invoked) - they're capabilities Claude chooses to use.
|
||||
|
||||
## Core Structure
|
||||
|
||||
Every skill requires a directory containing `SKILL.md` with YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Your Skill Name
|
||||
description: Clear, specific one-line description
|
||||
---
|
||||
|
||||
# Instructions and content
|
||||
```
|
||||
|
||||
For detailed structure information including optional files, see `reference/skill-structure.md`.
|
||||
|
||||
## Key Principles
|
||||
|
||||
### 1. Be Concise
|
||||
- Keep SKILL.md under 500 lines
|
||||
- Only include what Claude doesn't already know
|
||||
- Use progressive disclosure with reference files
|
||||
|
||||
### 2. Clear Naming
|
||||
- Use gerund form (verb + -ing): "Processing PDFs", "Analyzing Data"
|
||||
- Avoid vague names: "Helper", "Utils", "Manager"
|
||||
- Make names descriptive and specific
|
||||
|
||||
### 3. Specific Descriptions
|
||||
- Write in third person
|
||||
- Include key terms for discoverability
|
||||
- Clearly indicate when to use the skill
|
||||
- Maximum 1024 characters
|
||||
|
||||
### 4. Progressive Context Reveal
|
||||
- Start with essential information in SKILL.md
|
||||
- Reference detailed docs when needed
|
||||
- Organize supporting files logically
|
||||
|
||||
## Creating a Skill
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. Create skill directory: `mkdir -p .claude/skills/my-skill`
|
||||
2. Create `SKILL.md` with frontmatter
|
||||
3. Write clear name and description
|
||||
4. Add concise instructions
|
||||
5. Test with Claude
|
||||
|
||||
For a complete template, see `templates/skill-template.md`.
|
||||
|
||||
### Writing Effective Instructions
|
||||
|
||||
**DO:**
|
||||
- Provide concrete examples
|
||||
- Create clear step-by-step workflows
|
||||
- Include validation/feedback loops
|
||||
- Use consistent terminology
|
||||
- Reference additional files for details
|
||||
|
||||
**DON'T:**
|
||||
- Include time-sensitive information
|
||||
- Over-explain what Claude already knows
|
||||
- Use vague or ambiguous language
|
||||
- Cram all details into SKILL.md
|
||||
|
||||
### Setting Degrees of Freedom
|
||||
|
||||
Match specificity to task requirements:
|
||||
- **High freedom**: Flexible, creative tasks
|
||||
- **Low freedom**: Fragile, sequence-critical operations
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
# Low freedom (specific)
|
||||
When processing invoice PDFs:
|
||||
1. Extract date field using format YYYY-MM-DD
|
||||
2. Validate amount matches total
|
||||
3. Output to invoices.json
|
||||
|
||||
# High freedom (flexible)
|
||||
Analyze the document and extract relevant financial information.
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
Use progressive disclosure for complex skills within the skill directory:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Concise entry point
|
||||
├── reference/ # Detailed documentation
|
||||
│ ├── api-docs.md
|
||||
│ └── examples.md
|
||||
├── scripts/ # Helper utilities
|
||||
│ └── validator.py
|
||||
└── templates/ # Starting templates
|
||||
└── output.json
|
||||
```
|
||||
|
||||
**IMPORTANT**: Skills must be self-contained within their directory:
|
||||
- Only reference files within the skill directory
|
||||
- Do NOT reference external files (e.g., `../../CLAUDE.md` or project files)
|
||||
- Include all necessary content within the skill structure
|
||||
- Skills may be used in different contexts and must work independently
|
||||
|
||||
See `reference/skill-structure.md` for detailed organization patterns.
|
||||
|
||||
## Best Practices
|
||||
|
||||
For comprehensive best practices, see `reference/best-practices.md`. Key highlights:
|
||||
|
||||
### Description Writing
|
||||
```markdown
|
||||
# Good
|
||||
description: Guides creation of React components following project conventions, including TypeScript types, styled-components, and test patterns
|
||||
|
||||
# Vague
|
||||
description: Helps with React stuff
|
||||
```
|
||||
|
||||
### Documentation
|
||||
- Write skills for the current Claude model's capabilities
|
||||
- Avoid time-sensitive information
|
||||
- Test iteratively with real scenarios
|
||||
- Create evaluation cases before extensive docs
|
||||
|
||||
### Tool Restrictions
|
||||
Limit tool access when needed:
|
||||
```yaml
|
||||
---
|
||||
name: Read-Only Analysis
|
||||
allowed-tools: [Read, Grep, Glob]
|
||||
---
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See `reference/examples.md` for complete skill examples including:
|
||||
- Simple focused skills
|
||||
- Complex multi-file skills
|
||||
- Skills with tool restrictions
|
||||
- Skills with progressive disclosure
|
||||
|
||||
## Testing and Iteration
|
||||
|
||||
1. Start with core functionality
|
||||
2. Test with Claude on real scenarios
|
||||
3. Refine based on actual usage
|
||||
4. Add supporting docs as needed
|
||||
5. Keep SKILL.md concise, move details to reference files
|
||||
|
||||
## Critical Workflow: Review After Every Change
|
||||
|
||||
**IMPORTANT**: Whenever you make changes to a skill file (creating, editing, or updating SKILL.md or related files), you MUST immediately review the skill against best practices.
|
||||
|
||||
### Required Review Steps
|
||||
|
||||
After making any skill changes:
|
||||
|
||||
1. **Read the updated skill**: Use the Read tool to view the complete updated SKILL.md
|
||||
2. **Apply review checklist**: Review against criteria in `reference/skill-review.md`:
|
||||
- Name: Gerund form, specific, not vague
|
||||
- Description: Under 1024 chars, includes key terms, third person
|
||||
- Length: SKILL.md under 500 lines
|
||||
- Examples: Concrete and helpful
|
||||
- Validation: Steps included for verifying success
|
||||
- Clarity: Instructions are unambiguous and actionable
|
||||
- Organization: Logical structure with progressive disclosure
|
||||
3. **Identify issues**: Note any deviations from best practices
|
||||
4. **Fix immediately**: If issues are found, fix them before completing the task
|
||||
|
||||
### What to Check
|
||||
|
||||
- **Discoverability**: Will Claude find and use this skill appropriately?
|
||||
- **Clarity**: Are instructions clear enough to follow?
|
||||
- **Completeness**: Is all necessary information included?
|
||||
- **Conciseness**: Only what Claude doesn't already know?
|
||||
- **Effectiveness**: Does the skill actually help accomplish the task?
|
||||
|
||||
### Common Issues to Catch
|
||||
|
||||
- Vague descriptions that hurt discoverability
|
||||
- Missing validation steps
|
||||
- Ambiguous instructions
|
||||
- Monolithic SKILL.md files (over 500 lines)
|
||||
- Over-explanation of what Claude already knows
|
||||
- Missing concrete examples
|
||||
- Time-sensitive information
|
||||
- External file references (skills must be self-contained)
|
||||
|
||||
For comprehensive review guidelines, see `reference/skill-review.md`.
|
||||
|
||||
**This review step is not optional** - it ensures every skill change maintains quality and follows best practices.
|
||||
|
||||
## Reviewing Skills
|
||||
|
||||
Whether reviewing your own skills or others', systematic review ensures quality and effectiveness.
|
||||
|
||||
### Review Checklist
|
||||
|
||||
Quick checklist for skill review:
|
||||
- **Name**: Gerund form, specific, not vague
|
||||
- **Description**: Under 1024 chars, includes key terms, third person
|
||||
- **Length**: SKILL.md under 500 lines
|
||||
- **Examples**: Concrete and helpful
|
||||
- **Validation**: Steps included for verifying success
|
||||
- **Clarity**: Instructions are unambiguous and actionable
|
||||
- **Organization**: Logical structure with progressive disclosure
|
||||
|
||||
### Key Review Areas
|
||||
|
||||
1. **Discoverability**: Will Claude find and use this skill appropriately?
|
||||
2. **Clarity**: Are instructions clear enough to follow?
|
||||
3. **Completeness**: Is all necessary information included?
|
||||
4. **Conciseness**: Only what Claude doesn't already know?
|
||||
5. **Effectiveness**: Does the skill actually help accomplish the task?
|
||||
|
||||
### Common Issues to Check
|
||||
|
||||
- Vague descriptions that hurt discoverability
|
||||
- Missing validation steps
|
||||
- Ambiguous instructions
|
||||
- Monolithic SKILL.md files (over 500 lines)
|
||||
- Over-explanation of what Claude already knows
|
||||
- Missing concrete examples
|
||||
- Time-sensitive information
|
||||
|
||||
For comprehensive review guidelines, see `reference/skill-review.md`.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Single-Purpose Skill
|
||||
Focus on one specific capability with clear instructions.
|
||||
|
||||
### Multi-Step Workflow
|
||||
Provide structured steps with validation between stages.
|
||||
|
||||
### Context-Heavy Skill
|
||||
Use progressive disclosure: essentials in SKILL.md, details in reference files.
|
||||
|
||||
### Tool-Restricted Skill
|
||||
Limit tools for safety-critical or read-only operations.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Skill not discovered**: Check description specificity and key terms
|
||||
**Too verbose**: Move details to reference files
|
||||
**Unclear when to use**: Improve description and add usage examples
|
||||
**Inconsistent results**: Reduce degrees of freedom, add specific steps
|
||||
|
||||
## References
|
||||
|
||||
- `reference/skill-structure.md`: Complete structure and organization details
|
||||
- `reference/best-practices.md`: Comprehensive best practices guide
|
||||
- `reference/examples.md`: Real-world skill examples
|
||||
- `reference/skill-review.md`: Comprehensive skill review guidelines
|
||||
- `templates/skill-template.md`: Starting template for new skills
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
Creating a new skill? Ask:
|
||||
1. **Is it focused?** One capability per skill
|
||||
2. **Is the description clear?** Third person, specific, key terms
|
||||
3. **Is SKILL.md concise?** Under 500 lines, essential info only
|
||||
4. **Do I need reference files?** Use progressive disclosure for complex topics
|
||||
5. **Have I tested it?** Try with real scenarios before finalizing
|
||||
|
||||
When writing skills, remember: skills extend Claude's knowledge, so focus on what Claude doesn't already know and make it easily discoverable through clear descriptions and names.
|
||||
649
skills/skill-builder/reference/best-practices.md
Normal file
649
skills/skill-builder/reference/best-practices.md
Normal 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
815
skills/skill-builder/reference/examples.md
Normal 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
756
skills/skill-builder/reference/skill-review.md
Normal 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
448
skills/skill-builder/reference/skill-structure.md
Normal 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
|
||||
210
skills/skill-builder/templates/skill-template.md
Normal file
210
skills/skill-builder/templates/skill-template.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
name: [Gerund Form: "Processing", "Analyzing", "Creating"]
|
||||
description: [Third person, specific description with key terms - max 1024 chars]
|
||||
# Optional: Restrict which tools Claude can use
|
||||
# allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
|
||||
---
|
||||
|
||||
# [Skill Name]
|
||||
|
||||
[1-2 sentence overview of what this skill does and when to use it]
|
||||
|
||||
## Overview
|
||||
|
||||
[Brief explanation of the skill's purpose and capabilities]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
[Optional: List what must exist or be true before using this skill]
|
||||
- Prerequisite 1
|
||||
- Prerequisite 2
|
||||
|
||||
## Workflow
|
||||
|
||||
[Step-by-step instructions for accomplishing the task]
|
||||
|
||||
1. **[Step name]**
|
||||
[Description of what to do]
|
||||
|
||||
```bash
|
||||
# Example command if applicable
|
||||
```
|
||||
|
||||
2. **[Step name]**
|
||||
[Description of what to do]
|
||||
- Sub-step if needed
|
||||
- Another sub-step
|
||||
|
||||
3. **[Step name with validation]**
|
||||
[Description]
|
||||
|
||||
Verify:
|
||||
- Expected outcome 1
|
||||
- Expected outcome 2
|
||||
|
||||
## Expected Output
|
||||
|
||||
[Describe or show the expected output format]
|
||||
|
||||
```[language]
|
||||
# Example output
|
||||
{
|
||||
"field": "value"
|
||||
}
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
[How to verify the task was completed successfully]
|
||||
|
||||
- [ ] Validation checkpoint 1
|
||||
- [ ] Validation checkpoint 2
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: [Scenario Name]
|
||||
|
||||
**Input:**
|
||||
```
|
||||
[Example input]
|
||||
```
|
||||
|
||||
**Process:**
|
||||
[What to do with this input]
|
||||
|
||||
**Output:**
|
||||
```
|
||||
[Expected output]
|
||||
```
|
||||
|
||||
### Example 2: [Edge Case or Variation]
|
||||
|
||||
[Another concrete example demonstrating usage]
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: [Problem Description]
|
||||
**Solution**: [How to resolve]
|
||||
|
||||
### Issue: [Another Problem]
|
||||
**Solution**: [How to resolve]
|
||||
|
||||
## Error Handling
|
||||
|
||||
[How to handle errors or unexpected situations]
|
||||
|
||||
If [error condition]:
|
||||
1. [Recovery step]
|
||||
2. [Verification step]
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
[Optional: Advanced patterns or variations]
|
||||
|
||||
### Pattern 1: [Advanced Pattern Name]
|
||||
[Description and example]
|
||||
|
||||
### Pattern 2: [Another Pattern]
|
||||
[Description and example]
|
||||
|
||||
## References
|
||||
|
||||
[Optional: Link to supporting documentation]
|
||||
- `reference/detailed-docs.md`: [What's there]
|
||||
- `scripts/helper.py`: [What it does]
|
||||
- `templates/output-format.json`: [What it shows]
|
||||
|
||||
---
|
||||
|
||||
## Template Usage Notes
|
||||
|
||||
**Remove this section before using**
|
||||
|
||||
### Naming Guidelines
|
||||
- **Skill name**: Use gerund (verb + -ing)
|
||||
- Good: "Processing Invoice PDFs", "Analyzing Logs"
|
||||
- Avoid: "Invoice Helper", "Log Utils"
|
||||
|
||||
### Description Guidelines
|
||||
- Write in third person
|
||||
- Include key technology names
|
||||
- Specify the output or outcome
|
||||
- Maximum 1024 characters
|
||||
- Good: "Processes invoice PDFs extracting vendor, date, and line items with validation"
|
||||
- Avoid: "Helps with invoices"
|
||||
|
||||
### Content Guidelines
|
||||
1. **Be concise**: Only include what Claude doesn't already know
|
||||
2. **Be specific**: Provide concrete examples and formats
|
||||
3. **Include validation**: Add verification steps
|
||||
4. **Progressive disclosure**: For complex topics, reference additional files
|
||||
5. **Keep under 500 lines**: Move extensive details to reference/ files
|
||||
|
||||
### Tool Restrictions (optional)
|
||||
Uncomment and customize `allowed-tools` if you need to restrict which tools Claude can use:
|
||||
- Read-only analysis: `[Read, Grep, Glob]`
|
||||
- File operations: `[Read, Write, Edit, Glob, Grep]`
|
||||
- Development: `[Read, Write, Edit, Bash, Glob, Grep]`
|
||||
|
||||
### Sections to Customize
|
||||
Required:
|
||||
- [ ] name (frontmatter)
|
||||
- [ ] description (frontmatter)
|
||||
- [ ] Overview
|
||||
- [ ] Workflow or Instructions
|
||||
- [ ] At least one Example
|
||||
|
||||
Optional (remove if not needed):
|
||||
- [ ] Prerequisites
|
||||
- [ ] Expected Output
|
||||
- [ ] Validation
|
||||
- [ ] Common Issues
|
||||
- [ ] Error Handling
|
||||
- [ ] Advanced Usage
|
||||
- [ ] References
|
||||
|
||||
### File Organization
|
||||
Simple skill:
|
||||
```
|
||||
my-skill/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
With reference docs:
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
└── reference/
|
||||
└── detailed-guide.md
|
||||
```
|
||||
|
||||
With scripts:
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
└── scripts/
|
||||
└── helper.py
|
||||
```
|
||||
|
||||
Complete:
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md
|
||||
├── reference/
|
||||
│ └── docs.md
|
||||
├── scripts/
|
||||
│ └── helper.py
|
||||
└── templates/
|
||||
└── output.json
|
||||
```
|
||||
|
||||
### Quick Checklist
|
||||
Before finalizing:
|
||||
- [ ] Name uses gerund form
|
||||
- [ ] Description is specific with key terms
|
||||
- [ ] Examples are concrete and helpful
|
||||
- [ ] Validation steps included
|
||||
- [ ] Under 500 lines
|
||||
- [ ] No obvious information Claude already knows
|
||||
- [ ] Tested with real scenario
|
||||
- [ ] Template notes removed
|
||||
Reference in New Issue
Block a user