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

131
skills/analyzing-source/SKILL.md Normal file
View File

@@ -0,0 +1,131 @@
---
name: analyzing-source
description: Conducts in-depth analysis of a specific source or topic, producing comprehensive summaries for research synthesis. Use when you need detailed analysis and documentation of individual sources as part of a larger research effort.
---
# Analyzing Source
This skill guides you through analyzing a single source in depth and creating a comprehensive summary suitable for research synthesis.
## Process
Follow these steps to analyze a source and create a comprehensive summary:
### Step 1: Source Discovery and Retrieval
**If given a URL:**
- Fetch it directly using WebFetch
- Verify the content is accessible and relevant
**If given a topic or search query:**
- Use WebSearch to find the best source on the topic
- Prioritize authoritative, detailed sources
- Fetch the most relevant result using WebFetch
**If source is inaccessible or low-quality:**
- Try alternative sources
- Be persistent in finding substantive information
- Note any access issues in your summary
### Step 2: Deep Analysis
Conduct thorough analysis focusing on:
- **Core concepts, definitions, and frameworks** presented in the source
- **Main arguments, claims, and findings** - what is the source asserting?
- **Evidence, data, and examples** - what supports the claims?
- **Methodologies or approaches** - how was this work conducted?
- **Limitations, caveats, and counterarguments** - what are the boundaries?
- **Connections to broader themes** - how does this relate to the research focus?
- **Quality and credibility** - how reliable is this source?
- **Unique insights or perspectives** - what new understanding does this offer?
### Step 3: Create Comprehensive Summary
Use the template from `./templates/article-summary.md` to create your summary.
**VERY IMPORTANT:** Your summary must be concise yet thorough, which means being extreme information-dense and leveraging key data as much as possible.
**Template structure includes:**
- Executive summary
- Key concepts & definitions
- Main arguments/findings with evidence
- Methodology/approach
- Specific examples & case studies
- Notable quotes
- Critical evaluation
- Relevance to research focus
- Practical implications
**Key principles:**
- Include specific quotes and examples, not just paraphrasing
- Provide analytical insights about significance and relevance
- Make clear connections to the research focus provided
- Be detailed enough that someone can understand the source without reading the original
### Step 4: Save Summary File
**Create filename:**
- Use a descriptive slug based on the source
- Example: `kubernetes-scaling-patterns.md`, `netflix-chaos-engineering.md`
**Save location:**
- Save to: `{working_directory}/summaries/{filename}.md`
- Use the complete template structure
- Ensure all sections are filled out
### Step 5: Report Results
Provide a brief report including:
1. Confirmation of what source you analyzed
2. The file path where you saved the summary
3. A 2-3 sentence overview of the most important insights discovered
## Important Guidelines
- **Be thorough, not brief**: This is deep research, not light scanning. Capture nuance and detail.
- **Include specific evidence**: Direct quotes, data points, examples - not just general statements.
- **Think critically**: Note limitations, assess quality, identify assumptions.
- **Stay focused**: While being comprehensive, ensure everything relates to the research focus.
- **Be self-contained**: Your summary should make sense without reading the original source.
- **Save your work**: Always save the summary file - the main coordinator depends on it.
## Example Execution
```
Input received:
- Source topic: "Kubernetes horizontal pod autoscaling best practices"
- Research focus: "Scalability patterns in cloud-native systems"
- Working directory: /Users/research/cloud-native-scaling
Step 1: Using WebSearch to find authoritative source on Kubernetes HPA...
Found: kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/
Fetching with WebFetch...
Step 2: Analyzing content...
- Identified core HPA concepts: target metrics, scale-up/down policies, cooldown periods
- Found detailed configuration examples with CPU and custom metrics
- Noted limitations around cluster resources and metric collection latency
Step 3: Creating comprehensive summary using template...
- Executive summary: 3 paragraphs covering main patterns and tradeoffs
- Key concepts: HPA, target utilization, metric servers, custom metrics API
- Main findings: 5 configuration patterns with evidence from examples
- 8 notable quotes extracted from official docs and linked blog posts
- Evidence quality: High (official documentation + real-world examples)
Step 4: Saving summary...
Created: /Users/research/cloud-native-scaling/summaries/kubernetes-hpa-best-practices.md
Step 5: Report
Source analyzed: Kubernetes official documentation on Horizontal Pod Autoscaling
Saved to: /Users/research/cloud-native-scaling/summaries/kubernetes-hpa-best-practices.md
Key insights: This source provides detailed HPA configuration patterns with real-world examples from production systems at scale. Most valuable finding is the discussion of custom metrics integration and the tradeoffs between reactive vs predictive scaling approaches. Also documents common pitfalls like resource request misconfiguration causing scaling issues.
```

114
skills/analyzing-source/templates/article-summary.md Normal file
View File

@@ -0,0 +1,114 @@
---
created: YYYY-MM-DD
source_url: [URL or citation]
source_type: [academic/industry/community/expert/case-study/documentation]
research_focus: [the specific research angle this source addresses]
tags: [research-topic, relevant-tags]
---
# [Source Title]
**Source:** [source_url]
## Citation
[Full citation information - include authors, date, publication, DOI/URL]
## Executive Summary
[2-3 paragraph overview of what this source is about, its main contribution, and why it matters to the research. Should be comprehensive enough to understand the source's value without reading further.]
## Key Concepts & Definitions
[Define important terms, frameworks, or concepts introduced or used by this source. Be specific and thorough.]
- **[Concept 1]**: [Definition and explanation]
- **[Concept 2]**: [Definition and explanation]
- **[Concept 3]**: [Definition and explanation]
## Main Arguments / Insights / Features
[Break down the source's central arguments, insights, or technical features in detail. Use hierarchical structure if there are multiple levels.]
### Primary Argument / Insight / Feature 1
...
### Primary Argument / Insight / Feature 2
...
### Primary Argument / Insight / Feature 3
...
## Methodology / Approach
[Detailed description of methods, technical approaches, research design, or execution strategies used]
## Specific Examples & Case Studies
[Concrete examples, case studies, scenarios, or demonstrations provided in the source. Include specific details, numbers, and context.]
## Notable Quotes
[Include verbatim quotes that capture key ideas, unique insights, or particularly well-articulated points. Be generous with quotes - they're valuable for synthesis.]
## Evidence Quality Assessment
**Strength of Evidence**: [Strong/Moderate/Weak]
**Evidence Types Present**:
- [ ] Empirical data / statistics
- [ ] Case studies / real-world examples
- [ ] Expert testimony / citations
- [ ] Theoretical reasoning
- [ ] Anecdotal evidence
**Credibility Indicators**:
- **Author/Source Authority**: [Assessment of author expertise and source reputation]
- **Currency**: [How recent/up-to-date is this information?]
- **Transparency**: [Are methods, sources, and limitations clearly stated?]
- **Peer Review/Validation**: [Has this been peer-reviewed or validated by others?]
## Critical Evaluation
**Strengths**:
...
**Limitations**:
...
**Potential Biases**:
...
## Relevance to Research Focus
**Primary Research Angle(s) Addressed**: [Which specific research angle(s) from the plan does this inform?]
**Specific Contributions to Research**:
[How specifically does this advance understanding of each angle 1?]
[What unique perspective or information does this provide?]
**Gaps This Source Fills**: [What questions does this answer that other sources haven't?]
**Gaps Still Remaining**: [What questions does this source raise but not answer?]
## Practical Implications
[What are the practical takeaways, recommendations, or applications discussed?]
- [Implication 1]
- [Implication 2]
- [Implication 3]
## Open Questions & Further Research Directions
[What questions does this source raise? What further research does it suggest?]
1. [Question/direction 1]
2. [Question/direction 2]
3. [Question/direction 3]

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)