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

18
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "dot-claude",
"description": "Actually useful skills, agents, and commands for Claude Code - focused on research, analysis, and skill creation",
"version": "2.0.0",
"author": {
"name": "Sawyer",
"email": "saw.midd@gmail.com"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# dot-claude
Actually useful skills, agents, and commands for Claude Code - focused on research, analysis, and skill creation

38
agents/research-analyst.md Normal file
View File

@@ -0,0 +1,38 @@
---
name: research-analyst
description: Expert research analyst that helps research and analyze specific sources
model: haiku
permissionMode: default
skills: analyzing-source
---
You are a specialized research analyst conducting in-depth investigation of a specific source or topic as part of a larger research project. Your goal is to thoroughly analyze the assigned source and produce a comprehensive, detailed summary that captures all key insights, arguments, evidence, and connections to the broader research themes.
## Context
You are working as part of a parallel research effort where multiple researchers are simultaneously investigating different sources. Your work will be synthesized with other researchers' findings by the main research coordinator, so your summary must be self-contained and comprehensive enough to stand alone.
## Task
Follow the **analyzing-source** skill to:
1. Discover and retrieve the source (WebSearch/WebFetch)
2. Conduct deep analysis of the content
3. Create a comprehensive summary using analyzing-source/templates/article-summary.md
4. Save the summary to `{working_directory}/summaries/{filename}.md`
5. Report your findings with key insights
## Inputs You'll Receive
- **Source topic or URL**: The specific source to research
- **Research focus**: The specific angle or theme to emphasize
- **Research purpose**: Overall goal of the research project
- **Working directory**: Directory path where you should save your summary
## Output Format
Provide:
1. Brief confirmation of what source you analyzed
2. File path where you saved the summary
3. 2-3 sentence overview of the most important insights discovered

289
commands/deep-research.md Normal file
View File

@@ -0,0 +1,289 @@
# Deep Research Command
Conducts comprehensive research on complex topics with technical rigor, synthesizing multiple sources including academic papers, technical documentation, industry reports, and practitioner insights.
## Usage
```
/deep-research [topic]
```
## Purpose
Execute a systematic research workflow that:
- Clarifies research parameters through structured dialog
- Creates a detailed research plan
- Conducts parallel source investigation
- Synthesizes findings into comprehensive documentation
- Produces research-ready artifacts with proper citations
## Prerequisites
- Access to web search and fetch capabilities
- Sufficient time for thorough investigation (varies by depth)
## Workflow Steps
### Phase 0: Topic Identification
**If the user invoked the command without a topic** (e.g., just `/deep-research`):
Ask an open-ended question: "What topic or research question would you like to investigate?"
**If the user provided a topic** (e.g., `/deep-research distributed systems patterns`):
- Proceed directly to Phase 1 with the provided topic
### Phase 1: Initial Clarification
Use the **AskUserQuestion** tool to gather structured feedback on research parameters.
Ask the user to clarify:
1. **Research purpose**: What is the goal of this research/what angles should be explored? Suggest options contextually. (use AskUserQuestion with multiSelect: true)
2. **Scope boundaries**: What should be included/excluded? Any constraints? Suggest options contextually. (use AskUserQuestion with multiSelect: true)
3. **Source preferences**: Which types are most valuable? (use AskUserQuestion with multiSelect: true)
- Academic papers and peer-reviewed research
- Technical documentation / Industry whitepapers
- Technical blogs from recognized experts
- Practitioner discussions (Reddit, X, LinkedIn, HackerNews)
- Company documentation and case studies
4. **Research depth**: How many sources? (use AskUserQuestion with options for Light: 6-8, Medium: 9-14, Deep: 15+)
### Phase 2: Planning & Approval
**Brief preliminary investigation:**
- Search for 2-3 representative sources
- Identify major themes, terminology, key authors/organizations
- Note unexpected angles or adjacent topics worth exploring
**Create research plan:**
1. Use template from `plugins/dot-claude/commands/templates/research-plan.md`
2. Ask the user where they would like you to save your work or if you should create a new working directory
3. Create `/[RESEARCH TOPIC]` inside the working directory
4. Create and save your research plan to `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/plan.md`
**Plan structure:**
- **Research angles**: 3-5 core sub-questions or perspectives
- **Source strategy**: Mix of source types with target quantities based on user preferences
- **Analysis approach**: Synthesis method (thematic, comparative, chronological)
- **Expected deliverables**: Final format and supporting documentation
- **Potential challenges**: Known gaps, access issues, complexity factors
---
### Phase 3: Research Execution & Synthesis
#### Overview
Research is conducted by spawning multiple researcher subagents simultaneously—one for each source topic. Each researcher independently fetches, analyzes, and creates a comprehensive summary of their assigned source. After all researchers complete, you synthesize their findings into a unified research document.
**Research approach:**
- All sources researched simultaneously for faster execution
- Research follows the initial research plan established in Phase 2
- Comprehensive individual summaries from each researcher
- Final synthesis integrates all findings after research is complete
#### Step 1: Setup
1. Create synthesis file from template: `plugins/dot-claude/commands/templates/research-synthesis.md`
2. Save to: `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/synthesis.md`
3. Create summaries directory: `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/`
#### Step 2: Identify Research Topics
From the approved research plan, identify specific search queries to research. Aim for target source count from Phase 1 (6-8 for Light, 9-14 for Medium, 15+ for Deep).
**For each research angle in the plan**, identify 2-4 specific search queries to investigate:
Example:
- Research Angle: "Performance patterns in distributed systems"
- Query 1: "Kubernetes horizontal pod autoscaling best practices"
- Query 2: "Netflix microservices scaling strategies"
- Query 3: "Load balancing algorithms for distributed systems"
Create a list of N search queries to research (where N = target source count).
#### Step 3: Find and Validate URLs
**CRITICAL: You must identify and validate specific URLs before spawning any researcher subagents.**
For each search query from Step 2:
1. Use WebSearch to find relevant sources
2. Identify a specific URL from the search results that best addresses the query
3. Use WebFetch with a simple prompt (e.g., "Extract the title and first paragraph") to verify each URL is accessible
4. If a URL is not accessible, find an alternative URL for that query and validate it
5. Compile a list of N validated URLs (one per query)
**Do not proceed to Step 4 until you have N validated, accessible URLs.**
Document the validated URLs clearly, noting which research angle and query each URL addresses.
#### Step 4: Spawn Researcher Subagents in Parallel
**CRITICAL: Use a single message with multiple Task tool calls to execute all researchers in parallel.**
For each validated URL from Step 3, spawn a researcher subagent using the Task tool:
```
Task tool parameters for each researcher:
- subagent_type: "dot-claude-agents:research-analyst"
- description: "Research [brief topic description]"
- prompt: "You are executing the researcher subagent role defined in plugins/dot-claude/agents/research-analyst.md.
Your assignment:
- Source URL: [VALIDATED_URL]
- Research focus: [specific research angle from plan]
- Research purpose: [overall research goal from Phase 1]
- Working directory: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]
Follow the instructions in plugins/dot-claude/agents/research-analyst.md to:
1. Fetch the source using WebFetch on the provided URL
2. Conduct deep analysis
3. Create comprehensive summary using plugins/dot-claude/skills/analyzing-source/templates/article-summary.md
4. Save to: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/[descriptive-filename].md
Provide a brief confirmation when complete with the key insights discovered."
```
**Execute all N researchers in parallel by including N Task tool calls in a single message.**
#### Step 5: Wait for Completion
All researcher subagents will execute in parallel. Wait for all to complete before proceeding.
#### Step 6: Review Researcher Outputs
Once all researchers have completed:
1. List all summary files created in `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/`
2. Read each source summary file to understand what each researcher discovered
3. Note the range of perspectives, key themes, contradictions, and gaps
#### Step 7: Build Comprehensive Synthesis
Now synthesize all findings into the `synthesis.md` file:
**Synthesis approach:**
1. **Identify major themes** across all sources
- Look for patterns that appear in multiple sources
- Note areas of consensus and disagreement
- Group related findings together
2. **Organize synthesis by themes**, not by source
- Each theme section should integrate insights from multiple sources
- Compare and contrast different perspectives
- Build coherent narrative for each theme
3. **For each theme, include:**
- Core insights and findings (citing source summaries using `[[filename]]`)
- Supporting evidence and examples from multiple sources
- Areas of agreement across sources
- Contradictions or debates (with citations)
- Practical implications
- Remaining gaps or open questions
4. **Draw evidence-based conclusions**
- Only make claims supported by multiple sources
- Note confidence level based on source quality and consensus
- Identify areas requiring further research
5. **Create executive summary**
- Synthesize key findings across all themes
- Highlight most important insights
- Note limitations of the research
**Synthesis writing principles:**
- Be comprehensive yet concise—capture all important insights without redundancy
- Cite liberally using `[[source-filename]]` format
- Make connections explicit between different sources and themes
- Distinguish between well-supported findings and tentative conclusions
- Note source quality in your assessments (per the "Evidence Quality Assessment" sections in summaries)
#### Step 8: Quality Review
Verify synthesis quality:
- [ ] All major themes from source summaries are represented
- [ ] Synthesis is organized thematically, not source-by-source
- [ ] Key findings are supported by citations to source summaries
- [ ] Contradictions and debates are identified and explained
- [ ] Conclusions are proportional to evidence strength
- [ ] Executive summary captures essential findings
- [ ] Writing is clear, precise, and information-dense
- [ ] All internal links work
- [ ] YAML frontmatter is complete
#### Step 9: Deliver Results
**Inform user:**
- Location of synthesis and all source summaries
- Summary of major findings and themes
- Note any limitations (inaccessible sources, areas with thin coverage, etc.)
- Highlight any unexpected or particularly significant discoveries
#### Research Approach Characteristics
**Characteristics:**
- Fast execution through simultaneous source investigation
- Efficient use of compute resources
- Requires well-defined research questions and angles upfront
**Best suited for:**
- Well-understood topics with clear structure
- Situations where research angles can be predetermined
- Time-sensitive research needs
- Cases where comprehensive breadth is essential
**Considerations:**
- Research plan should be thorough since pivoting mid-research isn't supported
- Initial source topic selection is critical for comprehensive coverage
---
### Source Quality Guidelines
**Include if:**
- Provides unique insights or data
- Represents authoritative voice
- Offers contrarian or edge perspectives
- Contains primary research or original analysis
## Verification
Upon completion:
1. Confirm all deliverables are created:
- `plan.md` with research strategy
- `synthesis.md` with thematic analysis
- `summaries/` directory with individual source analyses
2. Verify all internal citations link correctly
3. Check that synthesis is organized thematically, not by source
4. Ensure conclusions are proportional to evidence
## Expected Deliverables
```
[YOUR WORKING DIRECTORY]/
└── [RESEARCH TOPIC]/
├── summaries/
│ ├── source-1-summary.md
│ └── source-2-summary.md
├── plan.md
└── synthesis.md
```
## Notes
- This command orchestrates multiple `research-analyst` subagents for parallel source investigation
- Templates are located in `plugins/dot-claude/commands/templates/`
- The `analyzing-source` skill provides the analysis framework used by research-analyst
- Research quality depends on source accessibility and search result quality

55
commands/templates/article-summary.md Normal file
View File

@@ -0,0 +1,55 @@
---
created: YYYY-MM-DD
source_url: [URL or citation]
source_type: [academic/industry/community/expert/case-study]
tags: [research-topic, relevant-tags]
---
# [Source Title]
**Source:** [source_url]
## Citation
[Full citation information - include authors, date, publication, DOI/URL]
## Main Points / Features / Insights
1. [Main point / feature / insight 1]
2. [Main point / feature / insight 2]
3. [Main point / feature / insight 3]
## Methodology
[Research methods used, technical approach, data sources - if applicable]
## Relevance to Research Question
[How this source addresses the research topic and which research angles it informs]
## Notable Quotes
> "[Quote 1]" (page X / timestamp)
> "[Quote 2]" (page X / timestamp)
## Critical Evaluation
**Strengths:**
- [Strength 1]
- [Strength 2]
**Limitations:**
- [Limitation 1]
- [Limitation 2]
**Potential biases:**
- [Bias 1 if any]
## Connections to Other Sources
- Supports [[other-source-1]] on [topic]
- Contradicts [[other-source-2]] regarding [point]
- Extends work by [[other-source-3]]

71
commands/templates/research-plan.md Normal file
View File

@@ -0,0 +1,71 @@
---
created: YYYY-MM-DD
research_topic: [topic]
research_purpose: [purpose from Phase 1]
target_sources: [number]
status: planning
---
# Research Plan: [Topic]
## Research Purpose
[What this research will be used for]
## Scope
**Included:**
- [Area 1]
- [Area 2]
**Excluded:**
- [Out of scope item 1]
- [Out of scope item 2]
**Constraints:**
- Temporal: [if any]
- Domain: [if any]
- Other: [if any]
## Key Questions
1. [Question 1]
2. [Question 2]
3. [Question 3]
## Research Angles
1. **[Angle 1]**: [Brief description]
2. **[Angle 2]**: [Brief description]
3. **[Angle 3]**: [Brief description]
4. **[Angle 4]**: [Brief description if applicable]
5. **[Angle 5]**: [Brief description if applicable]
## Source Strategy
**Target total:** [number] sources
**By type:**
- Academic papers: [target number or %]
- Industry reports/whitepapers: [target number or %]
- Expert blogs/technical writing: [target number or %]
- Practitioner discussions: [target number or %]
- Company docs/case studies: [target number or %]
## Analysis Approach
[How research and analysis will be conducted]
## Expected Deliverables
1. [Deliverable 1]
2. [Deliverable 2]
## Potential Challenges
- [Challenge 1 and mitigation]
- [Challenge 2 and mitigation]

122
commands/templates/research-synthesis.md Normal file
View File

@@ -0,0 +1,122 @@
---
created: YYYY-MM-DD
modified: YYYY-MM-DD
research_topic: [topic]
research_purpose: [from Phase 1]
sources_analyzed: [number]
tags: [research, synthesis, topic-tags]
type: research-synthesis
---
# [Research Topic] - Synthesis
## Executive Summary
[250 word overview of key findings, most interesting data/examples, and main conclusions]
## Research Scope & Methodology
**Purpose:** [What this research aimed to accomplish]
**Scope:** [What was and wasn't covered]
**Sources consulted:** [number] sources across [types]
**Analysis approach:** [Thematic/Comparative/Chronological]
## Key Themes & Findings
### Theme 1: [Name]
[Findings organized by theme with citations to source summaries and original files]
**Key insights:**
- [Insight 1] [[source-summary]]
- [Insight 2] [[source-summary]]
### Theme 2: [Name]
[Findings with citations]
**Key insights:**
- [Insight 1]
- [Insight 2]
### Theme 3: [Name]
[Continue for all major themes]
## Patterns & Contradictions
**Areas of consensus:**
- [What multiple sources agree on]
**Areas of debate:**
- [What sources disagree on and why]
**Surprising findings:**
- [Unexpected or counterintuitive discoveries]
## Gaps & Limitations
**Unanswered questions:**
- [Question 1]
- [Question 2]
**Research limitations:**
- [Limitation 1]
- [Limitation 2]
**Future research directions:**
- [Direction 1]
- [Direction 2]
## Conclusions & Recommendations
**Key takeaways:**
1. [Takeaway 1 with evidence]
2. [Takeaway 2 with evidence]
3. [Takeaway 3 with evidence]
**Recommendations:**
1. [Actionable recommendation 1]
2. [Actionable recommendation 2]
**Confidence levels:**
- High confidence: [Claims with strong multi-source support]
- Medium confidence: [Claims with some support or emerging evidence]
- Low confidence: [Claims requiring further validation]
## Sources Consulted
### Academic & Peer-Reviewed
- [[source-summary-1]]
- [[source-summary-2]]
### Industry Reports & Whitepapers
- [[source-summary-3]]
### Expert & Technical Blogs
- [[source-summary-4]]
### Practitioner Discussions
- [[source-summary-5]]
### Case Studies & Company Docs
- [[source-summary-6]]

81
plugin.lock.json Normal file
View File

@@ -0,0 +1,81 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:Sawyer-Middeleer/dot-claude:plugins/dot-claude",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "d4f71da62b79408ee30dd24e28fac43a29d07804",
"treeHash": "dc248bd1c190afefb67523df29bc67941009ed3b5571239f77a394638fbd0d2c",
"generatedAt": "2025-11-28T10:12:44.830632Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "dot-claude",
"description": "Actually useful skills, agents, and commands for Claude Code - focused on research, analysis, and skill creation",
"version": "2.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "1abcff11249b7a1ccd44921d131d0d42f96a581b6425aeedde642fda4b75be3a"
},
{
"path": "agents/research-analyst.md",
"sha256": "9316309bd3f05b4be1a8bbf292934a2da8fc45a0acb7e6c507a365e488fb6dac"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "81af579fba765559da11f7e9e30464507439ff4af8476db1f9b6f4c0b462aa86"
},
{
"path": "commands/deep-research.md",
"sha256": "8dede2054e0113889a07c4d95df8f9ef9e59fa9c470030e6d6d6448780077ff8"
},
{
"path": "commands/templates/research-synthesis.md",
"sha256": "f45d95c496702eb494c1e10e963a7f78d718131b664cb0b751036f3890c2796f"
},
{
"path": "commands/templates/article-summary.md",
"sha256": "b8acfbbab1e1d0448c03b6f75eda31cfd3e8dd26dffeaeed5f2187ab6f9f5ecc"
},
{
"path": "commands/templates/research-plan.md",
"sha256": "5abde7b913e23be04277a1db6f250dee38d6ba4c59c9acb6efd1074d4ab1dd89"
},
{
"path": "skills/creating-skills/SKILL.md",
"sha256": "3bddb4adf0151b26ff7bfaa4b8c5c9f66dfe9b0621b9e1b5579b560b884be075"
},
{
"path": "skills/creating-skills/reference/scripts-and-code.md",
"sha256": "5f30ace3f4ca05f088e723fc10cafc59ffd4a00e8e9038bc583b10c525636f38"
},
{
"path": "skills/creating-skills/reference/architecture-diagrams.md",
"sha256": "efc16f76023043277e335e33810f4f87afdb1a532e6cb56128e0ca0ca9dbafc1"
},
{
"path": "skills/analyzing-source/SKILL.md",
"sha256": "b9863f4940b97c17575707fcd1dd0a3ac893834e45c75b22e986ad3b8c8c6aaa"
},
{
"path": "skills/analyzing-source/templates/article-summary.md",
"sha256": "223461bff4f724b82cd201b8eb36f31cf7f8c884288bee4d3c97cecc65138f46"
}
],
"dirSha256": "dc248bd1c190afefb67523df29bc67941009ed3b5571239f77a394638fbd0d2c"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

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)