Research Goal: Best practices for Claude Code skill organization

Search Query: "Claude Code skills" progressive disclosure 2025

Findings:
1. Progressive disclosure pattern (from official Anthropic docs):
   - SKILL.md: Main entry, <5000 words
   - references/: Detailed guides, on-demand
   - scripts/: Automation utilities

2. YAML frontmatter requirements (from skill-creator):
   - name: hyphen-case
   - description: with "Use when" triggers

3. Community patterns (from 40+ skills analyzed):
   - Workflow-based: 45% of skills
   - Task-based: 30% of skills
   - Reference: 15% of skills
   - Capabilities: 10% of skills

Sources:
- https://docs.claude.com/en/docs/claude-code/...
- https://github.com/anthropics/anthropic-skills/...

Research Goal: Find MCP servers for file system operations

Servers Found:

1. **filesystem MCP Server** (Official Anthropic)
   - Tools: read_file, write_file, edit_file, list_directory, search_files
   - Platform: Python, Node
   - Installation: npm install @modelcontextprotocol/server-filesystem
   - Use Case: File operations in Claude Code skills
   - Maturity: Official, well-maintained
   - Limitations: Limited to local filesystem

2. **aws-s3 MCP Server** (Community)
   - Tools: s3_read, s3_write, s3_list, s3_delete
   - Platform: Python
   - Installation: pip install mcp-server-aws-s3
   - Use Case: Cloud storage integration
   - Maturity: 150 stars, active development
   - Limitations: Requires AWS credentials

Recommendation: Use official filesystem server for local operations,
consider aws-s3 for cloud storage needs.

Research Goal: How to structure Claude Code skills with workflows

Repository: anthropic/anthropic-skills (example-skills)

Findings:

1. **Workflow Structure Pattern** (deployment-guide/SKILL.md):
   ```markdown
   ## Deployment Workflow

   ### Step 1: Prepare Application
   [Instructions]

   ### Step 2: Configure Railway
   [Instructions]

   ### Step 3: Deploy
   [Instructions]

**Expected Outcome**:
- Code patterns documented with examples
- File/directory structures captured
- Architectural approaches identified
- Best practices extracted
- Repository sources cited

**Validation**:
- [ ] Multiple repositories analyzed (3-5 minimum)
- [ ] Code snippets captured with location references
- [ ] Patterns identified across repositories
- [ ] Context of usage documented
- [ ] Best practices vs anti-patterns distinguished

**Common Issues**:
- **Issue**: Repository too large to analyze
  - **Solution**: Focus on specific directories relevant to research goal
- **Issue**: Code patterns unclear
  - **Solution**: Read tests, examples, documentation first
- **Issue**: Outdated repository
  - **Solution**: Check commit dates, look for active forks

**Tips for GitHub Research**:
- Use advanced search (stars:>100, language:python, etc.)
- Check examples/ or samples/ directories first
- Read CONTRIBUTING.md for patterns
- Look at tests/ for usage examples
- Check issues for edge cases and solutions

---

Research Goal: Claude Code skill structure requirements

Source: https://docs.claude.com/en/docs/claude-code/skills

Findings:

1. **Skill Structure Requirements**:
   - SKILL.md must have YAML frontmatter
   - Frontmatter fields: name, description
   - Progressive disclosure: SKILL.md < 15,000 words
   - Use references/ for detailed content
   - scripts/ for automation utilities

2. **YAML Frontmatter Specification**:
   ```yaml
   ---
   name: skill-name-in-hyphen-case
   description: Brief description. Use when [triggers].
   ---

**Expected Outcome**:
- Comprehensive documentation summary
- Specific requirements captured
- Code examples copied accurately
- URLs referenced for verification
- Version/date noted

**Validation**:
- [ ] Official documentation identified and verified
- [ ] Key concepts extracted and defined
- [ ] Code examples captured accurately
- [ ] Specifications documented precisely
- [ ] Page URLs recorded for reference
- [ ] Version/date information noted

**Common Issues**:
- **Issue**: Documentation unclear or incomplete
  - **Solution**: Check examples, search for supplementary guides
- **Issue**: Multiple documentation versions
  - **Solution**: Use most recent, note version explicitly
- **Issue**: Conflicting information
  - **Solution**: Reference official docs over community content

**Tips for Documentation Research**:
- Start with "Getting Started" or "Quickstart"
- Read conceptual guides before API reference
- Check changelog/releases for recent changes
- Look for "Best Practices" or "Recommendations" sections
- Copy examples exactly (don't paraphrase)
- Note warnings and "gotchas" prominently

---

undefined

undefined

undefined

**Expected Outcome**:
- Comprehensive synthesis document
- Clear patterns identified
- Actionable recommendations
- Conflicts resolved
- Sources cited

**Validation**:
- [ ] Findings from all sources incorporated
- [ ] Patterns identified across multiple sources
- [ ] Recommendations are actionable
- [ ] Conflicts identified and resolved
- [ ] Sources properly cited
- [ ] Document organized clearly

**Common Issues**:
- **Issue**: Too much information, overwhelmed
  - **Solution**: Focus on research goal, organize by theme
- **Issue**: Contradictory findings
  - **Solution**: Prioritize official sources, note context differences
- **Issue**: Can't find patterns
  - **Solution**: Look for what appears 2-3+ times across sources

**Tips for Synthesis**:
- Use consistent format for all research findings
- Group similar findings before synthesizing
- Prioritize quality over quantity (3 good sources > 10 weak)
- Make recommendations specific and actionable
- Note what you still don't know (further research needed)

---