Initial commit

2025-11-30 08:48:52 +08:00
commit 6ec3196ecc
434 changed files with 125248 additions and 0 deletions
--- a/skills/docs-seeker/references/tool-selection.md
+++ b/skills/docs-seeker/references/tool-selection.md
@@ -0,0 +1,262 @@
+# Tool Selection Guide
+
+Complete reference for choosing and using the right tools for documentation discovery.
+
+## context7.com (PRIORITY)
+
+**Use FIRST for all llms.txt lookups**
+
+**Patterns:**
+
+GitHub repositories:
+```
+Pattern: https://context7.com/{org}/{repo}/llms.txt
+Examples:
+- https://github.com/vercel/next.js → https://context7.com/vercel/next.js/llms.txt
+- https://github.com/shadcn-ui/ui → https://context7.com/shadcn-ui/ui/llms.txt
+```
+
+Websites:
+```
+Pattern: https://context7.com/websites/{normalized-path}/llms.txt
+Examples:
+- https://docs.imgix.com/ → https://context7.com/websites/imgix/llms.txt
+- https://ffmpeg.org/doxygen/8.0/ → https://context7.com/websites/ffmpeg_doxygen_8_0/llms.txt
+```
+
+Topic-specific searches:
+```
+Pattern: https://context7.com/{path}/llms.txt?topic={query}
+Examples:
+- https://context7.com/shadcn-ui/ui/llms.txt?topic=date
+- https://context7.com/vercel/next.js/llms.txt?topic=cache
+- https://context7.com/websites/ffmpeg_doxygen_8_0/llms.txt?topic=compress
+```
+
+**Benefits:**
+- Comprehensive aggregator of documentation
+- Up-to-date content
+- Topic filtering for targeted results
+- Consistent format across libraries
+- Reduces search time
+
+**When to use:**
+- ALWAYS try context7.com first before WebSearch
+- Use topic parameter when user asks about specific feature
+- Fall back to WebSearch only if context7.com returns 404
+
+## WebSearch
+
+**Use when:**
+- context7.com unavailable or returns 404
+- Finding GitHub repository URLs
+- Locating official documentation sites
+- Identifying package registries
+- Searching for specific versions
+
+**Best practices:**
+- Try context7.com FIRST
+- Include domain in query: `site:docs.example.com`
+- Specify version when needed: `v2.0 llms.txt`
+- Use official terms: "official repository" "documentation"
+- Check multiple domains if first fails
+
+**Example queries:**
+```
+Good: "Next.js llms.txt site:nextjs.org"
+Good: "React v18 documentation site:react.dev"
+Good: "Vue 3 official github repository"
+
+Avoid: "how to use react" (too vague)
+Avoid: "best react tutorial" (not official)
+```
+
+## WebFetch
+
+**Use when:**
+- Reading llms.txt content
+- Accessing single documentation pages
+- Retrieving specific URLs
+- Checking documentation structure
+- Verifying content availability
+
+**Best practices:**
+- Use specific prompt: "Extract all documentation URLs"
+- Handle redirects properly
+- Check for rate limiting
+- Verify content is complete
+- Note last-modified dates when available
+
+**Limitations:**
+- Single URL at a time (use Explorer for multiple)
+- May timeout on very large pages
+- Cannot handle dynamic content
+- No JavaScript execution
+
+## Task Tool with Explore Subagent
+
+**Use when:**
+- Multiple URLs to read (3+)
+- Need parallel exploration
+- Comprehensive documentation coverage
+- Time-sensitive requests
+- Large documentation sets
+
+**Best practices:**
+- Launch all agents in single message
+- Distribute workload evenly
+- Group related URLs per agent
+- Maximum 7 agents per batch
+- Provide clear extraction goals
+
+**Example prompt:**
+```
+"Read the following URLs and extract:
+1. Installation instructions
+2. Core API methods
+3. Configuration options
+4. Common usage examples
+
+URLs:
+- [url1]
+- [url2]
+- [url3]"
+```
+
+## Task Tool with Researcher Subagent
+
+**Use when:**
+- No structured documentation found
+- Need diverse information sources
+- Community knowledge required
+- Scattered documentation
+- Comparative analysis needed
+
+**Best practices:**
+- Assign specific research areas per agent
+- Request source verification
+- Ask for date/version information
+- Prioritize official sources
+- Cross-reference findings
+
+**Example prompt:**
+```
+"Research [library] focusing on:
+1. Official installation methods
+2. Common usage patterns
+3. Known limitations or issues
+4. Community best practices
+
+Prioritize official sources and note version/date for all findings."
+```
+
+## Repomix
+
+**Use when:**
+- GitHub repository available
+- Need complete codebase analysis
+- Documentation scattered in repository
+- Want to analyze code structure
+- API documentation in code comments
+
+**Installation:**
+```bash
+# Check if installed
+which repomix
+
+# Install globally if needed
+npm install -g repomix
+
+# Verify installation
+repomix --version
+```
+
+**Usage:**
+```bash
+# Basic usage
+git clone [repo-url] /tmp/docs-analysis
+cd /tmp/docs-analysis
+repomix --output repomix-output.xml
+
+# Focus on specific directory
+repomix --include "docs/**" --output docs-only.xml
+
+# Exclude large files
+repomix --exclude "*.png,*.jpg,*.pdf" --output repomix-output.xml
+```
+
+**When Repomix may fail:**
+- Repository > 1GB (too large)
+- Requires authentication (private repo)
+- Slow network connection
+- Limited disk space
+- Binary-heavy repository
+
+**Alternatives if Repomix fails:**
+```bash
+# Option 1: Focus on docs directory only
+repomix --include "docs/**,README.md" --output docs.xml
+
+# Option 2: Use Explorer agents to read specific files
+# Launch agents to read key documentation files directly
+
+# Option 3: Manual repository exploration
+# Read README, then explore /docs directory structure
+```
+
+## Tool Selection Decision Tree
+
+```
+Need documentation?
+  ↓
+Try context7.com first
+  ↓
+Know GitHub org/repo?
+  YES → https://context7.com/{org}/{repo}/llms.txt
+  NO → Continue
+  ↓
+Know website URL?
+  YES → https://context7.com/websites/{normalized-path}/llms.txt
+  NO → Continue
+  ↓
+Specific topic/feature?
+  YES → Add ?topic={query} parameter
+  NO → Use base llms.txt URL
+  ↓
+context7.com found?
+  YES → Process llms.txt URLs (go to URL count check)
+  NO → Continue
+  ↓
+Fallback: WebSearch for llms.txt
+  ↓
+Single URL?
+  YES → WebFetch
+  NO → Continue
+  ↓
+1-3 URLs?
+  YES → Single Explorer agent
+  NO → Continue
+  ↓
+4+ URLs?
+  YES → Multiple Explorer agents (3-7)
+  NO → Continue
+  ↓
+Need repository analysis?
+  YES → Repomix (if available)
+  NO → Continue
+  ↓
+No structured docs?
+  YES → Researcher agents
+```
+
+## Quick Reference
+
+| Tool | Best For | Speed | Coverage | Complexity |
+|------|----------|-------|----------|------------|
+| context7.com | llms.txt lookup | Instant | High | Low |
+| context7.com?topic= | Targeted search | Instant | Focused | Low |
+| WebSearch | Finding URLs | Fast | Narrow | Low |
+| WebFetch | Single page | Fast | Single | Low |
+| Explorer | Multiple URLs | Fast | Medium | Medium |
+| Researcher | Scattered info | Slow | Wide | High |
+| Repomix | Repository | Medium | Complete | Medium |