zhongwei/gh-sawyer-middeleer-dot-claude-plugins-dot-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:54:17 +08:00
commit 39d22f1b82
13 changed files with 1557 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
skills/creating-skills/SKILL.md Normal file
View File

@@ -0,0 +1,301 @@
---
name: creating-skills
description: Creates high-quality Claude skills following official best practices. Use when the user asks to create a new skill, improve an existing skill, or needs guidance on skill authoring. Includes proper structure, naming conventions, progressive disclosure patterns, and quality validation.
---
# Creating High-Quality Claude Skills
Use this skill when creating or improving Claude skills to ensure they follow official best practices and work effectively across all Claude models.
## Core Principles
**Conciseness**: Skills share the context window. Only include information Claude doesn't already have.
**Appropriate Freedom**: Match instruction detail to task needs:
- **High freedom**: Multiple valid approaches (use text instructions)
- **Medium freedom**: Preferred patterns with flexibility (use pseudocode/guidance)
- **Low freedom**: Exact sequences required (use specific bash/python scripts)
**Progressive Disclosure**: Keep SKILL.md under 500 lines. Split content into reference files when approaching this limit. All references must be one level deep.
## Phase 1: Initial Clarification (CRITICAL)
**BEFORE planning or writing the skill**, use the **AskUserQuestion** tool to gather structured feedback on skill requirements.
Ask the user to clarify (only if needed):
1. **Instruction detail level**: How much freedom should Claude have? (use AskUserQuestion with single select)
- High freedom - Multiple valid approaches, text instructions only
- Medium freedom - Preferred patterns with flexibility, pseudocode/guidance
- Low freedom - Exact sequences required, specific scripts
2. **Success criteria**: How will success be measured? Suggest options contextually based on skill type. (use AskUserQuestion with multiSelect: true)
3. **Special considerations**: Are there any special requirements? Suggest options contextually based on skill type. (use AskUserQuestion with multiSelect: true)
Feel free to include 1-2 additional multiSelect questions if it's essential to clarify workflow steps, inputs and outputs, or other materials to include in the skill. You can write the questions and answer options based on context if you want to do this.
## Phase 2: Design & Planning
After gathering requirements in Phase 1, design the skill structure:
1. **Choose skill name**
- [ ] Use gerund form (verb + -ing, max 64 chars)
- [ ] Lowercase letters, numbers, hyphens only
- [ ] Avoid: `helper`, `utils`, or words containing "anthropic"/"claude" as these are reserved words
2. **Write description**
- [ ] Include specific keywords for discovery
- [ ] State what the skill does and when to use it
- [ ] Keep under 1024 chars, write in third person
3. **Plan content structure**
- [ ] Determine if single file (< 400 lines) or progressive disclosure needed
- [ ] Identify sections: workflow, examples, templates, validation
- [ ] Note which parts need high/medium/low freedom based on Phase 1
4. **Generate architecture diagram**
- [ ] Create ASCII architecture diagram showing full skill structure
- [ ] Follow the format guidelines in [reference/architecture-diagrams.md](./reference/architecture-diagrams.md)
- [ ] Include: phases, components, decision trees, file structure, validation flows
5. **Present plan to user**
- Share proposed name, description, and structure outline
- **Present the architecture diagram** for visual validation
- Confirm alignment with their expectations
- Adjust based on feedback before proceeding to implementation
## Phase 3: Create Content
1. **Write SKILL.md**
- [ ] Add valid YAML frontmatter
- [ ] Include only information Claude doesn't already have
- [ ] Add workflows with checklists for complex tasks
2. **Add supplementary files** (if needed)
- [ ] Create subdirectory(ies) (e.g., `examples/`, `templates/`, `scripts/`, etc)
- [ ] Split content into focused topics (one level deep only)
- [ ] Ensure SKILL.md remains under 500 lines
3. **Implement feedback mechanisms** (if identified in Phase 1)
- [ ] Add validation checkpoints
- [ ] Structure quality review loops
- [ ] Specify error handling approaches
## Phase 4: Validate Quality
Before finalizing, run through the quality checklist:
- [ ] Valid YAML frontmatter with name and description
- [ ] Name follows conventions (gerund, ≤64 chars, lowercase/hyphens)
- [ ] Description includes usage triggers (≤1024 chars)
- [ ] SKILL.md under 500 lines
- [ ] Supporting files (if any) are one level deep
- [ ] Only includes information Claude doesn't already have
- [ ] Consistent terminology throughout
- [ ] Concrete examples provided
- [ ] Scripts (if any) have explicit error handling
- [ ] File paths use forward slashes
- [ ] Dependencies documented
## YAML Frontmatter (Required)
Every skill must start with:
```yaml
---
name: skill-name-here
description: Clear description with keywords, functionality, and usage triggers for discovery.
---
```
**Name requirements:**
- Lowercase letters, numbers, hyphens only (max 64 chars)
- Use gerund form: `processing-pdfs`, `analyzing-spreadsheets`
- Avoid: `helper`, `utils`, or words containing "anthropic"/"claude"
**Description requirements:**
- Non-empty, no XML tags (max 1024 chars)
- Write in third person
- Include specific keywords and when to use this skill
- Think: "How will this be found among 100+ skills?"
## Content Organization
### Single File vs. Progressive Disclosure
**Use single SKILL.md when:**
- Content is under 400 lines
- Information is tightly related
- Users need everything at once
**Use progressive disclosure when:**
- Approaching 500 lines
- Content has distinct topics
- Some details are conditional/advanced
**Progressive disclosure patterns:**
```
SKILL.md (overview + core workflow)
└── reference/
├── topic-one.md
├── topic-two.md
└── advanced-features.md
```
**Critical rule:** Never nest references. All reference files must be directly under a single subdirectory.
## Content Principles
Core principles for writing effective skill content: conciseness, freedom levels, and progressive disclosure.
## Conciseness
Skills share the context window with conversation history and other skills. Every word must earn its place.
### Challenge Every Detail
Before including any information, ask:
- Is this essential for the task?
- Could this be inferred from context?
- Does this duplicate instruction that already exists?
**Example - Essential information only:**
```markdown
## Processing CSV Files
When processing CSVs:
1. Validate column headers match expected schema
2. Check for encoding issues (default to UTF-8)
3. Handle missing values explicitly (null vs. empty string)
```
### Focus on Unique Information
Only include what Claude doesn't already know or what's specific to your use case:
**Example (unique, actionable information):**
```markdown
## Data Processing Requirements
For this workflow, use pandas with these constraints:
- Preserve original column order (df.reindex())
- Handle timestamps in Pacific timezone
- Round currency values to 2 decimal places
```
### Remove Redundant Explanations
Don't explain the same concept multiple times:
**Example:**
```markdown
## Workflow
1. **Validate Input**: Check schema and data types
2. **Process Data**: Apply transformations
3. **Generate Output**: Format and export results
```
## Common Content Patterns
### Workflows with Checklists
Break complex tasks into steps:
```markdown
1. **Analyze Input**
- [ ] Validate format
- [ ] Check required fields
- [ ] Identify issues
2. **Process Data**
- [ ] Apply transformations
- [ ] Handle edge cases
- [ ] Validate output
```
### Templates and Examples
Provide concrete demonstrations:
```markdown
## Example: API Request
\`\`\`python
# Use this pattern for all API calls
response = requests.post(
url="https://api.example.com/endpoint", # API endpoint
json={"key": "value"}, # Request payload
timeout=30 # Prevent hanging (API rate limits)
)
\`\`\`
```
### Feedback Loops
Implement validation cycles:
```markdown
1. Run validation
2. If errors found → review → fix → return to step 1
3. If passes → proceed
```
## Scripts and Code Guidelines
**Error handling**: Scripts should provide specific, actionable messages
```python
if df['date'].isna().any():
missing_count = df['date'].isna().sum()
print(f"Error: {missing_count} rows have missing dates.")
print(f"Affected rows: {df[df['date'].isna()].index.tolist()}")
print("Solution: Remove rows or fill with interpolated values.")
```
**File paths**: Always use forward slashes for cross-platform compatibility
- ✓ `data/input/file.csv`
- ✗ `data\input\file.csv`
**Dependencies**: Document required packages and explain configuration values
**MCP tools**: Use fully qualified names: `ServerName:tool_name`
See [reference/scripts-and-code.md](./reference/scripts-and-code.md) for comprehensive guidance.
## Quality Checklist (Essential)
Before finalizing a skill:
**Structure:**
- [ ] Valid YAML frontmatter with name and description
- [ ] Name follows conventions (gerund, ≤64 chars, lowercase/hyphens)
- [ ] Description includes usage triggers (≤1024 chars)
- [ ] SKILL.md under 500 lines
- [ ] Reference files (if any) are one level deep
**Content:**
- [ ] Consistent terminology throughout
- [ ] Concrete examples provided
- [ ] Workflows use checkboxes for complex tasks
- [ ] No time-sensitive information
**Technical:**
- [ ] Scripts have explicit error handling
- [ ] File paths use forward slashes
- [ ] Dependencies documented
- [ ] No "magic numbers" (all config explained)
## Reference Files
For detailed guidance on specific topics:
- [Scripts and Code](./reference/scripts-and-code.md) - Error handling, dependencies, configuration
- [Architecture Diagrams](./reference/architecture-diagrams.md) - Skill architecture diagram guidelines

107
skills/creating-skills/reference/architecture-diagrams.md Normal file
View File

@@ -0,0 +1,107 @@
# Architecture Diagrams
Create an ASCII architecture diagram in Phase 2 to visualize the skill structure before implementation.
## Purpose
Show the complete skill architecture:
- Flow from user request to deliverable output
- All phases with their key components
- Decision points and branching logic
- File structure and organization
- How parts connect and interact
## Structure Requirements
### Essential Components
1. **Header** - Skill name and purpose
2. **Core principles layer** - Conciseness, freedom level, progressive disclosure
3. **Phase sections** - Each phase with key components and steps
4. **Flow indicators** - Arrows showing progression (│, ▼, →, ←)
5. **Decision trees** - Where skill has branching logic
6. **File structure** - Output deliverable with directory tree
7. **Validation section** - Quality checks or review loops
8. **Reference layer** - If using progressive disclosure
### Box Drawing Characters
```
╔═══╗ Double-line (major sections/headers)
║ ║
╚═══╝
┌───┐ Single-line (components)
│ │
└───┘
│ ▼ → ← Flow arrows
```
### Critical: Border Alignment
All right-side borders must align vertically. Test in monospace terminal before presenting.
## Template
```
╔═══════════════════════════════════════════════════════════╗
║ SKILL-NAME ARCHITECTURE ║
╚═══════════════════════════════════════════════════════════╝
┌─────────────┐
│ USER REQUEST│
└──────┬──────┘
▼
╔═══════════════════════════════════════════════════════════╗
║ CORE PRINCIPLES ║
║ ┌─────────┐ ┌─────────┐ ┌─────────┐ ║
║ │Principle│ │Principle│ │Principle│ ║
║ └─────────┘ └─────────┘ └─────────┘ ║
╚═══════════════════════════════════════════════════════════╝
│
▼
╔═══════════════════════════════════════════════════════════╗
║ PHASE 1: [NAME] ║
║ ┌─────────────┐ ┌─────────────┐ ║
║ │ Component 1 │ │ Component 2 │ ║
║ └─────────────┘ └─────────────┘ ║
╚═══════════════════════════════════════════════════════════╝
│
▼
[Additional phases...]
╔═══════════════════════════════════════════════════════════╗
║ OUTPUT DELIVERABLE ║
║ ┌───────────────────────────────────────────────────┐ ║
║ │ skill-name/ │ ║
║ │ ├── SKILL.md │ ║
║ │ └── reference/ (optional) │ ║
║ └───────────────────────────────────────────────────┘ ║
╚═══════════════════════════════════════════════════════════╝
```
## Content Guidelines
### Emphasize
- User interaction points
- Decision points with clear conditions
- Validation and quality checks
- Flow of data
- Skill, subagent, tool, etc dependencies
- Tool usage (Read, Write, Edit, etc.)
### Keep concise
- High-level components only, not every detail
- Show flow and structure, not implementation
- Fit diagram in terminal window
### Adapt by skill type
- Workflow: Sequential phases, validation checkpoints
- Analysis: Input validation, feedback loops, quality checks
- Content generation: Templates, parameters, formatting
- Research: Source discovery, synthesis approach, citations

227
skills/creating-skills/reference/scripts-and-code.md Normal file
View File

@@ -0,0 +1,227 @@
# Scripts and Code
Best practices for including scripts, handling errors, managing dependencies, and documenting configuration in skills.
## Table of Contents
- [When to Include Scripts](#when-to-include-scripts)
- [Error Handling](#error-handling)
- [Dependencies and Packages](#dependencies-and-packages)
- [File Paths and Cross-Platform Compatibility](#file-paths-and-cross-platform-compatibility)
- [Configuration Documentation](#configuration-documentation)
- [Script Execution vs. Reference](#script-execution-vs-reference)
- [Validation Scripts](#validation-scripts)
- [MCP Tools Integration](#mcp-tools-integration)
## When to Include Scripts
Pre-made scripts are more reliable than code generation for critical operations.
### Scripts vs. Generated Code
**Use pre-made scripts for:**
- Critical operations requiring exact sequences
- Complex error handling
- Repeated utility functions
- Fragile operations (database migrations, API calls)
- Operations where order matters
**Use code generation for:**
- Creative solutions
- Context-specific implementations
- One-off operations
- Exploratory tasks
## Error Handling
Scripts should solve problems, not punt to Claude. Provide specific, actionable error messages.
### Good Error Handling
✓ **What to do:**
```python
def process_file(filename):
"""
Process input file with comprehensive error handling.
Args:
filename: Path to the file to process
Returns:
Processed data string
Raises:
FileNotFoundError: With specific path and suggestions
PermissionError: With permission requirements
ValueError: With format expectations
"""
import os
# Check file exists
if not os.path.exists(filename):
raise FileNotFoundError(
f"File not found: {filename}\n"
f"Current directory: {os.getcwd()}\n"
f"Please verify:\n"
f" 1. File path is correct\n"
f" 2. File exists in the expected location\n"
f" 3. You have permission to access the directory"
)
# Check file is readable
if not os.access(filename, os.R_OK):
raise PermissionError(
f"Cannot read file: {filename}\n"
f"Current user: {os.getenv('USER')}\n"
f"File permissions: {oct(os.stat(filename).st_mode)[-3:]}\n"
f"Solution: Run 'chmod +r {filename}' or contact system administrator"
)
# Check file is not empty
if os.path.getsize(filename) == 0:
raise ValueError(
f"File is empty: {filename}\n"
f"Expected: Non-empty CSV file with headers\n"
f"Please provide a file with data"
)
# Check file format
try:
with open(filename, 'r') as f:
first_line = f.readline()
if not first_line.strip():
raise ValueError(
f"File appears to be empty or invalid: {filename}\n"
f"Expected: CSV file with comma-separated headers"
)
if ',' not in first_line:
raise ValueError(
f"File does not appear to be CSV format: {filename}\n"
f"First line: {first_line[:100]}\n"
f"Expected: Comma-separated values\n"
f"Detected: {first_line.count('\t')} tabs, {first_line.count('|')} pipes\n"
f"Suggestion: Check delimiter or convert to CSV"
)
# Process file
f.seek(0)
data = f.read()
return data
except UnicodeDecodeError as e:
raise ValueError(
f"File encoding error: {filename}\n"
f"Error: {str(e)}\n"
f"File might be binary or use unsupported encoding\n"
f"Solution: Convert to UTF-8 encoding or verify file type"
)
```
## Dependencies and Packages
Document required packages with versions and explain why they're needed.
## File Paths and Cross-Platform Compatibility
Always use forward slashes for file paths to ensure cross-platform compatibility.
### Path Best Practices
**Always use forward slashes:**
```python
# ✓ Correct - works on all platforms
data_file = "data/input/customers.csv"
output_dir = "reports/2024/march"
config_path = "config/settings.json"
# ✗ Wrong - fails on Unix-like systems
data_file = "data\\input\\customers.csv"
output_dir = "reports\\2024\\march"
```
**Use pathlib for path operations:**
```python
from pathlib import Path
# Automatically handles platform differences
data_dir = Path("data") / "input"
output_file = data_dir / "processed_data.csv"
# Always converts to forward slashes for display
print(output_file.as_posix()) # "data/input/processed_data.csv"
```
**Convert user-provided paths:**
```python
def normalize_path(path_str):
"""Convert any path format to forward-slash format."""
from pathlib import Path
return Path(path_str).as_posix()
# Example usage
user_path = "data\\input\\file.csv" # User on Windows
normalized = normalize_path(user_path) # "data/input/file.csv"
```
## Configuration Documentation
Document why configuration values exist. No "magic numbers."
### Good Configuration
✓ **What to do:**
```python
# Maximum retry attempts for API calls
# Set to 3 because:
# - API typically recovers within 3 attempts
# - Higher values cause unacceptable user wait times
# - Exponential backoff means 3 attempts = ~7 seconds total
MAX_RETRIES = 3
# Request timeout in seconds
# Set to 30 because:
# - API SLA guarantees response within 20 seconds
# - 10 second buffer prevents false timeouts
# - Longer timeouts risk resource exhaustion
TIMEOUT = 30
```
## Script Execution vs. Reference
Clarify whether Claude should execute scripts or use them as reference patterns.
## Validation Scripts
Create validation scripts with explicit, actionable error messages for critical operations.
## MCP Tools Integration
When referencing MCP (Model Context Protocol) tools, always use fully qualified names.
### Fully Qualified Names
MCP tools must be referenced with the server name prefix:
✓ **Correct:**
```markdown
Use the `DatabaseServer:search_database` tool to find records.
Use the `FileServer:list_files` tool to see available files.
```
## Validation Checklist
Scripts and code checklist:
- [ ] Scripts included only for critical/complex/repeated operations
- [ ] Error messages are specific and actionable
- [ ] Error messages include context and solutions
- [ ] All error conditions explicitly handled
- [ ] Dependencies documented with versions and purposes
- [ ] File paths use forward slashes (cross-platform)
- [ ] Configuration values explained (no magic numbers)
- [ ] Clear indication whether to execute or reference scripts
- [ ] Validation scripts provide comprehensive error reports
- [ ] MCP tools referenced with fully qualified names (ServerName:tool_name)