ai-qakit 1.0.0

package/templates/.claude/skills/docs-discovery/README.md

@@ -0,0 +1,53 @@
+# Documentation Discovery Skill
+
+**Version 4.0** - Simplified, LLM-first approach
+
+## What Changed
+
+### Before (v3.x)
+- 600+ lines of Node.js scripts for pattern matching
+- Hardcoded regex for English queries only
+- Programmatic URL construction
+- Complex categorization logic
+- Zero flexibility for creative queries
+
+### After (v4.0)
+- Simple prompts guide Claude's natural reasoning
+- Works with any language, handles typos, creative phrasing
+- Uses basic curl/grep for data retrieval
+- Claude does intelligent categorization
+- Fully adaptable and maintainable
+
+## Key Principles
+
+1. **Skills provide PROMPTS, not scripts** - Guide Claude's intelligence, don't replace it
+2. **LLM for reasoning, bash for data** - Use Claude for analysis, curl/grep for retrieval
+3. **Flexibility over rigidity** - Adapt to any query style, not just hardcoded patterns
+4. **Maintainability** - Update URL patterns in markdown, not code
+
+## Usage
+
+See `SKILL.md` for complete documentation.
+
+**Quick example:**
+```
+User: "How do I use date picker in shadcn?"
+
+Claude analyzes:
+- Library: shadcn/ui → shadcn-ui/ui
+- Topic: date
+
+Claude fetches:
+curl "https://context7.com/shadcn-ui/ui/llms.txt?topic=date"
+
+Claude processes results and presents documentation
+```
+
+## Migration Notes
+
+If you were using the old scripts:
+- `detect-topic.js` → Claude analyzes queries naturally
+- `fetch-docs.js` → Use curl commands from SKILL.md
+- `analyze-llms-txt.js` → Claude reasons about URL priorities
+
+Old scripts archived in `archive/` directory for reference.

package/templates/.claude/skills/docs-discovery/REFACTORING_SUMMARY.md

@@ -0,0 +1,144 @@
+# docs-discovery Skill Refactoring Summary
+
+**Date:** 2025-12-06
+**Version:** 3.1.0 → 4.0.0
+**Type:** Major simplification - LLM-first design
+
+## What Was Done
+
+### 1. Removed Complex Scripts (600+ lines)
+Archived to `archive/` directory:
+- `scripts/detect-topic.js` (171 lines) - Regex pattern matching
+- `scripts/fetch-docs.js` (214 lines) - Programmatic URL construction  
+- `scripts/analyze-llms-txt.js` (212 lines) - Hardcoded categorization
+- `scripts/tests/` (252 lines) - Unit tests for scripts
+- `workflows/` (3 files) - Script-centric workflow docs
+- `references/` (3 files) - Supporting documentation
+
+### 2. Created Simplified Prompt-Based Skill
+New `SKILL.md` (211 lines):
+- Simple prompts guide Claude's natural reasoning
+- Clear examples for library + topic extraction
+- Basic curl/grep commands for data retrieval
+- Flexible categorization guidelines
+- Agent distribution decision framework
+
+### 3. Documentation
+- `README.md` - Quick overview and migration guide
+- `COMPARISON.md` - Detailed before/after analysis
+- `REFACTORING_SUMMARY.md` - This file
+
+## Results
+
+### Quantitative Improvements
+- **65% reduction** in total code (600+ → 211 lines)
+- **87% reduction** in file count (15+ → 2 files)
+- **Zero dependencies** (removed Node.js requirement)
+- **100% language support** (works with any language, not just English)
+- **Infinite flexibility** (adapts to typos, creative phrasing, new frameworks)
+
+### Qualitative Improvements
+- **Maintainability:** Update markdown instead of code
+- **Flexibility:** Handles edge cases naturally
+- **Simplicity:** No build/test/deploy cycle
+- **Robustness:** Self-correcting through LLM reasoning
+- **Performance:** Fewer shell executions, no context switches
+
+## Key Insight
+
+**Skills should provide PROMPTS, not SCRIPTS**
+
+The old approach tried to programmatically replicate intelligence that Claude already possesses:
+- Pattern matching → Claude understands intent naturally
+- Normalization → Claude handles variations
+- Categorization → Claude reasons about priorities
+- Error handling → Claude adapts to context
+
+The new approach:
+- Teaches Claude the URL patterns
+- Provides decision frameworks
+- Uses bash tools for dumb data retrieval only
+- Lets Claude do the intelligent work
+
+## Example Comparison
+
+**Query:** "Next.jsのキャッシュ戦略" (Japanese: "Next.js caching strategies")
+
+**Before (v3.x):**
+```bash
+node scripts/detect-topic.js "Next.jsのキャッシュ戦略"
+# ❌ FAILED - No regex matches Japanese text
+```
+
+**After (v4.0):**
+```
+Claude analyzes: "Next.js caching in Japanese"
+→ Library: vercel/next.js
+→ Topic: cache
+→ curl "https://context7.com/vercel/next.js/llms.txt?topic=cache"
+✅ SUCCESS
+```
+
+## Migration Path
+
+**For users of the old skill:**
+1. No action required - skill auto-updates
+2. Old scripts still available in `archive/` for reference
+3. New version handles all previous use cases + more
+
+**For skill developers:**
+- Study this refactoring as a template
+- Apply "prompts over scripts" principle to your skills
+- Use bash tools (curl/grep) for data, LLM for reasoning
+
+## Files Changed
+
+**Removed from active use:**
+```
+scripts/
+  ├── detect-topic.js
+  ├── fetch-docs.js
+  ├── analyze-llms-txt.js
+  ├── utils/env-loader.js
+  └── tests/ (3 test files)
+workflows/
+  ├── topic-search.md
+  ├── library-search.md
+  └── repo-analysis.md
+references/
+  ├── context7-patterns.md
+  ├── errors.md
+  └── advanced.md
+package.json
+.env.example
+```
+
+**New active files:**
+```
+SKILL.md (211 lines) - Main skill prompt
+README.md (53 lines) - Quick start guide
+COMPARISON.md (313 lines) - Detailed analysis
+```
+
+## Lessons Learned
+
+1. **Don't replicate LLM intelligence in code** - Claude can reason, let it
+2. **Bash tools for data only** - curl, grep, awk for retrieval, not processing
+3. **Prompts are more maintainable** - Markdown edits vs code changes
+4. **Examples > Rules** - Show Claude what good looks like
+5. **Trust the LLM** - It handles edge cases better than hardcoded logic
+
+## Next Steps
+
+This refactoring establishes a pattern for other skills to follow:
+1. Identify programmatic logic that replicates LLM reasoning
+2. Replace with clear prompts and examples
+3. Keep only essential data retrieval tools
+4. Document the "why" not just the "what"
+5. Let Claude adapt and self-correct
+
+## References
+
+- **SKILL.md** - Complete skill documentation
+- **COMPARISON.md** - Detailed before/after analysis
+- **archive/** - Original scripts for reference

package/templates/.claude/skills/docs-discovery/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: docs-discovery
+description: "Technical documentation discovery via context7 and web search. Capabilities: library/framework docs lookup, topic-specific search. Keywords: llms.txt, context7, documentation, library docs, API docs. Use when: searching library documentation, finding framework guides, looking up API references."
+version: 7.0.0
+---
+
+# Documentation Discovery
+
+**Mission:** Find official library/framework documentation quickly.
+
+## Strategy
+
+### Step 1: Try context7 First
+
+```
+mcp__context7__resolve-library-id("{library}")
+→ Success? → mcp__context7__get-library-docs("{id}", topic="{topic}")
+→ Fail? → Step 2
+```
+
+### Step 2: Search for Documentation URLs
+
+**If context7 fails, run these searches in parallel:**
+
+```
+WebSearch: "{library} llms.txt"
+WebSearch: "{library} official documentation"
+```
+
+### Step 3: Fetch Found URLs
+
+**WebFetch the URLs found from Step 2:**
+- llms.txt links → fetch and parse
+- Documentation pages → fetch and extract content
+
+## Workflow Summary
+
+```
+1. context7 (fast, curated)
+   ↓ fail
+2. WebSearch (parallel):
+   - "{library} llms.txt"
+   - "{library} official documentation"
+   ↓ found URLs
+3. WebFetch found URLs
+   ↓ content
+4. Parse & present to user
+```
+
+## Tools
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| 1 | `mcp__context7__resolve-library-id` | Get context7 library ID |
+| 1 | `mcp__context7__get-library-docs` | Fetch docs from context7 |
+| 2 | `WebSearch` | Search for llms.txt and docs URLs |
+| 3 | `WebFetch` | Fetch documentation content |
+
+## Key Rules
+
+- **context7 first** - Fastest, already curated
+- **Search, don't guess** - Don't guess URL patterns, search for them
+- **Parallel search** - Run multiple WebSearch queries together
+- **Topic filtering** - Use topic param in context7, filter search results by topic

package/templates/.claude/skills/docs-discovery/archive/dot_env.example

@@ -0,0 +1,15 @@
+# Context7 API Configuration (optional)
+# Get your API key from https://context7.com/dashboard/api-keys
+CONTEXT7_API_KEY=
+
+# Gemini API Configuration (optional, for ai-multimodal integration)
+# Get your API key from https://aistudio.google.com/app/apikey
+GEMINI_API_KEY=
+
+# GitHub Token (optional, for higher rate limits on repository analysis)
+# Create at https://github.com/settings/tokens
+GITHUB_TOKEN=
+
+# Output settings
+OUTPUT_FORMAT=json
+DEBUG=false

package/templates/.claude/skills/docs-discovery/archive/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "docs-discovery-scripts",
+  "version": "3.0.0",
+  "description": "Documentation discovery scripts for docs-discovery skill",
+  "private": true,
+  "scripts": {
+    "test": "node scripts/tests/run-tests.js",
+    "test:detect": "node scripts/tests/test-detect-topic.js",
+    "test:fetch": "node scripts/tests/test-fetch-docs.js",
+    "test:analyze": "node scripts/tests/test-analyze-llms.js"
+  },
+  "keywords": [
+    "documentation",
+    "llms.txt",
+    "context7",
+    "docs-discovery"
+  ],
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/templates/.claude/skills/docs-discovery/archive/references/advanced.md

@@ -0,0 +1,79 @@
+# Advanced Scenarios & Edge Cases
+
+## Multi-Language Documentation
+
+**Challenge:** Docs in multiple languages
+
+**Approach:**
+1. Identify target language from user
+2. Search for language-specific llms.txt
+   - `llms-es.txt`, `llms-ja.txt`
+3. Fallback to English if not found
+4. Note language limitations in report
+
+## Version-Specific Documentation
+
+**Latest (default):**
+- Use base llms.txt URL
+- No version specifier needed
+
+**Specific version:**
+```
+WebSearch: "[library] v[version] llms.txt"
+Check paths:
+- /v2/llms.txt
+- /docs/v2/llms.txt
+- /{version}/llms.txt
+
+For repos:
+git checkout v[version] or tags/[version]
+```
+
+## Framework with Plugins
+
+**Challenge:** Core framework + 50 plugins
+
+**Strategy:**
+1. Focus on core framework first
+2. Ask user which plugins needed
+3. Launch targeted search for specific plugins
+4. Note available plugins in report
+5. Don't document everything upfront
+
+## Documentation Under Construction
+
+**Signs:**
+- New release with incomplete docs
+- Many "Coming soon" pages
+- GitHub issues requesting docs
+
+**Approach:**
+1. Note status upfront in report
+2. Combine available docs + repo analysis
+3. Check tests/ and examples/ directories
+4. Clearly mark "inferred from code"
+5. Link to GitHub issues for updates
+
+## Conflicting Information
+
+**When sources disagree:**
+1. Identify primary official source
+2. Note version differences
+3. Present both approaches with context
+4. Recommend official/latest
+5. Explain why conflict exists
+
+**Priority order:**
+1. Official docs (latest version)
+2. Official docs (versioned)
+3. GitHub README
+4. Community tutorials
+5. Stack Overflow
+
+## Rate Limiting
+
+**If hitting API limits:**
+- Use CONTEXT7_API_KEY from .env
+- Implement exponential backoff
+- Cache results in session
+- Batch requests where possible

package/templates/.claude/skills/docs-discovery/archive/references/context7-patterns.md

@@ -0,0 +1,68 @@
+# context7.com URL Patterns
+
+## Topic-Specific URLs (Priority #1)
+
+**Pattern:** `https://context7.com/{path}/llms.txt?topic={keyword}`
+
+**When to use:** User asks about specific feature/component
+
+**Examples:**
+```
+shadcn/ui date picker
+→ https://context7.com/shadcn-ui/ui/llms.txt?topic=date
+
+Next.js caching
+→ https://context7.com/vercel/next.js/llms.txt?topic=cache
+
+Better Auth OAuth
+→ https://context7.com/better-auth/better-auth/llms.txt?topic=oauth
+
+FFmpeg compression
+→ https://context7.com/websites/ffmpeg_doxygen_8_0/llms.txt?topic=compress
+```
+
+**Benefits:** Returns ONLY relevant docs, 10x faster, minimal tokens
+
+## General Library URLs (Priority #2)
+
+**GitHub repos:** `https://context7.com/{org}/{repo}/llms.txt`
+
+**Websites:** `https://context7.com/websites/{normalized-path}/llms.txt`
+
+## Known Repository Mappings
+
+```
+next.js → vercel/next.js
+nextjs → vercel/next.js
+astro → withastro/astro
+remix → remix-run/remix
+shadcn → shadcn-ui/ui
+shadcn/ui → shadcn-ui/ui
+better-auth → better-auth/better-auth
+```
+
+## Official Site Fallbacks
+
+Use ONLY if context7.com unavailable:
+```
+Astro: https://docs.astro.build/llms.txt
+Next.js: https://nextjs.org/llms.txt
+Remix: https://remix.run/llms.txt
+SvelteKit: https://kit.svelte.dev/llms.txt
+```
+
+## Topic Keyword Normalization
+
+**Rules:**
+- Lowercase
+- Remove special chars
+- Use first word for multi-word topics
+- Max 20 chars
+
+**Examples:**
+```
+"date picker" → "date"
+"OAuth" → "oauth"
+"Server-Side" → "server"
+"caching strategies" → "caching"
+```

package/templates/.claude/skills/docs-discovery/archive/references/errors.md

@@ -0,0 +1,68 @@
+# Error Handling & Fallback Strategies
+
+## Error Codes
+
+**404 Not Found**
+- Topic-specific URL not available
+- Library not on context7.com
+- llms.txt doesn't exist
+
+**Timeout**
+- Network issues
+- Large repository clone
+- Slow API response
+
+**Invalid Response**
+- Malformed llms.txt
+- Empty content
+- Invalid URLs
+
+## Fallback Chain
+
+### For Topic-Specific Queries
+
+```
+1. Try topic-specific URL
+   https://context7.com/{library}/llms.txt?topic={keyword}
+   ↓ 404
+2. Try general library URL
+   https://context7.com/{library}/llms.txt
+   ↓ 404
+3. WebSearch for llms.txt
+   "[library] llms.txt site:[official domain]"
+   ↓ Not found
+4. Repository analysis
+   Use Repomix on GitHub repo
+```
+
+### For General Library Queries
+
+```
+1. Try context7.com
+   https://context7.com/{library}/llms.txt
+   ↓ 404
+2. WebSearch for llms.txt
+   "[library] llms.txt"
+   ↓ Not found
+3. Repository analysis
+   Clone + Repomix
+   ↓ No repo
+4. Research agents
+   Deploy multiple Researcher agents
+```
+
+## Timeout Handling
+
+**Set limits:**
+- WebFetch: 60s
+- Repository clone: 5min
+- Repomix: 10min
+
+**Fail fast:** Don't retry failed methods
+
+## Empty Results
+
+**If llms.txt has 0 URLs:**
+→ Note in report
+→ Try repository analysis
+→ Check official website manually