chore: import upstream snapshot with attribution

docs/reference/AI_SKILL_STANDARDS.md

@@ -0,0 +1,926 @@
+# AI Skill Standards & Best Practices (2026)
+
+**Version:** 1.0
+**Last Updated:** 2026-01-11
+**Scope:** Cross-platform AI skills for Claude, Gemini, OpenAI, and generic LLMs
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Universal Standards](#universal-standards)
+3. [Platform-Specific Guidelines](#platform-specific-guidelines)
+4. [Knowledge Base Design Patterns](#knowledge-base-design-patterns)
+5. [Quality Grading Rubric](#quality-grading-rubric)
+6. [Common Pitfalls](#common-pitfalls)
+7. [Future-Proofing](#future-proofing)
+
+---
+
+## Introduction
+
+This document establishes the definitive standards for AI skill creation based on 2026 industry best practices, official platform documentation, and emerging patterns in agentic AI systems.
+
+### What is an AI Skill?
+
+An **AI skill** is a focused knowledge package that enhances an AI agent's capabilities in a specific domain. Skills include:
+- **Instructions**: How to use the knowledge
+- **Context**: When the skill applies
+- **Resources**: Reference documentation, examples, patterns
+- **Metadata**: Discovery, versioning, platform compatibility
+
+### Design Philosophy
+
+Modern AI skills follow three core principles:
+
+1. **Progressive Disclosure**: Load information only when needed (metadata → instructions → resources)
+2. **Context Economy**: Every token competes with conversation history
+3. **Cross-Platform Portability**: Design for the open Agent Skills standard
+
+---
+
+## Universal Standards
+
+These standards apply to **all platforms** (Claude, Gemini, OpenAI, generic).
+
+### 1. Naming Conventions
+
+**Format**: Gerund form (verb + -ing)
+
+**Why**: Clearly describes the activity or capability the skill provides.
+
+**Examples**:
+- ✅ "Building React Applications"
+- ✅ "Working with Django REST Framework"
+- ✅ "Analyzing Godot 4.x Projects"
+- ❌ "React Documentation" (passive, unclear)
+- ❌ "Django Guide" (vague)
+
+**Implementation**:
+```yaml
+name: building-react-applications  # kebab-case, gerund form
+description: Building modern React applications with hooks, routing, and state management
+```
+
+### 2. Description Field (Critical for Discovery)
+
+**Format**: Third person, actionable, includes BOTH "what" and "when"
+
+**Why**: Injected into system prompts; inconsistent POV causes discovery problems.
+
+**Structure**:
+```
+[What it does]. Use when [specific triggers/scenarios].
+```
+
+**Examples**:
+- ✅ "Building modern React applications with TypeScript, hooks, and routing. Use when implementing React components, managing state, or configuring build tools."
+- ✅ "Analyzing Godot 4.x game projects with GDScript patterns. Use when debugging game logic, optimizing performance, or implementing new features in Godot."
+- ❌ "I will help you with React" (first person, vague)
+- ❌ "Documentation for Django" (no when clause)
+
+### 3. Token Budget (Progressive Disclosure)
+
+**Token Allocation**:
+- **Metadata loading**: ~100 tokens (YAML frontmatter + description)
+- **Full instructions**: <5,000 tokens (main SKILL.md without references)
+- **Bundled resources**: Load on-demand only
+
+**Why**: Token efficiency is critical—unused context wastes capacity.
+
+**Best Practice**:
+```markdown
+## Quick Reference
+*30-second overview with most common patterns*
+
+[Core content - 3,000-4,500 tokens]
+
+## Extended Reference
+*See references/api.md for complete API documentation*
+```
+
+### 4. Conciseness & Relevance
+
+**Principles**:
+- Every sentence must provide **unique value**
+- Remove redundancy, filler, and "nice to have" information
+- Prioritize **actionable** over **explanatory** content
+- Use progressive disclosure: Quick Reference → Deep Dive → References
+
+**Example Transformation**:
+
+**Before** (130 tokens):
+```
+React is a popular JavaScript library for building user interfaces.
+It was created by Facebook and is now maintained by Meta and the
+open-source community. React uses a component-based architecture
+where you build encapsulated components that manage their own state.
+```
+
+**After** (35 tokens):
+```
+Component-based UI library. Build reusable components with local
+state, compose them into complex UIs, and efficiently update the
+DOM via virtual DOM reconciliation.
+```
+
+### 5. Structure & Organization
+
+**Required Sections** (in order):
+
+```markdown
+---
+name: skill-name
+description: [What + When in third person]
+---
+
+# Skill Title
+
+[1-2 sentence elevator pitch]
+
+## 💡 When to Use This Skill
+
+[3-5 specific scenarios with trigger phrases]
+
+## ⚡ Quick Reference
+
+[30-second overview, most common patterns]
+
+## 📝 Code Examples
+
+[Real-world, tested, copy-paste ready]
+
+## 🔧 API Reference
+
+[Core APIs, signatures, parameters - link to full reference]
+
+## 🏗️ Architecture
+
+[Key patterns, design decisions, trade-offs]
+
+## ⚠️ Common Issues
+
+[Known problems, workarounds, gotchas]
+
+## 📚 References
+
+[Links to deeper documentation]
+```
+
+**Optional Sections**:
+- Installation
+- Configuration
+- Testing Patterns
+- Migration Guides
+- Performance Tips
+
+### 6. Code Examples Quality
+
+**Standards**:
+- **Tested**: From official docs, test suites, or production code
+- **Complete**: Copy-paste ready, not fragments
+- **Annotated**: Brief explanation of what/why, not how (code shows how)
+- **Progressive**: Basic → Intermediate → Advanced
+- **Diverse**: Cover common use cases (80% of user needs)
+
+**Format**:
+```markdown
+### Example: User Authentication
+
+```typescript
+// Complete working example
+import { useState } from 'react';
+import { signIn } from './auth';
+
+export function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    await signIn(email, password);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={email} onChange={e => setEmail(e.target.value)} />
+      <input type="password" value={password} onChange={e => setPassword(e.target.value)} />
+      <button type="submit">Sign In</button>
+    </form>
+  );
+}
+```
+
+**Why this works**: Demonstrates state management, event handling, async operations, and TypeScript types in a real-world pattern.
+```
+
+### 7. Cross-Platform Compatibility
+
+**File Structure** (Open Agent Skills Standard):
+```
+skill-name/
+├── SKILL.md                # Main instructions (<5k tokens)
+├── skill.yaml              # Metadata (optional, redundant with frontmatter)
+├── references/             # On-demand resources
+│   ├── api.md
+│   ├── patterns.md
+│   ├── examples/
+│   │   ├── basic.md
+│   │   └── advanced.md
+│   └── index.md
+└── resources/              # Optional: scripts, configs, templates
+    ├── .clinerules
+    └── templates/
+```
+
+**YAML Frontmatter** (required for all platforms):
+```yaml
+---
+name: skill-name              # kebab-case, max 64 chars
+description: >                # What + When, max 1024 chars
+  Building modern React applications with TypeScript.
+  Use when implementing React components or managing state.
+version: 1.0.0                # Semantic versioning
+platforms:                    # Tested platforms
+  - claude
+  - gemini
+  - openai
+  - markdown
+tags:                         # Discovery keywords
+  - react
+  - typescript
+  - frontend
+  - web
+---
+```
+
+---
+
+## Platform-Specific Guidelines
+
+### Claude AI (Agent Skills)
+
+**Official Standard**: [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+**Key Differences**:
+- **Discovery**: Description injected into system prompt—must be third person
+- **Token limit**: ~5k tokens for main SKILL.md (hard limit for fast loading)
+- **Loading behavior**: Claude loads skill when description matches user intent
+- **Resource access**: References loaded on-demand via file reads
+
+**Best Practices**:
+- Use emojis for section headers (improves scannability): 💡 ⚡ 📝 🔧 🏗️ ⚠️ 📚
+- Include "trigger phrases" in description: "when implementing...", "when debugging...", "when configuring..."
+- Keep Quick Reference ultra-concise (user sees this first)
+- Link to references explicitly: "See `references/api.md` for complete API"
+
+**Example Description**:
+```yaml
+description: >
+  Building modern React applications with TypeScript, hooks, and routing.
+  Use when implementing React components, managing application state,
+  configuring build tools, or debugging React applications.
+```
+
+### Google Gemini (Actions)
+
+**Official Standard**: [Grounding Best Practices](https://ai.google.dev/gemini-api/docs/google-search)
+
+**Key Differences**:
+- **Grounding**: Skills can leverage Google Search for real-time information
+- **Temperature**: Keep at 1.0 (default) for optimal grounding results
+- **Format**: Supports tar.gz packages (not ZIP)
+- **Limitations**: No Maps grounding in Gemini 3 (use Gemini 2.5 if needed)
+
+**Grounding Enhancements**:
+```markdown
+## When to Use This Skill
+
+Use this skill when:
+- Implementing React components (skill provides patterns)
+- Checking latest React version (grounding provides current info)
+- Debugging common errors (skill + grounding = comprehensive solution)
+```
+
+**Note**: Grounding costs $14 per 1,000 queries (as of Jan 5, 2026).
+
+### OpenAI (GPT Actions)
+
+**Official Standard**: [Key Guidelines for Custom GPTs](https://help.openai.com/en/articles/9358033-key-guidelines-for-writing-instructions-for-custom-gpts)
+
+**Key Differences**:
+- **Multi-step instructions**: Break into simple, atomic steps
+- **Trigger/Instruction pairs**: Use delimiters to separate scenarios
+- **Thoroughness prompts**: Include "take your time", "take a deep breath", "check your work"
+- **Not compatible**: GPT-5.1 reasoning models don't support custom actions yet
+
+**Format**:
+```markdown
+## Instructions
+
+### When user asks about React state management
+
+1. First, identify the state management need (local vs global)
+2. Then, recommend appropriate solution:
+   - Local state → useState or useReducer
+   - Global state → Context API or Redux
+3. Provide code example matching their use case
+4. Finally, explain trade-offs and alternatives
+
+Take your time to understand the user's specific requirements before recommending a solution.
+
+---
+
+### When user asks about React performance
+
+[Similar structured approach]
+```
+
+### Generic Markdown (Platform-Agnostic)
+
+**Use Case**: Documentation sites, internal wikis, non-LLM tools
+
+**Format**: Standard markdown with minimal metadata
+
+**Best Practice**: Focus on human readability over token economy
+
+---
+
+## Knowledge Base Design Patterns
+
+Modern AI skills leverage advanced RAG (Retrieval-Augmented Generation) patterns for optimal knowledge delivery.
+
+### 1. Agentic RAG (Recommended for 2026+)
+
+**Pattern**: Multi-query, context-aware retrieval with agent orchestration
+
+**Architecture**:
+```
+User Query → Agent Plans Retrieval → Multi-Source Fetch →
+Context Synthesis → Response Generation → Self-Verification
+```
+
+**Benefits**:
+- **Adaptive**: Agent adjusts retrieval based on conversation context
+- **Accurate**: Multi-query approach reduces hallucination
+- **Efficient**: Only retrieves what's needed for current query
+
+**Implementation in Skills**:
+```markdown
+references/
+├── index.md              # Navigation hub
+├── api/                  # API references (structured)
+│   ├── components.md
+│   ├── hooks.md
+│   └── utilities.md
+├── patterns/             # Design patterns (by use case)
+│   ├── state-management.md
+│   └── performance.md
+└── examples/             # Code examples (by complexity)
+    ├── basic/
+    ├── intermediate/
+    └── advanced/
+```
+
+**Why**: Agent can navigate structure to find exactly what's needed.
+
+**Sources**:
+- [Traditional RAG vs. Agentic RAG - NVIDIA](https://developer.nvidia.com/blog/traditional-rag-vs-agentic-rag-why-ai-agents-need-dynamic-knowledge-to-get-smarter/)
+- [What is Agentic RAG? - IBM](https://www.ibm.com/think/topics/agentic-rag)
+
+### 2. GraphRAG (Advanced Use Cases)
+
+**Pattern**: Knowledge graph structures for complex reasoning
+
+**Use Case**: Large codebases, interconnected concepts, architectural analysis
+
+**Structure**:
+```markdown
+references/
+├── entities/              # Nodes in knowledge graph
+│   ├── Component.md
+│   ├── Hook.md
+│   └── Context.md
+├── relationships/         # Edges in knowledge graph
+│   ├── Component-uses-Hook.md
+│   └── Context-provides-State.md
+└── graph.json            # Machine-readable graph
+```
+
+**Benefits**: Multi-hop reasoning, relationship exploration, complex queries
+
+**Sources**:
+- [Emerging Patterns in Building GenAI Products - Martin Fowler](https://martinfowler.com/articles/gen-ai-patterns/)
+
+### 3. Multi-Agent Systems (Enterprise Scale)
+
+**Pattern**: Specialized agents for different knowledge domains
+
+**Architecture**:
+```
+Skill Repository
+├── research-agent-skill/      # Explores information space
+├── verification-agent-skill/  # Checks factual claims
+├── synthesis-agent-skill/     # Combines findings
+└── governance-agent-skill/    # Ensures compliance
+```
+
+**Use Case**: Enterprise workflows, compliance requirements, multi-domain expertise
+
+**Sources**:
+- [4 Agentic AI Design Patterns - AIMultiple](https://research.aimultiple.com/agentic-ai-design-patterns/)
+
+### 4. Reflection Pattern (Quality Assurance)
+
+**Pattern**: Self-evaluation and refinement before finalizing responses
+
+**Implementation**:
+```markdown
+## Usage Instructions
+
+When providing code examples:
+1. Generate initial example
+2. Evaluate against these criteria:
+   - Completeness (can user copy-paste and run?)
+   - Best practices (follows framework conventions?)
+   - Security (no vulnerabilities?)
+   - Performance (efficient patterns?)
+3. Refine example based on evaluation
+4. Present final version with explanations
+```
+
+**Benefits**: Higher quality outputs, fewer errors, better adherence to standards
+
+**Sources**:
+- [4 Agentic AI Design Patterns - AIMultiple](https://research.aimultiple.com/agentic-ai-design-patterns/)
+
+### 5. Vector Database Integration
+
+**Pattern**: Semantic search over embeddings for concept-based retrieval
+
+**Use Case**: Large documentation sets, conceptual queries, similarity search
+
+**Structure**:
+- Store reference documents as embeddings
+- User query → embedding → similarity search → top-k retrieval
+- Agent synthesizes retrieved chunks
+
+**Tools**:
+- Pinecone, Weaviate, Chroma, Qdrant
+- Model Context Protocol (MCP) for standardized access
+
+**Sources**:
+- [Anatomy of an AI agent knowledge base - InfoWorld](https://www.infoworld.com/article/4091400/anatomy-of-an-ai-agent-knowledge-base.html)
+
+---
+
+## Quality Grading Rubric
+
+Use this rubric to assess AI skill quality on a **10-point scale**.
+
+### Categories & Weights
+
+| Category | Weight | Description |
+|----------|--------|-------------|
+| **Discovery & Metadata** | 10% | How easily agents find and load the skill |
+| **Conciseness & Token Economy** | 15% | Efficient use of context window |
+| **Structural Organization** | 15% | Logical flow, progressive disclosure |
+| **Code Example Quality** | 20% | Tested, complete, diverse examples |
+| **Accuracy & Correctness** | 20% | Factually correct, up-to-date information |
+| **Actionability** | 10% | User can immediately apply knowledge |
+| **Cross-Platform Compatibility** | 10% | Works across Claude, Gemini, OpenAI |
+
+### Detailed Scoring
+
+#### 1. Discovery & Metadata (10%)
+
+**10/10 - Excellent**:
+- ✅ Name in gerund form, clear and specific
+- ✅ Description: third person, what + when, <1024 chars
+- ✅ Trigger phrases that match user intent
+- ✅ Appropriate tags for discovery
+- ✅ Version and platform metadata present
+
+**7/10 - Good**:
+- ✅ Name clear but not gerund form
+- ✅ Description has what + when but verbose
+- ⚠️ Some trigger phrases missing
+- ✅ Tags present
+
+**4/10 - Poor**:
+- ⚠️ Name vague or passive
+- ⚠️ Description missing "when" clause
+- ⚠️ No trigger phrases
+- ❌ Missing tags
+
+**1/10 - Failing**:
+- ❌ No metadata or incomprehensible name
+- ❌ Description is first person or generic
+
+#### 2. Conciseness & Token Economy (15%)
+
+**10/10 - Excellent**:
+- ✅ Main SKILL.md <5,000 tokens
+- ✅ No redundancy or filler content
+- ✅ Every sentence provides unique value
+- ✅ Progressive disclosure (references on-demand)
+- ✅ Quick Reference <500 tokens
+
+**7/10 - Good**:
+- ✅ Main SKILL.md <7,000 tokens
+- ⚠️ Minor redundancy (5-10% waste)
+- ✅ Most content valuable
+- ⚠️ Some references inline instead of separate
+
+**4/10 - Poor**:
+- ⚠️ Main SKILL.md 7,000-10,000 tokens
+- ⚠️ Significant redundancy (20%+ waste)
+- ⚠️ Verbose explanations, filler words
+- ⚠️ Poor reference organization
+
+**1/10 - Failing**:
+- ❌ Main SKILL.md >10,000 tokens
+- ❌ Massive redundancy, encyclopedic content
+- ❌ No progressive disclosure
+
+#### 3. Structural Organization (15%)
+
+**10/10 - Excellent**:
+- ✅ Clear hierarchy: Quick Ref → Core → Extended → References
+- ✅ Logical flow (discovery → usage → deep dive)
+- ✅ Emojis for scannability
+- ✅ Proper use of headings (##, ###)
+- ✅ Table of contents for long documents
+
+**7/10 - Good**:
+- ✅ Most sections present
+- ⚠️ Flow could be improved
+- ✅ Headings used correctly
+- ⚠️ No emojis or TOC
+
+**4/10 - Poor**:
+- ⚠️ Missing key sections
+- ⚠️ Illogical flow (advanced before basic)
+- ⚠️ Inconsistent heading levels
+- ❌ Wall of text, no structure
+
+**1/10 - Failing**:
+- ❌ No structure, single massive block
+- ❌ Missing required sections
+
+#### 4. Code Example Quality (20%)
+
+**10/10 - Excellent**:
+- ✅ 5-10 examples covering 80% of use cases
+- ✅ All examples tested/validated
+- ✅ Complete (copy-paste ready)
+- ✅ Progressive complexity (basic → advanced)
+- ✅ Annotated with brief explanations
+- ✅ Correct language detection
+- ✅ Real-world patterns (not toy examples)
+
+**7/10 - Good**:
+- ✅ 3-5 examples
+- ✅ Most tested
+- ⚠️ Some incomplete (require modification)
+- ✅ Some progression
+- ⚠️ Light annotations
+
+**4/10 - Poor**:
+- ⚠️ 1-2 examples only
+- ⚠️ Untested or broken examples
+- ⚠️ Fragments, not complete
+- ⚠️ All same complexity level
+- ❌ No annotations
+
+**1/10 - Failing**:
+- ❌ No examples or all broken
+- ❌ Incorrect language tags
+- ❌ Toy examples only
+
+#### 5. Accuracy & Correctness (20%)
+
+**10/10 - Excellent**:
+- ✅ All information factually correct
+- ✅ Current best practices (2026)
+- ✅ No deprecated patterns
+- ✅ Correct API signatures
+- ✅ Accurate version information
+- ✅ No hallucinated features
+
+**7/10 - Good**:
+- ✅ Mostly accurate
+- ⚠️ 1-2 minor errors or outdated details
+- ✅ Core patterns correct
+- ⚠️ Some version ambiguity
+
+**4/10 - Poor**:
+- ⚠️ Multiple factual errors
+- ⚠️ Deprecated patterns presented as current
+- ⚠️ API signatures incorrect
+- ⚠️ Mixing versions
+
+**1/10 - Failing**:
+- ❌ Fundamentally incorrect information
+- ❌ Hallucinated APIs or features
+- ❌ Dangerous or insecure patterns
+
+#### 6. Actionability (10%)
+
+**10/10 - Excellent**:
+- ✅ User can immediately apply knowledge
+- ✅ Step-by-step instructions for complex tasks
+- ✅ Common workflows documented
+- ✅ Troubleshooting guidance
+- ✅ Links to deeper resources when needed
+
+**7/10 - Good**:
+- ✅ Most tasks actionable
+- ⚠️ Some workflows missing steps
+- ✅ Basic troubleshooting present
+- ⚠️ Some dead-end references
+
+**4/10 - Poor**:
+- ⚠️ Theoretical knowledge, unclear application
+- ⚠️ Missing critical steps
+- ❌ No troubleshooting
+- ⚠️ Broken links
+
+**1/10 - Failing**:
+- ❌ Pure reference, no guidance
+- ❌ Cannot use information without external help
+
+#### 7. Cross-Platform Compatibility (10%)
+
+**10/10 - Excellent**:
+- ✅ Follows Open Agent Skills standard
+- ✅ Works on Claude, Gemini, OpenAI, Markdown
+- ✅ No platform-specific dependencies
+- ✅ Proper file structure
+- ✅ Valid YAML frontmatter
+
+**7/10 - Good**:
+- ✅ Works on 2-3 platforms
+- ⚠️ Minor platform-specific tweaks needed
+- ✅ Standard structure
+
+**4/10 - Poor**:
+- ⚠️ Only works on 1 platform
+- ⚠️ Non-standard structure
+- ⚠️ Invalid YAML
+
+**1/10 - Failing**:
+- ❌ Platform-locked, proprietary format
+- ❌ Cannot be ported
+
+### Overall Grade Calculation
+
+```
+Total Score = (Discovery × 0.10) +
+              (Conciseness × 0.15) +
+              (Structure × 0.15) +
+              (Examples × 0.20) +
+              (Accuracy × 0.20) +
+              (Actionability × 0.10) +
+              (Compatibility × 0.10)
+```
+
+**Grade Mapping**:
+- **9.0-10.0**: A+ (Exceptional, reference quality)
+- **8.0-8.9**: A (Excellent, production-ready)
+- **7.0-7.9**: B (Good, minor improvements needed)
+- **6.0-6.9**: C (Acceptable, significant improvements needed)
+- **5.0-5.9**: D (Poor, major rework required)
+- **0.0-4.9**: F (Failing, not usable)
+
+---
+
+## Common Pitfalls
+
+### 1. Encyclopedic Content
+
+**Problem**: Including everything about a topic instead of focusing on actionable knowledge.
+
+**Example**:
+```markdown
+❌ BAD:
+React was created by Jordan Walke, a software engineer at Facebook,
+in 2011. It was first deployed on Facebook's newsfeed in 2011 and
+later on Instagram in 2012. It was open-sourced at JSConf US in May
+2013. Over the years, React has evolved significantly...
+
+✅ GOOD:
+React is a component-based UI library. Build reusable components,
+manage state with hooks, and efficiently update the DOM.
+```
+
+**Fix**: Focus on **what the user needs to do**, not history or background.
+
+### 2. First-Person Descriptions
+
+**Problem**: Using "I" or "you" in metadata (breaks Claude discovery).
+
+**Example**:
+```yaml
+❌ BAD:
+description: I will help you build React applications with best practices
+
+✅ GOOD:
+description: Building modern React applications with TypeScript, hooks,
+  and routing. Use when implementing components or managing state.
+```
+
+**Fix**: Always use third person in description field.
+
+### 3. Token Waste
+
+**Problem**: Redundant explanations, verbose phrasing, or filler content.
+
+**Example**:
+```markdown
+❌ BAD (85 tokens):
+When you are working on a project and you need to manage state in your
+React application, you have several different options available to you.
+One option is to use the useState hook, which is great for managing
+local component state. Another option is to use useReducer, which is
+better for more complex state logic.
+
+✅ GOOD (28 tokens):
+State management options:
+- Local state → useState (simple values)
+- Complex logic → useReducer (state machines)
+- Global state → Context API or Redux
+```
+
+**Fix**: Use bullet points, remove filler, focus on distinctions.
+
+### 4. Untested Examples
+
+**Problem**: Code examples that don't compile or run.
+
+**Example**:
+```typescript
+❌ BAD:
+function Example() {
+  const [data, setData] = useState();  // No type, no initial value
+  useEffect(() => {
+    fetchData();  // Function doesn't exist
+  });  // Missing dependency array
+  return <div>{data}</div>;  // TypeScript error
+}
+
+✅ GOOD:
+interface User {
+  id: number;
+  name: string;
+}
+
+function Example() {
+  const [data, setData] = useState<User | null>(null);
+
+  useEffect(() => {
+    fetch('/api/user')
+      .then(r => r.json())
+      .then(setData);
+  }, []);  // Empty deps = run once
+
+  return <div>{data?.name ?? 'Loading...'}</div>;
+}
+```
+
+**Fix**: Test all code examples, ensure they compile/run.
+
+### 5. Missing "When to Use"
+
+**Problem**: Description explains what but not when.
+
+**Example**:
+```yaml
+❌ BAD:
+description: Documentation for React hooks and component patterns
+
+✅ GOOD:
+description: Building React applications with hooks and components.
+  Use when implementing UI components, managing state, or optimizing
+  React performance.
+```
+
+**Fix**: Always include "Use when..." or "Use for..." clause.
+
+### 6. Flat Reference Structure
+
+**Problem**: All references in one file or directory, no organization.
+
+**Example**:
+```
+❌ BAD:
+references/
+├── everything.md  (20,000+ tokens)
+
+✅ GOOD:
+references/
+├── index.md
+├── api/
+│   ├── components.md
+│   └── hooks.md
+├── patterns/
+│   ├── state-management.md
+│   └── performance.md
+└── examples/
+    ├── basic/
+    └── advanced/
+```
+
+**Fix**: Organize by category, enable agent navigation.
+
+### 7. Outdated Information
+
+**Problem**: Including deprecated APIs or old best practices.
+
+**Example**:
+```markdown
+❌ BAD (deprecated in React 18):
+Use componentDidMount() and componentWillUnmount() for side effects.
+
+✅ GOOD (current as of 2026):
+Use useEffect() hook for side effects in function components.
+```
+
+**Fix**: Regularly update skills, include version info.
+
+---
+
+## Future-Proofing
+
+### Emerging Standards (2026-2030)
+
+1. **Model Context Protocol (MCP)**: Standardizes how agents access tools and data
+   - Skills will integrate with MCP servers
+   - Expect MCP endpoints in skill metadata
+
+2. **Multi-Modal Skills**: Beyond text (images, audio, video)
+   - Include diagram references, video tutorials
+   - Prepare for vision-capable agents
+
+3. **Skill Composition**: Skills that reference other skills
+   - Modular architecture (React skill imports TypeScript skill)
+   - Dependency management for skills
+
+4. **Real-Time Grounding**: Skills + live data sources
+   - Gemini-style grounding becomes universal
+   - Skills provide context, grounding provides current data
+
+5. **Federated Skill Repositories**: Decentralized skill discovery
+   - GitHub-style skill hosting
+   - Version control, pull requests for skills
+
+### Recommendations
+
+- **Version your skills**: Use semantic versioning (1.0.0, 1.1.0, 2.0.0)
+- **Tag platform compatibility**: Specify which platforms/versions tested
+- **Document dependencies**: If skill references external APIs or tools
+- **Provide migration guides**: When updating major versions
+- **Maintain changelog**: Track what changed and why
+
+---
+
+## References
+
+### Official Documentation
+
+- [Claude Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [OpenAI Custom GPT Guidelines](https://help.openai.com/en/articles/9358033-key-guidelines-for-writing-instructions-for-custom-gpts)
+- [Google Gemini Grounding Best Practices](https://ai.google.dev/gemini-api/docs/google-search)
+
+### Industry Standards
+
+- [Agent Skills: Anthropic's Next Bid to Define AI Standards - The New Stack](https://thenewstack.io/agent-skills-anthropics-next-bid-to-define-ai-standards/)
+- [Claude Skills and CLAUDE.md: a practical 2026 guide for teams](https://www.gend.co/blog/claude-skills-claude-md-guide)
+
+### Design Patterns
+
+- [Emerging Patterns in Building GenAI Products - Martin Fowler](https://martinfowler.com/articles/gen-ai-patterns/)
+- [4 Agentic AI Design Patterns - AIMultiple](https://research.aimultiple.com/agentic-ai-design-patterns/)
+- [Traditional RAG vs. Agentic RAG - NVIDIA](https://developer.nvidia.com/blog/traditional-rag-vs-agentic-rag-why-ai-agents-need-dynamic-knowledge-to-get-smarter/)
+- [What is Agentic RAG? - IBM](https://www.ibm.com/think/topics/agentic-rag)
+
+### Knowledge Base Architecture
+
+- [Anatomy of an AI agent knowledge base - InfoWorld](https://www.infoworld.com/article/4091400/anatomy-of-an-ai-agent-knowledge-base.html)
+- [The Next Frontier of RAG: Enterprise Knowledge Systems 2026-2030 - NStarX](https://nstarxinc.com/blog/the-next-frontier-of-rag-how-enterprise-knowledge-systems-will-evolve-2026-2030/)
+- [RAG Architecture Patterns For Developers](https://customgpt.ai/rag-architecture-patterns/)
+
+### Community Resources
+
+- [awesome-claude-skills - GitHub](https://github.com/travisvn/awesome-claude-skills)
+- [Claude Agent Skills: A First Principles Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/)
+
+---
+
+**Document Maintenance**:
+- Review quarterly for platform updates
+- Update examples with new framework versions
+- Track emerging patterns in AI agent space
+- Incorporate community feedback
+
+**Version History**:
+- 1.0 (2026-01-11): Initial release based on 2026 standards

docs/reference/API_REFERENCE.md

@@ -0,0 +1,898 @@
+# API Reference - Programmatic Usage
+
+**Version:** 3.7.0
+**Last Updated:** 2026-06-11
+**Status:** ✅ Verified against v3.7.0 (every import and signature in this document was checked by importing it)
+
+---
+
+## Overview
+
+Skill Seekers can be used programmatically for integration into other tools, automation scripts, and CI/CD pipelines. This guide covers the Python APIs available for developers who want to embed Skill Seekers functionality into their own applications.
+
+> **Stability note — read this first**
+>
+> The **stable, supported interface of the PyPI package is the `skill-seekers` CLI** (and the MCP server). The Python API documented here is real and importable — it is the same code the CLI runs — but it tracks the implementation: module paths, signatures, and config-dict keys may change between minor releases. **Semver guarantees do not extend to these internals.** If you import these modules, pin an exact version (`skill-seekers==3.7.0`) and re-verify on upgrade.
+
+**Use Cases:**
+- Automated documentation skill generation in CI/CD
+- Batch processing multiple documentation sources
+- Custom skill generation workflows
+- Integration with internal tooling
+- Automated skill updates on documentation changes
+
+Each example below is marked **[offline]** (no network, no AI), **[network]** (fetches remote content), or **[AI]** (calls an LLM API or spawns a local agent).
+
+---
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install skill-seekers
+```
+
+### With Platform Dependencies
+
+```bash
+# Google Gemini support
+pip install skill-seekers[gemini]
+
+# OpenAI ChatGPT support
+pip install skill-seekers[openai]
+
+# All LLM platform support
+pip install skill-seekers[all-llms]
+
+# Everything (all source types + platforms, except video-full)
+pip install skill-seekers[all]
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
+cd Skill_Seekers
+pip install -e ".[all-llms]"
+```
+
+---
+
+## Core APIs
+
+### 1. Skill Conversion API (`get_converter`)
+
+The primary programmatic entry point mirrors the `skill-seekers create` command: a factory returns a `SkillConverter` for any of the 18 source types, and `run()` executes the full extract → build pipeline.
+
+```python
+from skill_seekers.cli.skill_converter import get_converter, CONVERTER_REGISTRY
+
+# get_converter(source_type: str, config: dict[str, Any]) -> SkillConverter
+# SkillConverter.run() -> int   (0 = success, non-zero = failure)
+
+print(sorted(CONVERTER_REGISTRY))
+# ['asciidoc', 'chat', 'config', 'confluence', 'epub', 'github', 'html',
+#  'jupyter', 'local', 'manpage', 'notion', 'openapi', 'pdf', 'pptx',
+#  'rss', 'video', 'web', 'word']
+```
+
+#### Basic Usage — web documentation **[network]**
+
+```python
+from skill_seekers.cli.skill_converter import get_converter
+
+config = {
+    "name": "django",
+    "description": "Use when working with Django web framework",
+    "base_url": "https://docs.djangoproject.com/en/5.0/",
+    "selectors": {"main_content": "article", "title": "h1", "code_blocks": "pre code"},
+    "url_patterns": {"include": ["/en/5.0/"], "exclude": []},
+    "max_pages": 50,
+    "rate_limit": 0.5,
+    "output_dir": "output/django",
+}
+
+converter = get_converter("web", config)
+exit_code = converter.run()          # scrapes, then builds output/django/SKILL.md
+print("ok" if exit_code == 0 else "failed")
+```
+
+#### Template method contract
+
+`run()` is a template method on the `SkillConverter` base class:
+
+1. `extract()` — source-specific extraction (scrape, parse, clone, …)
+2. `build_skill()` — categorize content and write `SKILL.md` + `references/`
+
+`run()` **returns an exit code instead of raising**: exceptions from `extract()`/`build_skill()` are logged and converted to return value `1`. Check the return value, not a `try/except`.
+
+```python
+converter = get_converter("pdf", {"name": "manual", "pdf_path": "manual.pdf"})
+
+# Reuse existing on-disk extracted data (skip extraction, rebuild only):
+converter.skip_scrape = True   # run() checks this attribute
+converter.run()
+```
+
+#### Factory errors **[offline]**
+
+- `ValueError` — unknown source type (message lists supported types)
+- `RuntimeError` — the source type's optional dependency is not installed (message includes the `pip install` hint)
+
+#### Unified config through the factory **[offline construction]**
+
+The `"config"` source type wraps the multi-source `UnifiedScraper` (section 4) behind the same factory. It takes the **factory-shaped dict** — only `config_path` is required:
+
+```python
+from skill_seekers.cli.skill_converter import get_converter
+
+scraper = get_converter("config", {
+    "config_path": "configs/unified/react-unified.json",
+    "output_dir": "output/react-complete",   # optional override
+    "merge_mode": "rule-based",              # optional: 'rule-based' | 'claude-enhanced'
+    "dry_run": True,                         # optional: preview sources, write nothing
+})
+scraper.run()
+```
+
+---
+
+### 2. Source Detection API
+
+`SourceDetector` is what `skill-seekers create` uses to auto-detect the source type from a raw input string. It returns a `SourceInfo` dataclass.
+
+#### Basic Usage **[offline]**
+
+```python
+from skill_seekers.cli.source_detector import SourceDetector
+
+detector = SourceDetector()
+
+# detect(source: str) -> SourceInfo
+info = detector.detect("https://docs.djangoproject.com/")
+print(info.type)            # 'web'
+print(info.parsed)          # {'url': 'https://docs.djangoproject.com/'}
+print(info.suggested_name)  # 'djangoproject'
+print(info.raw_input)       # original input string
+
+detector.detect("fastapi/fastapi").type   # 'github'  -> parsed: {'repo': 'fastapi/fastapi'}
+detector.detect("./manual.pdf").type      # 'pdf'     -> parsed: {'file_path': './manual.pdf'}
+detector.detect("./my-project").type      # 'local'   -> parsed: {'directory': '/abs/path/my-project'}
+detector.detect("configs/react.json").type  # 'config' -> parsed: {'config_path': 'configs/react.json'}
+```
+
+`SourceInfo` fields: `type`, `parsed` (dict, shape depends on `type`), `suggested_name`, `raw_input`.
+
+Note: local-directory detection requires the path to exist on disk — a non-existent `./name` falls through to other detectors (e.g. `owner/repo` GitHub shorthand).
+
+#### Detect-then-convert pipeline **[network for web/github]**
+
+```python
+from skill_seekers.cli.source_detector import SourceDetector
+from skill_seekers.cli.skill_converter import get_converter
+
+info = SourceDetector().detect("./manual.pdf")
+
+config = {
+    "name": info.suggested_name,
+    "pdf_path": info.parsed["file_path"],
+    "output_dir": f"output/{info.suggested_name}",
+}
+get_converter(info.type, config).run()
+```
+
+(The CLI's `create_command.py:_build_config()` is the canonical mapping from `SourceInfo.parsed` to each converter's config keys.)
+
+---
+
+### 3. Direct Converter Construction
+
+Every converter class can be constructed directly with a config dict (the factory does nothing more than registry lookup + optional-dependency check). The config keys below are read by each converter's `__init__` and are verified against v3.7.0.
+
+#### PDF — `PDFToSkillConverter` **[offline — local file processing]**
+
+```python
+from skill_seekers.cli.pdf_scraper import PDFToSkillConverter
+
+converter = PDFToSkillConverter({
+    "name": "product-manual",                  # required
+    "pdf_path": "manual.pdf",                  # path to the PDF
+    "description": "Product manual reference", # optional
+    "output_dir": "output/product-manual",     # optional (default: output/<name>)
+    "extract_options": {                       # optional
+        "chunk_size": 10,         # pages per chunk
+        "min_quality": 5.0,       # quality threshold for extracted text
+        "extract_images": True,
+        "min_image_size": 100,
+    },
+    "categories": {},                          # optional keyword mapping
+})
+converter.run()
+```
+
+#### Web — `DocToSkillConverter` **[network]**
+
+```python
+from skill_seekers.cli.doc_scraper import DocToSkillConverter
+
+converter = DocToSkillConverter({
+    "name": "react",                                  # required
+    "base_url": "https://react.dev/",                 # required
+    "selectors": {"main_content": "article", "title": "h1", "code_blocks": "pre code"},
+    "url_patterns": {"include": ["/learn", "/reference"], "exclude": ["/blog"]},
+    "categories": {},          # optional; smart categorization fills the gap
+    "rate_limit": 0.5,         # seconds between requests
+    "max_pages": 200,          # -1 = unlimited
+    "start_urls": [],          # optional explicit seed URLs
+    "llms_txt_url": None,      # optional llms.txt source
+    "browser": False,          # Playwright rendering for JS-heavy sites
+    "workers": 1,              # parallel scrape workers
+    "async_mode": False,       # asyncio scraping (faster on large sites)
+    "doc_version": "",         # stamped into SKILL.md metadata
+    "output_dir": "output/react",
+})
+converter.run()
+```
+
+Constructor also accepts `dry_run=True` / `resume=True` keyword arguments (or the same keys in the config dict).
+
+#### GitHub — `GitHubScraper` **[network — GitHub API; set `GITHUB_TOKEN` for higher rate limits]**
+
+```python
+from skill_seekers.cli.github_scraper import GitHubScraper
+
+converter = GitHubScraper({
+    "repo": "fastapi/fastapi",        # required, owner/repo
+    "name": "fastapi",                # optional (default: repo short name)
+    "local_repo_path": None,          # optional local clone => unlimited analysis, no API limits
+    "include_code": True,
+    "include_issues": True,
+    "max_issues": 100,
+    "max_comments": 0,
+    "issue_labels": [],               # filter issues by label
+    "issue_state": "all",             # 'open' | 'closed' | 'all'
+    "include_changelog": True,
+    "include_releases": True,
+    "output_dir": "output/fastapi",
+})
+converter.run()
+```
+
+The remaining 15 converters follow the same pattern; see `CONVERTER_REGISTRY` in `src/skill_seekers/cli/skill_converter.py` for the module/class of each, and each class's `__init__` for its config keys (e.g. `word` reads `docx_path`, `local` reads `directory` + the C3.x `detect_patterns`/`extract_test_examples`/… toggles).
+
+---
+
+### 4. Unified Multi-Source Scraping API
+
+`UnifiedScraper` combines multiple sources (any of the 18 supported types) into a single merged skill. It is itself a `SkillConverter` (registered as source type `"config"`).
+
+#### Construction forms
+
+```python
+from skill_seekers.cli.unified_scraper import UnifiedScraper
+
+# 1. Path to a unified config JSON file
+scraper = UnifiedScraper("configs/unified/react-unified.json")
+
+# 2. Already-loaded unified config dict (name + description required)
+scraper = UnifiedScraper({"name": "react-complete", "description": "...", "sources": [...]})
+
+# 3. Factory-shaped dict (what get_converter("config", ...) passes through)
+scraper = UnifiedScraper({"config_path": "configs/unified/react-unified.json"})
+
+# Keyword overrides (win over the config file's values)
+scraper = UnifiedScraper(
+    "configs/unified/react-unified.json",
+    merge_mode="rule-based",        # or 'claude-enhanced' (AI merge)
+    output_dir="output/react-complete",
+    dry_run=False,
+)
+```
+
+#### Running **[network — scrapes each source; AI if merge_mode='claude-enhanced']**
+
+```python
+scraper = UnifiedScraper("configs/unified/react-unified.json")
+scraper.run()    # scrape all sources -> merge -> detect conflicts -> build skill
+```
+
+#### Dry run preview **[offline]**
+
+```python
+UnifiedScraper("configs/unified/react-unified.json", dry_run=True).run()
+# Logs the sources that WOULD be scraped and the output directory; writes nothing.
+```
+
+#### Conflict detection
+
+Conflict detection is a **method on the instance**, not a module-level function. It is called automatically by `run()` after merging; you can also drive the phases manually:
+
+```python
+scraper = UnifiedScraper("configs/unified/react-unified.json")
+scraper.scrape_all_sources()              # [network]
+merged = scraper.merge_sources()
+conflicts = scraper.detect_conflicts()    # -> list of conflict records
+scraper.build_skill(merged)
+```
+
+---
+
+### 5. Skill Packaging API
+
+Package skills for different platforms using the adaptor architecture (Strategy + Factory).
+
+#### Basic Packaging **[offline]**
+
+```python
+from pathlib import Path
+from skill_seekers.cli.adaptors import get_adaptor, ADAPTORS
+
+# get_adaptor(platform: str, config: dict = None) -> SkillAdaptor
+print(sorted(ADAPTORS))
+# ['atlas', 'chroma', 'claude', 'deepseek', 'faiss', 'fireworks', 'gemini',
+#  'haystack', 'ibm-bob', 'kimi', 'langchain', 'llama-index', 'markdown',
+#  'minimax', 'openai', 'opencode', 'openrouter', 'pinecone', 'qdrant',
+#  'qwen', 'together', 'weaviate']
+
+adaptor = get_adaptor("claude")
+
+# package(skill_dir: Path, output_path: Path, ...) -> Path
+package_path = adaptor.package(Path("output/react"), Path("output"))
+print(package_path)   # output/react.zip
+```
+
+`get_adaptor` raises `ValueError` for an unknown platform, and `ImportError` if the platform's optional dependency is missing (with an install hint).
+
+#### Packaging with chunking (RAG/vector targets) **[offline]**
+
+```python
+package_path = adaptor.package(
+    Path("output/react"),
+    Path("output"),
+    enable_chunking=True,        # split content into token-bounded chunks
+    chunk_max_tokens=512,
+    preserve_code_blocks=True,   # never split inside a code fence
+    chunk_overlap_tokens=50,
+)
+```
+
+#### Multi-Platform Packaging **[offline]**
+
+```python
+from pathlib import Path
+from skill_seekers.cli.adaptors import get_adaptor
+
+for platform in ["claude", "gemini", "openai", "markdown"]:
+    adaptor = get_adaptor(platform)
+    pkg = adaptor.package(Path("output/react"), Path("output"))
+    print(f"{platform}: {pkg}")
+```
+
+#### Formatting and capability checks **[offline]**
+
+```python
+from pathlib import Path
+from skill_seekers.cli.adaptors import get_adaptor
+from skill_seekers.cli.adaptors.base import SkillAdaptor, SkillMetadata
+
+adaptor = get_adaptor("claude")
+
+adaptor.PLATFORM               # 'claude'
+adaptor.supports_upload()      # True
+adaptor.supports_enhancement() # True
+adaptor.get_env_var_name()     # 'ANTHROPIC_API_KEY'
+
+# format_skill_md(skill_dir: Path, metadata: SkillMetadata) -> str
+meta = SkillMetadata(name="my-skill", description="When to use this skill")
+text = adaptor.format_skill_md(Path("output/my-skill"), meta)
+```
+
+`SkillMetadata` fields: `name`, `description`, `version` (default `"1.0.0"`), `doc_version`, `author`, `tags`.
+
+#### Shared Embedding Methods
+
+The base `SkillAdaptor` class provides two shared embedding helpers inherited by all vector database adaptors (chroma, weaviate, pinecone, qdrant, faiss):
+
+- `_generate_openai_embeddings(texts, model)` — generate embeddings via the OpenAI API. **[network]**
+- `_generate_st_embeddings(texts, model)` — generate embeddings using a local sentence-transformers model. **[offline]**
+
+These are underscore-prefixed (internal) but shared deliberately, so vector adaptors do not re-implement embedding logic.
+
+---
+
+### 6. Skill Upload API
+
+Upload packaged skills to LLM platforms via their APIs. Signature on the base class:
+
+```python
+# upload(package_path: Path, api_key: str, **kwargs) -> dict[str, Any]
+```
+
+The returned dict's keys are **platform-specific** — inspect the concrete adaptor's `upload()` (e.g. `src/skill_seekers/cli/adaptors/claude.py`) for the exact shape. Check `adaptor.supports_upload()` first: adaptors that don't support upload (e.g. `markdown`) return a result dict with `"success": False` and an explanatory `"message"` instead of uploading.
+
+#### Claude AI Upload **[network — Anthropic API]**
+
+```python
+import os
+from pathlib import Path
+from skill_seekers.cli.adaptors import get_adaptor
+
+adaptor = get_adaptor("claude")
+result = adaptor.upload(
+    Path("output/react.zip"),
+    api_key=os.environ["ANTHROPIC_API_KEY"],
+)
+```
+
+#### Google Gemini Upload **[network — requires `pip install skill-seekers[gemini]`]**
+
+```python
+adaptor = get_adaptor("gemini")
+result = adaptor.upload(Path("output/react.tar.gz"), api_key=os.environ["GOOGLE_API_KEY"])
+```
+
+#### OpenAI Upload **[network — requires `pip install skill-seekers[openai]`]**
+
+```python
+adaptor = get_adaptor("openai")
+result = adaptor.upload(Path("output/react-openai.zip"), api_key=os.environ["OPENAI_API_KEY"])
+```
+
+Use `adaptor.get_env_var_name()` to discover which environment variable a platform conventionally reads, and `adaptor.validate_api_key(key)` for a cheap format check before uploading.
+
+---
+
+### 7. AI Enhancement API
+
+Enhance skills with AI-powered improvements. All API-mode enhancement routes
+through the shared `AgentClient` (`skill_seekers.cli.agent_client`), which
+centralizes provider selection (Anthropic/Gemini/OpenAI/Moonshot), model and
+base-URL overrides, the truncation gate, timeout policy, and atomic
+backup-then-save of SKILL.md.
+
+#### API Mode Enhancement (per-platform adaptor) **[AI — provider API call]**
+
+```python
+import os
+from pathlib import Path
+from skill_seekers.cli.adaptors import get_adaptor
+
+adaptor = get_adaptor('claude')  # also: gemini, openai, and OpenAI-compatible targets
+
+# Enhance SKILL.md via the platform's API (returns True on success).
+# The original is backed up to SKILL.md.backup and the save is atomic.
+ok = adaptor.enhance(
+    Path('output/react/'),
+    os.getenv('ANTHROPIC_API_KEY'),
+)
+```
+
+#### Direct AgentClient usage **[AI]**
+
+```python
+from skill_seekers.cli.agent_client import AgentClient
+
+client = AgentClient(mode='api')          # or mode='local' (spawns a local agent)
+reply = client.call('Summarize this skill...', timeout=600)
+```
+
+`AgentClient(mode='auto'|'api'|'local', agent=None, api_key=None, provider=None, base_url=None, model=None)`; `call(prompt, max_tokens=4096, timeout=None, output_file=None, cwd=None, system=None, temperature=None) -> str | None`. Also: `is_available()`, `get_model()`, `detect_api_key()`.
+
+#### LOCAL Mode Enhancement (local coding agent, free) **[AI — spawns local agent]**
+
+```python
+from skill_seekers.cli.enhance_skill_local import LocalSkillEnhancer
+
+enhancer = LocalSkillEnhancer(
+    'output/react/',
+    agent='claude',        # claude, codex, copilot, opencode, kimi, custom
+)
+enhancer.run(background=True)   # or headless=True (default), daemon=True
+```
+
+Monitor background runs from the CLI:
+
+```bash
+skill-seekers enhance-status output/react/ --watch
+```
+
+> LOCAL mode sets `SKILL_SEEKER_ENHANCE_ACTIVE=1` in the spawned agent's
+> environment and refuses to start when it is already set, preventing
+> recursive agent spawns.
+
+---
+
+### 8. Execution Context
+
+`ExecutionContext` is the centralized, pydantic-validated settings singleton the CLI builds from argparse + config files. Converters and enhancement read from it; programmatic callers can initialize and override it.
+
+```python
+from skill_seekers.cli.execution_context import ExecutionContext
+
+# Classmethods:
+#   initialize(args=None, config_path=None, source_info=None) -> ExecutionContext
+#   get() -> ExecutionContext          (active override, else base singleton)
+#   is_initialized() -> bool
+#   reset() -> None                    (mainly for tests)
+
+ExecutionContext.is_initialized()   # False until initialize() is called
+ctx = ExecutionContext.initialize() # defaults when args is None
+
+ctx.enhancement.level    # 2
+ctx.scraping.max_pages   # -1 (unlimited)
+ctx.output.output_dir    # None
+ctx.analysis.depth       # 'surface'
+```
+
+#### Temporary overrides (context manager) **[offline]**
+
+`override(**kwargs)` is a context manager; double-underscore keys address nested settings groups (`source`, `enhancement`, `output`, `scraping`, `analysis`). Overrides are **context-local** (stored in a `contextvars.ContextVar`), so concurrent asyncio tasks each see only their own override, and nested overrides stack and unwind cleanly:
+
+```python
+ctx = ExecutionContext.get()
+
+with ctx.override(enhancement__level=3, scraping__max_pages=100):
+    active = ExecutionContext.get()
+    assert active.enhancement.level == 3      # inside: overridden
+
+assert ExecutionContext.get().enhancement.level == 2  # outside: restored
+```
+
+Caveat: contextvars flow into asyncio tasks automatically but into worker threads only via `contextvars.copy_context().run(...)` — a bare `threading.Thread` sees the base singleton, not your override.
+
+---
+
+### 9. Services Layer (`skill_seekers.services`)
+
+Domain logic shared by the CLI and the MCP server. Importable **without** the `[mcp]` extra. Import from the submodules:
+
+```python
+from skill_seekers.services.marketplace_manager import MarketplaceManager
+from skill_seekers.services.source_manager import SourceManager
+from skill_seekers.services.config_publisher import ConfigPublisher, detect_category
+from skill_seekers.services.git_repo import GitConfigRepo
+```
+
+#### Marketplace registry CRUD **[offline — local registry file]**
+
+```python
+mm = MarketplaceManager()        # or MarketplaceManager(config_dir="~/.skill-seekers")
+mm.list_marketplaces()           # -> list[dict]; also: add/get/update/remove_marketplace
+```
+
+#### Config source registry CRUD **[offline]**
+
+```python
+sm = SourceManager()
+sm.list_sources()                # also: add/get/update/remove_source
+```
+
+#### Config category detection **[offline]**
+
+```python
+detect_category({"name": "react", "description": "React frontend UI library docs"})
+# 'web-frameworks'   (keyword scoring over CATEGORY_KEYWORDS)
+```
+
+#### Git-backed config repositories **[network — clones/pulls]**
+
+```python
+repo = GitConfigRepo()                       # or GitConfigRepo(cache_dir=...)
+repo.validate_git_url("https://github.com/owner/configs.git")   # offline check
+path = repo.clone_or_pull("https://github.com/owner/configs.git")  # [network]
+configs = repo.find_configs(path)
+```
+
+`ConfigPublisher` (`ConfigPublisher(cache_dir=None)`) pushes configs to registered config-source repos; `MarketplacePublisher` publishes packaged skills to plugin-marketplace repos. Both perform git pushes **[network]**.
+
+---
+
+## Configuration Objects
+
+The full config-file schema (single-source and unified) is documented in **[CONFIG_FORMAT.md](CONFIG_FORMAT.md)** — that is the authoritative reference. Summary:
+
+### Web (single-source) config keys
+
+These are the keys `DocToSkillConverter` reads (same dict whether loaded from a `configs/*.json` file or built in code):
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | string | *required* | Skill name (alphanumeric + hyphens) |
+| `base_url` | string | *required* | Documentation website URL |
+| `description` | string | generated | When to use this skill |
+| `selectors` | object | `{}` | CSS selectors (`main_content`, `title`, `code_blocks`) |
+| `url_patterns` | object | `{}` | `include` / `exclude` URL substring lists |
+| `categories` | object | `{}` | Category keywords mapping |
+| `rate_limit` | float | `0.5` | Delay between requests (seconds) |
+| `max_pages` | int | `-1` | Maximum pages to scrape (-1 = unlimited) |
+| `start_urls` | array | `[]` | Explicit seed URLs |
+| `llms_txt_url` | string | `null` | URL to llms.txt file |
+| `async_mode` | bool | `false` | Asyncio scraping (faster on large sites) |
+| `browser` | bool | `false` | Playwright rendering for JS-heavy sites |
+| `workers` | int | `1` | Parallel scrape workers |
+| `output_dir` | string | `output/<name>` | Where the skill is written |
+
+### Unified Config Schema (Multi-Source)
+
+Supports all 18 source types: `documentation`, `github`, `pdf`, `local`, `word`, `video`, `epub`, `jupyter`, `html`, `openapi`, `asciidoc`, `pptx`, `rss`, `manpage`, `confluence`, `notion`, `chat`, `config`.
+
+```json
+{
+  "name": "framework-unified",
+  "description": "Complete framework documentation",
+  "merge_mode": "rule-based",
+  "sources": [
+    {
+      "type": "documentation",
+      "base_url": "https://docs.example.com/",
+      "selectors": { "main_content": "article" }
+    },
+    {
+      "type": "github",
+      "repo": "org/repo",
+      "include_code": true
+    },
+    {
+      "type": "pdf",
+      "path": "manual.pdf"
+    },
+    {
+      "type": "openapi",
+      "path": "specs/openapi.yaml"
+    },
+    {
+      "type": "video",
+      "url": "https://www.youtube.com/watch?v=example"
+    },
+    {
+      "type": "jupyter",
+      "path": "notebooks/examples.ipynb"
+    },
+    {
+      "type": "confluence",
+      "base_url": "https://company.atlassian.net/wiki",
+      "space_key": "DOCS"
+    }
+  ]
+}
+```
+
+Configs are validated on load by `skill_seekers.cli.config_validator.validate_config(config_path)`, which the CLI and `UnifiedScraper` call for you.
+
+---
+
+## Error Handling
+
+The Python API signals failure three different ways — match on the layer you call:
+
+```python
+from pathlib import Path
+from skill_seekers.cli.skill_converter import get_converter
+from skill_seekers.cli.adaptors import get_adaptor
+
+# 1. Factory-time errors RAISE:
+try:
+    converter = get_converter("web", config)
+except ValueError as e:      # unknown source type
+    print(e)
+except RuntimeError as e:    # missing optional dependency (includes pip install hint)
+    print(e)
+
+try:
+    adaptor = get_adaptor("chroma")
+except ValueError as e:      # unknown platform
+    print(e)
+except ImportError as e:     # optional dependency not installed
+    print(e)
+
+# 2. Conversion errors are RETURN CODES (run() catches and logs exceptions):
+if converter.run() != 0:
+    raise SystemExit("skill build failed — see log output")
+
+# 3. Adaptor operations either RAISE (network/API errors during real uploads)
+#    or report failure in the returned dict — gate on capability and check
+#    result["success"]:
+if adaptor.supports_upload():
+    result = adaptor.upload(Path("output/react.zip"), api_key=key)
+    if not result.get("success"):
+        print(result.get("message"))
+```
+
+There is no `skill_seekers.exceptions` module — standard exceptions (`ValueError`, `RuntimeError`, `ImportError`, `FileNotFoundError`) are used throughout.
+
+---
+
+## Testing Your Integration
+
+Use `dry_run` and small `max_pages` limits to keep tests fast and offline-friendly:
+
+```python
+from skill_seekers.cli.skill_converter import get_converter
+from skill_seekers.cli.source_detector import SourceDetector
+
+
+def test_source_detection():            # [offline]
+    info = SourceDetector().detect("https://docs.example.com/")
+    assert info.type == "web"
+    assert info.parsed["url"] == "https://docs.example.com/"
+
+
+def test_unified_dry_run(tmp_path):     # [offline] — previews without scraping
+    import json
+    cfg = tmp_path / "unified.json"
+    cfg.write_text(json.dumps({
+        "name": "test",
+        "description": "Test skill",   # name + description are required
+        "sources": [{"type": "github", "repo": "owner/repo"}],
+    }))
+    scraper = get_converter("config", {"config_path": str(cfg), "dry_run": True})
+    assert scraper.run() == 0
+
+
+def test_packaging(tmp_path):           # [offline]
+    from pathlib import Path
+    from skill_seekers.cli.adaptors import get_adaptor
+
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: t\ndescription: d\n---\n# T\n")
+    pkg = get_adaptor("markdown").package(skill, tmp_path)
+    assert pkg.exists()
+```
+
+---
+
+## Performance Notes
+
+- **Async scraping**: set `"async_mode": True` in a web config for 2–3x faster scraping on large sites; `"workers": N` parallelizes the thread-based scraper.
+- **Rebuild without re-scraping**: set `converter.skip_scrape = True` before `run()` to rebuild `SKILL.md` from existing on-disk extracted data (`output/<name>_data/`).
+- **Resume**: web configs support checkpointing — pass `resume=True` to `DocToSkillConverter` (or `"resume": True` in the config) to continue an interrupted scrape.
+- **Batch processing**: converters are independent; run several `get_converter(...).run()` calls in a `ThreadPoolExecutor`. Don't share one `ExecutionContext.override()` across plain threads (see section 8 caveat).
+
+---
+
+## CI/CD Integration Examples
+
+For pipelines, prefer the CLI — it is the stable interface:
+
+### GitHub Actions
+
+```yaml
+name: Generate Skills
+
+on:
+  schedule:
+    - cron: '0 0 * * *'  # Daily at midnight
+  workflow_dispatch:
+
+jobs:
+  generate-skills:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install Skill Seekers
+        run: pip install skill-seekers[all-llms]
+
+      - name: Generate Skills
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+        run: |
+          skill-seekers install --config react --target claude
+          skill-seekers install --config vue --target gemini
+
+      - name: Archive Skills
+        uses: actions/upload-artifact@v3
+        with:
+          name: skills
+          path: output/**/*.zip
+```
+
+### GitLab CI
+
+```yaml
+generate_skills:
+  image: python:3.11
+  script:
+    - pip install skill-seekers[all-llms]
+    - skill-seekers install --config react --target claude
+    - skill-seekers install --config vue --target gemini --no-upload
+  artifacts:
+    paths:
+      - output/
+  only:
+    - schedules
+```
+
+---
+
+## Best Practices
+
+### 1. **Prefer the CLI for automation; pin the version for Python imports**
+```bash
+pip install skill-seekers==3.7.0   # internals can shift between minors
+```
+
+### 2. **Use the factory, not hardcoded classes**
+```python
+# Good: registry-driven
+converter = get_converter(info.type, config)
+adaptor = get_adaptor(target_platform)
+
+# Brittle: hardcoded imports break when modules move
+```
+
+### 3. **Check run() return codes**
+```python
+if get_converter("web", config).run() != 0:
+    raise SystemExit(1)   # run() logs the exception; it does not re-raise
+```
+
+### 4. **Cache scraped data, rebuild cheaply**
+```python
+converter = get_converter("web", config)
+converter.run()                 # first run: scrape + build (slow)
+
+converter = get_converter("web", config)
+converter.skip_scrape = True
+converter.run()                 # rebuild from output/<name>_data/ (fast)
+```
+
+### 5. **Probe adaptor capabilities before calling**
+```python
+adaptor = get_adaptor(platform)
+if adaptor.supports_upload():
+    adaptor.upload(pkg, api_key=os.environ[adaptor.get_env_var_name()])
+```
+
+### 6. **Use dry runs in tests**
+```python
+get_converter("config", {"config_path": cfg, "dry_run": True}).run()
+```
+
+---
+
+## API Reference Summary
+
+| API | Import | Use Case |
+|-----|--------|----------|
+| **Skill conversion factory** | `skill_seekers.cli.skill_converter.get_converter` | Any of the 18 source types → skill |
+| **Converter registry** | `skill_seekers.cli.skill_converter.CONVERTER_REGISTRY` | Source type → (module, class) lookup |
+| **Source detection** | `skill_seekers.cli.source_detector.SourceDetector` | Auto-detect type from raw input |
+| **Web docs** | `skill_seekers.cli.doc_scraper.DocToSkillConverter` | Documentation websites |
+| **GitHub repos** | `skill_seekers.cli.github_scraper.GitHubScraper` | Code + docs + community analysis |
+| **PDF** | `skill_seekers.cli.pdf_scraper.PDFToSkillConverter` | PDF documents |
+| **Local codebase** | `skill_seekers.cli.codebase_scraper.CodebaseAnalyzer` | Local directories (C3.x pipeline) |
+| **Multi-source** | `skill_seekers.cli.unified_scraper.UnifiedScraper` | Merge 18 source types + conflict detection |
+| **Packaging / upload / enhance** | `skill_seekers.cli.adaptors.get_adaptor` | 22 platform targets |
+| **AI enhancement** | `skill_seekers.cli.agent_client.AgentClient` | API or local-agent LLM calls |
+| **Local-agent enhancement** | `skill_seekers.cli.enhance_skill_local.LocalSkillEnhancer` | Free enhancement via coding agents |
+| **Settings singleton** | `skill_seekers.cli.execution_context.ExecutionContext` | Initialize / get / override settings |
+| **Marketplace registry** | `skill_seekers.services.marketplace_manager.MarketplaceManager` | Marketplace CRUD |
+| **Config sources** | `skill_seekers.services.source_manager.SourceManager` | Config source registry CRUD |
+| **Config publishing** | `skill_seekers.services.config_publisher` | Push configs; `detect_category()` |
+| **Git config repos** | `skill_seekers.services.git_repo.GitConfigRepo` | Clone/pull + config discovery |
+
+The other 14 converter classes (word, epub, video, jupyter, html, openapi, asciidoc, pptx, rss, manpage, confluence, notion, chat) are listed in `CONVERTER_REGISTRY`.
+
+---
+
+## Additional Resources
+
+- **[Main Documentation](../../README.md)** - Complete user guide
+- **[CLI Reference](CLI_REFERENCE.md)** - The stable command-line interface
+- **[Config Format](CONFIG_FORMAT.md)** - Authoritative config schema
+- **[MCP Setup](../guides/MCP_SETUP.md)** - MCP server integration
+- **[Multi-LLM Support](../integrations/MULTI_LLM_SUPPORT.md)** - Platform comparison
+- **[CHANGELOG](../../CHANGELOG.md)** - Version history and API changes
+
+---
+
+**Version:** 3.7.0
+**Last Updated:** 2026-06-11

docs/reference/CLAUDE_INTEGRATION.md

@@ -0,0 +1,535 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 🎯 Current Status (January 8, 2026)
+
+**Version:** v3.6.0
+**Status:** Production Ready
+
+### Recent Updates (January 2026):
+
+**🚀 MAJOR RELEASE: Three-Stream GitHub Architecture (v2.6.0)**
+- **✅ Phases 1-5 Complete** (26 hours implementation, 81 tests passing)
+- **NEW: GitHub Three-Stream Fetcher** - Split repos into Code, Docs, Insights streams
+- **NEW: Unified Codebase Analyzer** - Works with GitHub URLs + local paths, C3.x as analysis depth
+- **ENHANCED: Source Merging** - Multi-layer merge with GitHub docs and insights
+- **ENHANCED: Router Generation** - GitHub metadata, README quick start, common issues
+- **CRITICAL FIX: Actual C3.x Integration** - Real pattern detection (not placeholders)
+- **Quality Metrics**: GitHub overhead 20-60 lines, router size 60-250 lines
+- **Documentation**: Complete implementation summary and E2E tests
+
+### Recent Updates (December 2025):
+
+**🎉 MAJOR RELEASE: Multi-Platform Feature Parity! (v2.5.0)**
+- **🌐 Multi-LLM Support**: Full support for 21 platforms - Claude AI, Google Gemini, OpenAI ChatGPT, MiniMax AI, OpenCode, Kimi, DeepSeek, Qwen, OpenRouter, Together AI, Fireworks AI, IBM Bob, LangChain, LlamaIndex, Haystack, Pinecone, Weaviate, Chroma, FAISS, Qdrant, and Generic Markdown
+- **🔄 Complete Feature Parity**: All skill modes work with all platforms
+- **🏗️ Platform Adaptors**: Clean architecture with platform-specific implementations
+- **✨ 40 MCP Tools**: Enhanced with multi-platform support (package, upload, enhance)
+- **📚 Comprehensive Documentation**: Complete guides for all platforms
+- **🧪 Test Coverage**: 1,880+ tests passing, extensive platform compatibility testing
+
+**🚀 NEW: Three-Stream GitHub Architecture (v2.6.0)**
+- **📊 Three-Stream Fetcher**: Split GitHub repos into Code, Docs, and Insights streams
+- **🔬 Unified Codebase Analyzer**: Works with GitHub URLs and local paths
+- **🎯 Enhanced Router Generation**: GitHub insights + C3.x patterns for better routing
+- **📝 GitHub Issue Integration**: Common problems and solutions in sub-skills
+- **✅ 81 Tests Passing**: Comprehensive E2E validation (0.43 seconds)
+
+## Three-Stream GitHub Architecture
+
+**New in v2.6.0**: GitHub repositories are now analyzed using a three-stream architecture:
+
+**STREAM 1: Code** (for C3.x analysis)
+- Files: `*.py, *.js, *.ts, *.go, *.rs, *.java, etc.`
+- Purpose: Deep code analysis with C3.x components
+- Time: 20-60 minutes
+- Components: Patterns (C3.1), Examples (C3.2), Guides (C3.3), Configs (C3.4), Architecture (C3.7)
+
+**STREAM 2: Documentation** (from repository)
+- Files: `README.md, CONTRIBUTING.md, docs/*.md`
+- Purpose: Quick start guides and official documentation
+- Time: 1-2 minutes
+
+**STREAM 3: GitHub Insights** (metadata & community)
+- Data: Open issues, closed issues, labels, stars, forks
+- Purpose: Real user problems and known solutions
+- Time: 1-2 minutes
+
+### Usage Example
+
+```python
+from skill_seekers.cli.unified_codebase_analyzer import UnifiedCodebaseAnalyzer
+
+# Analyze GitHub repo with three streams
+analyzer = UnifiedCodebaseAnalyzer()
+result = analyzer.analyze(
+    source="https://github.com/facebook/react",
+    depth="c3x",  # or "basic"
+    fetch_github_metadata=True
+)
+
+# Access all three streams
+print(f"Files: {len(result.code_analysis['files'])}")
+print(f"README: {result.github_docs['readme'][:100]}")
+print(f"Stars: {result.github_insights['metadata']['stars']}")
+print(f"C3.x Patterns: {len(result.code_analysis['c3_1_patterns'])}")
+```
+
+### Router Generation with GitHub
+
+```python
+from skill_seekers.cli.generate_router import RouterGenerator
+from skill_seekers.cli.github_fetcher import GitHubThreeStreamFetcher
+
+# Fetch GitHub repo with three streams
+fetcher = GitHubThreeStreamFetcher("https://github.com/jlowin/fastmcp")
+three_streams = fetcher.fetch()
+
+# Generate router with GitHub integration
+generator = RouterGenerator(
+    ['configs/fastmcp-oauth.json', 'configs/fastmcp-async.json'],
+    github_streams=three_streams
+)
+
+# Result includes:
+# - Repository stats (stars, language)
+# - README quick start
+# - Common issues from GitHub
+# - Enhanced routing keywords (GitHub labels with 2x weight)
+skill_md = generator.generate_skill_md()
+```
+
+**See full documentation**: [Three-Stream Implementation Summary](IMPLEMENTATION_SUMMARY_THREE_STREAM.md)
+
+## Overview
+
+This is a Python-based documentation scraper that converts ANY documentation website into a Claude skill. It's a single-file tool (`doc_scraper.py`) that scrapes documentation, extracts code patterns, detects programming languages, and generates structured skill files ready for use with Claude.
+
+## Dependencies
+
+```bash
+pip3 install requests beautifulsoup4
+```
+
+## Core Commands
+
+### Run with a preset configuration
+```bash
+skill-seekers create --config configs/godot.json
+skill-seekers create --config configs/react.json
+skill-seekers create --config configs/vue.json
+skill-seekers create --config configs/django.json
+skill-seekers create --config configs/fastapi.json
+```
+
+### Interactive mode (for new frameworks)
+```bash
+skill-seekers create --interactive
+```
+
+### Quick mode (minimal config)
+```bash
+skill-seekers create --name react --url https://react.dev/ --description "React framework"
+```
+
+### Skip scraping (use cached data)
+```bash
+skill-seekers create --config configs/godot.json --skip-scrape
+```
+
+### Resume interrupted scrapes
+```bash
+# If scrape was interrupted
+skill-seekers create --config configs/godot.json --resume
+
+# Start fresh (clear checkpoint)
+skill-seekers create --config configs/godot.json --fresh
+```
+
+### Large documentation (10K-40K+ pages)
+```bash
+# 1. Estimate page count
+skill-seekers estimate configs/godot.json
+
+# 2. Split into focused sub-skills
+python -m skill_seekers.cli.split_config configs/godot.json --strategy router
+
+# 3. Generate router skill
+skill-seekers create configs/godot-*.json
+
+# 4. Package multiple skills
+skill-seekers package output/godot*/
+```
+
+### AI-powered SKILL.md enhancement
+```bash
+# Option 1: During scraping (API-based when ANTHROPIC_API_KEY is set)
+export ANTHROPIC_API_KEY=sk-ant-...
+skill-seekers create --config configs/react.json --enhance-level 2
+
+# Option 2: During scraping (LOCAL, no API key - uses Claude Code Max)
+skill-seekers create --config configs/react.json --enhance-level 2 --agent claude
+
+# Option 3: Standalone after scraping (API-based)
+skill-seekers enhance output/react/
+
+# Option 4: Standalone after scraping (LOCAL, no API key)
+skill-seekers enhance output/react/
+```
+
+The LOCAL enhancement option (`--enhance-local` or `enhance_skill_local.py`) opens a new terminal with Claude Code, which analyzes reference files and enhances SKILL.md automatically. This requires Claude Code Max plan but no API key.
+
+### MCP Integration (Claude Code)
+```bash
+# One-time setup
+./setup_mcp.sh
+
+# Then in Claude Code, use natural language:
+"List all available configs"
+"Generate config for Tailwind at https://tailwindcss.com/docs"
+"Split configs/godot.json using router strategy"
+"Generate router for configs/godot-*.json"
+"Package skill at output/react/"
+```
+
+40 MCP tools available with multi-platform support: list_configs, generate_config, validate_config, fetch_config, estimate_pages, scrape_docs, scrape_github, scrape_pdf, package_skill, upload_skill, enhance_skill (NEW), install_skill, split_config, generate_router, add_config_source, list_config_sources, remove_config_source, submit_config
+
+### Test with limited pages (edit config first)
+Set `"max_pages": 20` in the config file to test with fewer pages.
+
+## Multi-Platform Support (v2.5.0+)
+
+**4 Platforms Fully Supported:**
+- **Claude AI** (default) - ZIP format, Skills API, MCP integration
+- **Google Gemini** - tar.gz format, Files API, 1M token context
+- **OpenAI ChatGPT** - ZIP format, Assistants API, Vector Store
+- **Generic Markdown** - ZIP format, universal compatibility
+
+**All skill modes work with all platforms:**
+- Documentation scraping
+- GitHub repository analysis
+- PDF extraction
+- Unified multi-source
+- Local repository analysis
+
+**Use the `--target` parameter for packaging, upload, and enhancement:**
+```bash
+# Package for different platforms
+skill-seekers package output/react/ --target claude     # Default
+skill-seekers package output/react/ --target gemini
+skill-seekers package output/react/ --target openai
+skill-seekers package output/react/ --target markdown
+
+# Upload to platforms (requires API keys)
+skill-seekers upload output/react.zip --target claude
+skill-seekers upload output/react-gemini.tar.gz --target gemini
+skill-seekers upload output/react-openai.zip --target openai
+
+# Enhance with platform-specific AI
+skill-seekers enhance output/react/ --target claude     # Sonnet 4
+skill-seekers enhance output/react/ --target gemini     # Gemini 2.0
+skill-seekers enhance output/react/ --target openai     # GPT-4o
+```
+
+See [Multi-Platform Guide](UPLOAD_GUIDE.md) and [Feature Matrix](FEATURE_MATRIX.md) for complete details.
+
+## Architecture
+
+### Single-File Design
+The entire tool is contained in `doc_scraper.py` (~737 lines). It follows a class-based architecture with a single `DocToSkillConverter` class that handles:
+- **Web scraping**: BFS traversal with URL validation
+- **Content extraction**: CSS selectors for title, content, code blocks
+- **Language detection**: Heuristic-based detection from code samples (Python, JavaScript, GDScript, C++, etc.)
+- **Pattern extraction**: Identifies common coding patterns from documentation
+- **Categorization**: Smart categorization using URL structure, page titles, and content keywords with scoring
+- **Skill generation**: Creates SKILL.md with real code examples and categorized reference files
+
+### Data Flow
+1. **Scrape Phase**:
+   - Input: Config JSON (name, base_url, selectors, url_patterns, categories, rate_limit, max_pages)
+   - Process: BFS traversal starting from base_url, respecting include/exclude patterns
+   - Output: `output/{name}_data/pages/*.json` + `summary.json`
+
+2. **Build Phase**:
+   - Input: Scraped JSON data from `output/{name}_data/`
+   - Process: Load pages → Smart categorize → Extract patterns → Generate references
+   - Output: `output/{name}/SKILL.md` + `output/{name}/references/*.md`
+
+### Directory Structure
+```
+Skill_Seekers/
+├── cli/                        # CLI tools
+│   ├── doc_scraper.py         # Main scraping & building tool
+│   ├── enhance_skill.py       # AI enhancement (API-based)
+│   ├── enhance_skill_local.py # AI enhancement (LOCAL, no API)
+│   ├── estimate_pages.py      # Page count estimator
+│   ├── split_config.py        # Large docs splitter (NEW)
+│   ├── generate_router.py     # Router skill generator (NEW)
+│   ├── package_skill.py       # Single skill packager
+│   └── package_multi.py       # Multi-skill packager (NEW)
+├── mcp/                        # MCP server
+│   ├── server.py              # 9 MCP tools (includes upload)
+│   └── README.md
+├── configs/                    # Preset configurations
+│   ├── godot.json
+│   ├── godot-large-example.json  # Large docs example (NEW)
+│   ├── react.json
+│   └── ...
+├── docs/                       # Documentation
+│   ├── CLAUDE.md              # Technical architecture (this file)
+│   ├── LARGE_DOCUMENTATION.md # Large docs guide (NEW)
+│   ├── ENHANCEMENT.md
+│   ├── MCP_SETUP.md
+│   └── ...
+└── output/                     # Generated output (git-ignored)
+    ├── {name}_data/           # Raw scraped data (cached)
+    │   ├── pages/             # Individual page JSONs
+    │   ├── summary.json       # Scraping summary
+    │   └── checkpoint.json    # Resume checkpoint (NEW)
+    └── {name}/                # Generated skill
+        ├── SKILL.md           # Main skill file with examples
+        ├── SKILL.md.backup    # Backup (if enhanced)
+        ├── references/        # Categorized documentation
+        │   ├── index.md
+        │   ├── getting_started.md
+        │   ├── api.md
+        │   └── ...
+        ├── scripts/           # Empty (for user scripts)
+        └── assets/            # Empty (for user assets)
+```
+
+### Configuration Format
+Config files in `configs/*.json` contain:
+- `name`: Skill identifier (e.g., "godot", "react")
+- `description`: When to use this skill
+- `base_url`: Starting URL for scraping
+- `selectors`: CSS selectors for content extraction
+  - `main_content`: Main documentation content (e.g., "article", "div[role='main']")
+  - `title`: Page title selector
+  - `code_blocks`: Code sample selector (e.g., "pre code", "pre")
+- `url_patterns`: URL filtering
+  - `include`: Only scrape URLs containing these patterns
+  - `exclude`: Skip URLs containing these patterns
+- `categories`: Keyword-based categorization mapping
+- `rate_limit`: Delay between requests (seconds)
+- `max_pages`: Maximum pages to scrape
+- `split_strategy`: (Optional) How to split large docs: "auto", "category", "router", "size"
+- `split_config`: (Optional) Split configuration
+  - `target_pages_per_skill`: Pages per sub-skill (default: 5000)
+  - `create_router`: Create router/hub skill (default: true)
+  - `split_by_categories`: Category names to split by
+- `checkpoint`: (Optional) Checkpoint/resume configuration
+  - `enabled`: Enable checkpointing (default: false)
+  - `interval`: Save every N pages (default: 1000)
+
+### Key Features
+
+**Auto-detect existing data**: Tool checks for `output/{name}_data/` and prompts to reuse, avoiding re-scraping.
+
+**Language detection**: Detects code languages from:
+1. CSS class attributes (`language-*`, `lang-*`)
+2. Heuristics (keywords like `def`, `const`, `func`, etc.)
+
+**Pattern extraction**: Looks for "Example:", "Pattern:", "Usage:" markers in content and extracts following code blocks (up to 5 per page).
+
+**Smart categorization**:
+- Scores pages against category keywords (3 points for URL match, 2 for title, 1 for content)
+- Threshold of 2+ for categorization
+- Auto-infers categories from URL segments if none provided
+- Falls back to "other" category
+
+**Enhanced SKILL.md**: Generated with:
+- Real code examples from documentation (language-annotated)
+- Quick reference patterns extracted from docs
+- Common pattern section
+- Category file listings
+
+**AI-Powered Enhancement**: Two scripts to dramatically improve SKILL.md quality:
+- `enhance_skill.py`: Uses Anthropic API (~$0.15-$0.30 per skill, requires API key)
+- `enhance_skill_local.py`: Uses Claude Code Max (free, no API key needed)
+- Transforms generic 75-line templates into comprehensive 500+ line guides
+- Extracts best examples, explains key concepts, adds navigation guidance
+- Success rate: 9/10 quality (based on steam-economy test)
+
+**Large Documentation Support (NEW)**: Handle 10K-40K+ page documentation:
+- `split_config.py`: Split large configs into multiple focused sub-skills
+- `generate_router.py`: Create intelligent router/hub skills that direct queries
+- `package_multi.py`: Package multiple skills at once
+- 4 split strategies: auto, category, router, size
+- Parallel scraping support for faster processing
+- MCP integration for natural language usage
+
+**Checkpoint/Resume (NEW)**: Never lose progress on long scrapes:
+- Auto-saves every N pages (configurable, default: 1000)
+- Resume with `--resume` flag
+- Clear checkpoint with `--fresh` flag
+- Saves on interruption (Ctrl+C)
+
+## Key Code Locations
+
+- **URL validation**: `is_valid_url()` doc_scraper.py:47-62
+- **Content extraction**: `extract_content()` doc_scraper.py:64-131
+- **Language detection**: `detect_language()` doc_scraper.py:133-163
+- **Pattern extraction**: `extract_patterns()` doc_scraper.py:165-181
+- **Smart categorization**: `smart_categorize()` doc_scraper.py:280-321
+- **Category inference**: `infer_categories()` doc_scraper.py:323-349
+- **Quick reference generation**: `generate_quick_reference()` doc_scraper.py:351-370
+- **SKILL.md generation**: `create_enhanced_skill_md()` doc_scraper.py:424-540
+- **Scraping loop**: `scrape_all()` doc_scraper.py:226-249
+- **Main workflow**: `main()` doc_scraper.py:661-733
+
+## Workflow Examples
+
+### First time scraping (with scraping)
+```bash
+# 1. Scrape + Build
+skill-seekers create --config configs/godot.json
+# Time: 20-40 minutes
+
+# 2. Package
+skill-seekers package output/godot/
+
+# Result: godot.zip
+```
+
+### Using cached data (fast iteration)
+```bash
+# 1. Use existing data
+skill-seekers create --config configs/godot.json --skip-scrape
+# Time: 1-3 minutes
+
+# 2. Package
+skill-seekers package output/godot/
+```
+
+### Creating a new framework config
+```bash
+# Option 1: Interactive
+skill-seekers create --interactive
+
+# Option 2: Copy and modify
+cp configs/react.json configs/myframework.json
+# Edit configs/myframework.json
+skill-seekers create --config configs/myframework.json
+```
+
+### Large documentation workflow (40K pages)
+```bash
+# 1. Estimate page count (fast, 1-2 minutes)
+skill-seekers estimate configs/godot.json
+
+# 2. Split into focused sub-skills
+python -m skill_seekers.cli.split_config configs/godot.json --strategy router --target-pages 5000
+
+# Creates: godot-scripting.json, godot-2d.json, godot-3d.json, etc.
+
+# 3. Scrape all in parallel (4-8 hours instead of 20-40!)
+for config in configs/godot-*.json; do
+  skill-seekers create --config $config &
+done
+wait
+
+# 4. Generate intelligent router skill
+skill-seekers create configs/godot-*.json
+
+# 5. Package all skills
+skill-seekers package output/godot*/
+
+# 6. Upload all .zip files to Claude
+# Result: Router automatically directs queries to the right sub-skill!
+```
+
+**Time savings:** Parallel scraping reduces 20-40 hours to 4-8 hours
+
+**See full guide:** [Large Documentation Guide](LARGE_DOCUMENTATION.md)
+
+## Testing Selectors
+
+To find the right CSS selectors for a documentation site:
+
+```python
+from bs4 import BeautifulSoup
+import requests
+
+url = "https://docs.example.com/page"
+soup = BeautifulSoup(requests.get(url).content, 'html.parser')
+
+# Try different selectors
+print(soup.select_one('article'))
+print(soup.select_one('main'))
+print(soup.select_one('div[role="main"]'))
+```
+
+## Running Tests
+
+**IMPORTANT: You must install the package before running tests**
+
+```bash
+# 1. Install package in editable mode (one-time setup)
+pip install -e .
+
+# 2. Run all tests
+pytest
+
+# 3. Run specific test files
+pytest tests/test_config_validation.py
+pytest tests/test_github_scraper.py
+
+# 4. Run with verbose output
+pytest -v
+
+# 5. Run with coverage report
+pytest --cov=src/skill_seekers --cov-report=html
+```
+
+**Why install first?**
+- Tests import from `skill_seekers.cli` which requires the package to be installed
+- Modern Python packaging best practice (PEP 517/518)
+- CI/CD automatically installs with `pip install -e .`
+- conftest.py will show helpful error if package not installed
+
+**Test Coverage:**
+- 391+ tests passing
+- 39% code coverage
+- All core features tested
+- CI/CD tests on Ubuntu + macOS with Python 3.10-3.12
+
+## Troubleshooting
+
+**No content extracted**: Check `main_content` selector. Common values: `article`, `main`, `div[role="main"]`, `div.content`
+
+**Poor categorization**: Edit `categories` section in config with better keywords specific to the documentation structure
+
+**Force re-scrape**: Delete cached data with `rm -rf output/{name}_data/`
+
+**Rate limiting issues**: Increase `rate_limit` value in config (e.g., from 0.5 to 1.0 seconds)
+
+## Output Quality Checks
+
+After building, verify quality:
+```bash
+cat output/godot/SKILL.md              # Should have real code examples
+cat output/godot/references/index.md   # Should show categories
+ls output/godot/references/            # Should have category .md files
+```
+
+## llms.txt Support
+
+Skill_Seekers automatically detects llms.txt files before HTML scraping:
+
+### Detection Order
+1. `{base_url}/llms-full.txt` (complete documentation)
+2. `{base_url}/llms.txt` (standard version)
+3. `{base_url}/llms-small.txt` (quick reference)
+
+### Benefits
+- ⚡ 10x faster (< 5 seconds vs 20-60 seconds)
+- ✅ More reliable (maintained by docs authors)
+- 🎯 Better quality (pre-formatted for LLMs)
+- 🚫 No rate limiting needed
+
+### Example Sites
+- Hono: https://hono.dev/llms-full.txt
+
+If no llms.txt is found, automatically falls back to HTML scraping.

docs/reference/CODE_QUALITY.md

@@ -0,0 +1,823 @@
+# Code Quality Standards
+
+**Version:** 3.6.0
+**Last Updated:** 2026-02-18
+**Status:** ✅ Production Ready
+
+---
+
+## Overview
+
+Skill Seekers maintains high code quality through automated linting, comprehensive testing, and continuous integration. This document outlines the quality standards, tools, and processes used to ensure reliability and maintainability.
+
+**Quality Pillars:**
+1. **Linting** - Automated code style and error detection with Ruff
+2. **Testing** - Comprehensive test coverage (1,880+ tests)
+3. **Type Safety** - Type hints and validation
+4. **Security** - Security scanning with Bandit
+5. **CI/CD** - Automated validation on every commit
+
+---
+
+## Linting with Ruff
+
+### What is Ruff?
+
+**Ruff** is an extremely fast Python linter written in Rust that combines the functionality of multiple tools:
+- Flake8 (style checking)
+- isort (import sorting)
+- Black (code formatting)
+- pyupgrade (Python version upgrades)
+- And 100+ other linting rules
+
+**Why Ruff:**
+- ⚡ 10-100x faster than traditional linters
+- 🔧 Auto-fixes for most issues
+- 📦 Single tool replaces 10+ legacy tools
+- 🎯 Comprehensive rule coverage
+
+### Installation
+
+```bash
+# Using uv (recommended)
+uv pip install ruff
+
+# Using pip
+pip install ruff
+
+# Development installation
+pip install -e ".[dev]"  # Includes ruff
+```
+
+### Running Ruff
+
+#### Check for Issues
+
+```bash
+# Check all Python files
+ruff check .
+
+# Check specific directory
+ruff check src/
+
+# Check specific file
+ruff check src/skill_seekers/cli/doc_scraper.py
+
+# Check with auto-fix
+ruff check --fix .
+```
+
+#### Format Code
+
+```bash
+# Check formatting (dry run)
+ruff format --check .
+
+# Apply formatting
+ruff format .
+
+# Format specific file
+ruff format src/skill_seekers/cli/doc_scraper.py
+```
+
+### Configuration
+
+Ruff configuration is in `pyproject.toml`:
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "UP",   # pyupgrade
+]
+
+ignore = [
+    "E501",  # Line too long (handled by formatter)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",  # Allow assert in tests
+]
+```
+
+---
+
+## Common Ruff Rules
+
+### SIM102: Simplify Nested If Statements
+
+**Before:**
+```python
+if condition1:
+    if condition2:
+        do_something()
+```
+
+**After:**
+```python
+if condition1 and condition2:
+    do_something()
+```
+
+**Why:** Improves readability, reduces nesting levels.
+
+### SIM117: Combine Multiple With Statements
+
+**Before:**
+```python
+with open('file1.txt') as f1:
+    with open('file2.txt') as f2:
+        process(f1, f2)
+```
+
+**After:**
+```python
+with open('file1.txt') as f1, open('file2.txt') as f2:
+    process(f1, f2)
+```
+
+**Why:** Cleaner syntax, better resource management.
+
+### B904: Proper Exception Chaining
+
+**Before:**
+```python
+try:
+    risky_operation()
+except Exception:
+    raise CustomError("Failed")
+```
+
+**After:**
+```python
+try:
+    risky_operation()
+except Exception as e:
+    raise CustomError("Failed") from e
+```
+
+**Why:** Preserves error context, aids debugging.
+
+### SIM113: Remove Unused Enumerate Counter
+
+**Before:**
+```python
+for i, item in enumerate(items):
+    process(item)  # i is never used
+```
+
+**After:**
+```python
+for item in items:
+    process(item)
+```
+
+**Why:** Clearer intent, removes unused variables.
+
+### B007: Unused Loop Variable
+
+**Before:**
+```python
+for item in items:
+    total += 1  # item is never used
+```
+
+**After:**
+```python
+for _ in items:
+    total += 1
+```
+
+**Why:** Explicit that loop variable is intentionally unused.
+
+### ARG002: Unused Method Argument
+
+**Before:**
+```python
+def process(self, data, unused_arg):
+    return data.transform()  # unused_arg never used
+```
+
+**After:**
+```python
+def process(self, data):
+    return data.transform()
+```
+
+**Why:** Removes dead code, clarifies function signature.
+
+---
+
+## Recent Code Quality Improvements
+
+### v3.6.0 Fixes (January 18, 2026)
+
+Fixed **all 21 ruff linting errors** across the codebase:
+
+| Rule | Count | Files Affected | Impact |
+|------|-------|----------------|--------|
+| SIM102 | 7 | config_extractor.py, pattern_recognizer.py (3) | Combined nested if statements |
+| SIM117 | 9 | test_example_extractor.py (3), unified_skill_builder.py | Combined with statements |
+| B904 | 1 | pdf_scraper.py | Added exception chaining |
+| SIM113 | 1 | config_validator.py | Removed unused enumerate counter |
+| B007 | 1 | doc_scraper.py | Changed unused loop variable to _ |
+| ARG002 | 1 | test fixture | Removed unused test argument |
+| **Total** | **21** | **12 files** | **Zero linting errors** |
+
+**Result:** Clean codebase with zero linting errors, improved maintainability.
+
+### Files Updated
+
+1. **src/skill_seekers/cli/config_extractor.py** (SIM102 fixes)
+2. **src/skill_seekers/cli/config_validator.py** (SIM113 fix)
+3. **src/skill_seekers/cli/doc_scraper.py** (B007 fix)
+4. **src/skill_seekers/cli/pattern_recognizer.py** (3 × SIM102 fixes)
+5. **src/skill_seekers/cli/test_example_extractor.py** (3 × SIM117 fixes)
+6. **src/skill_seekers/cli/unified_skill_builder.py** (SIM117 fix)
+7. **src/skill_seekers/cli/pdf_scraper.py** (B904 fix)
+8. **6 test files** (various fixes)
+
+---
+
+## Testing Requirements
+
+### Test Coverage Standards
+
+**Critical Paths:** 100% coverage required
+- Core scraping logic
+- Platform adaptors
+- MCP tool implementations
+- Configuration validation
+
+**Overall Project:** >80% coverage target
+
+**Current Status:**
+- ✅ 1,880+ tests passing
+- ✅ >85% code coverage
+- ✅ All critical paths covered
+- ✅ CI/CD integrated
+
+### Running Tests
+
+#### All Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src/skill_seekers --cov-report=term --cov-report=html
+
+# View HTML coverage report
+open htmlcov/index.html
+```
+
+#### Specific Test Categories
+
+```bash
+# Unit tests only
+pytest tests/test_*.py -v
+
+# Integration tests
+pytest tests/test_*_integration.py -v
+
+# E2E tests
+pytest tests/test_*_e2e.py -v
+
+# MCP tests
+pytest tests/test_mcp*.py -v
+```
+
+#### Test Markers
+
+```bash
+# Slow tests (skip by default)
+pytest tests/ -m "not slow"
+
+# Run slow tests
+pytest tests/ -m slow
+
+# Async tests
+pytest tests/ -m asyncio
+```
+
+### Test Categories
+
+1. **Unit Tests** (800+ tests)
+   - Individual function testing
+   - Isolated component testing
+   - Mock external dependencies
+
+2. **Integration Tests** (300+ tests)
+   - Multi-component workflows
+   - End-to-end feature testing
+   - Real file system operations
+
+3. **E2E Tests** (100+ tests)
+   - Complete user workflows
+   - CLI command testing
+   - Platform integration testing
+
+4. **MCP Tests** (63 tests)
+   - All 40 MCP tools
+   - Transport mode testing (stdio, HTTP)
+   - Error handling validation
+
+### Test Requirements Before Commits
+
+**Per user instructions in `~/.claude/CLAUDE.md`:**
+
+> "never skip any test. always make sure all test pass"
+
+**This means:**
+- ✅ **ALL 1,880+ tests must pass** before commits
+- ✅ No skipping tests, even if they're slow
+- ✅ Add tests for new features
+- ✅ Fix failing tests immediately
+- ✅ Maintain or improve coverage
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Workflow
+
+Skill Seekers uses GitHub Actions for automated quality checks on every commit and PR.
+
+#### Workflow Configuration
+
+```yaml
+# .github/workflows/ci.yml (excerpt)
+name: CI
+
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+    branches: [main, development]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install ruff
+
+      - name: Run Ruff Check
+        run: ruff check .
+
+      - name: Run Ruff Format Check
+        run: ruff format --check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install -e ".[all-llms,dev]"
+
+      - name: Run tests
+        run: pytest tests/ --cov=src/skill_seekers --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+```
+
+### CI Checks
+
+Every commit and PR must pass:
+
+1. **Ruff Linting** - Zero linting errors
+2. **Ruff Formatting** - Consistent code style
+3. **Pytest** - All 1,880+ tests passing
+4. **Coverage** - >80% code coverage
+5. **Multi-platform** - Ubuntu + macOS
+6. **Multi-version** - Python 3.10-3.13
+
+**Status:** ✅ All checks passing
+
+---
+
+## Pre-commit Hooks
+
+### Setup
+
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# Install hooks
+pre-commit install
+```
+
+### Configuration
+
+Create `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.0
+    hooks:
+      # Run ruff linter
+      - id: ruff
+        args: [--fix]
+      # Run ruff formatter
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      # Run tests before commit
+      - id: pytest
+        name: pytest
+        entry: pytest
+        language: system
+        pass_filenames: false
+        always_run: true
+        args: [tests/, -v]
+```
+
+### Usage
+
+```bash
+# Pre-commit hooks run automatically on git commit
+git add .
+git commit -m "Your message"
+# → Runs ruff check, ruff format, pytest
+
+# Run manually on all files
+pre-commit run --all-files
+
+# Skip hooks (emergency only!)
+git commit -m "Emergency fix" --no-verify
+```
+
+---
+
+## Best Practices
+
+### Code Organization
+
+#### Import Ordering
+
+```python
+# 1. Standard library imports
+import os
+import sys
+from pathlib import Path
+
+# 2. Third-party imports
+import anthropic
+import requests
+from fastapi import FastAPI
+
+# 3. Local application imports
+from skill_seekers.cli.doc_scraper import scrape_all
+from skill_seekers.cli.adaptors import get_adaptor
+```
+
+**Tool:** Ruff automatically sorts imports with `I` rule.
+
+#### Naming Conventions
+
+```python
+# Constants: UPPER_SNAKE_CASE
+MAX_PAGES = 500
+DEFAULT_TIMEOUT = 30
+
+# Classes: PascalCase
+class DocumentationScraper:
+    pass
+
+# Functions/variables: snake_case
+def scrape_all(base_url, config):
+    pages_count = 0
+    return pages_count
+
+# Private: leading underscore
+def _internal_helper():
+    pass
+```
+
+### Documentation
+
+#### Docstrings
+
+```python
+def scrape_all(base_url: str, config: dict) -> list[dict]:
+    """Scrape documentation from a website using BFS traversal.
+
+    Args:
+        base_url: The root URL to start scraping from
+        config: Configuration dict with selectors and patterns
+
+    Returns:
+        List of page dictionaries containing title, content, URL
+
+    Raises:
+        NetworkError: If connection fails
+        InvalidConfigError: If config is malformed
+
+    Example:
+        >>> pages = scrape_all('https://docs.example.com', config)
+        >>> len(pages)
+        42
+    """
+    pass
+```
+
+#### Type Hints
+
+```python
+from typing import Optional, Union, Literal
+
+def package_skill(
+    skill_dir: str | Path,
+    target: Literal['claude', 'gemini', 'openai', 'markdown'],
+    output_path: Optional[str] = None
+) -> str:
+    """Package skill for target platform."""
+    pass
+```
+
+### Error Handling
+
+#### Exception Patterns
+
+```python
+# Good: Specific exceptions with context
+try:
+    result = risky_operation()
+except NetworkError as e:
+    raise ScrapingError(f"Failed to fetch {url}") from e
+
+# Bad: Bare except
+try:
+    result = risky_operation()
+except:  # ❌ Too broad, loses error info
+    pass
+```
+
+#### Logging
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Log at appropriate levels
+logger.debug("Processing page: %s", url)
+logger.info("Scraped %d pages", len(pages))
+logger.warning("Rate limit approaching: %d requests", count)
+logger.error("Failed to parse: %s", url, exc_info=True)
+```
+
+---
+
+## Security Scanning
+
+### Bandit
+
+Bandit scans for security vulnerabilities in Python code.
+
+#### Installation
+
+```bash
+pip install bandit
+```
+
+#### Running Bandit
+
+```bash
+# Scan all Python files
+bandit -r src/
+
+# Scan with config
+bandit -r src/ -c pyproject.toml
+
+# Generate JSON report
+bandit -r src/ -f json -o bandit-report.json
+```
+
+#### Common Security Issues
+
+**B404: Import of subprocess module**
+```python
+# Review: Ensure safe usage of subprocess
+import subprocess
+
+# ✅ Safe: Using subprocess with shell=False and list arguments
+subprocess.run(['ls', '-l'], shell=False)
+
+# ❌ UNSAFE: Using shell=True with user input (NEVER DO THIS)
+# This is an example of what NOT to do - security vulnerability!
+# subprocess.run(f'ls {user_input}', shell=True)
+```
+
+**B605: Start process with a shell**
+```python
+# ❌ UNSAFE: Shell injection risk (NEVER DO THIS)
+# Example of security anti-pattern:
+# import os
+# os.system(f'rm {filename}')
+
+# ✅ Safe: Use subprocess with list arguments
+import subprocess
+subprocess.run(['rm', filename], shell=False)
+```
+
+**Security Best Practices:**
+- Never use `shell=True` with user input
+- Always validate and sanitize user input
+- Use subprocess with list arguments instead of shell commands
+- Avoid dynamic command construction
+
+---
+
+## Development Workflow
+
+### 1. Before Starting Work
+
+```bash
+# Pull latest changes
+git checkout development
+git pull origin development
+
+# Create feature branch
+git checkout -b feature/your-feature
+
+# Install dependencies
+pip install -e ".[all-llms,dev]"
+```
+
+### 2. During Development
+
+```bash
+# Run linter frequently
+ruff check src/skill_seekers/cli/your_file.py --fix
+
+# Run relevant tests
+pytest tests/test_your_feature.py -v
+
+# Check formatting
+ruff format src/skill_seekers/cli/your_file.py
+```
+
+### 3. Before Committing
+
+```bash
+# Run all linting checks
+ruff check .
+ruff format --check .
+
+# Run full test suite (REQUIRED)
+pytest tests/ -v
+
+# Check coverage
+pytest tests/ --cov=src/skill_seekers --cov-report=term
+
+# Verify all tests pass ✅
+```
+
+### 4. Committing Changes
+
+```bash
+# Stage changes
+git add .
+
+# Commit (pre-commit hooks will run)
+git commit -m "feat: Add your feature
+
+- Detailed change 1
+- Detailed change 2
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+
+# Push to remote
+git push origin feature/your-feature
+```
+
+### 5. Creating Pull Request
+
+```bash
+# Create PR via GitHub CLI
+gh pr create --title "Add your feature" --body "Description..."
+
+# CI checks will run automatically:
+# ✅ Ruff linting
+# ✅ Ruff formatting
+# ✅ Pytest (1,880+ tests)
+# ✅ Coverage report
+# ✅ Multi-platform (Ubuntu + macOS)
+# ✅ Multi-version (Python 3.10-3.13)
+```
+
+---
+
+## Quality Metrics
+
+### Current Status (v3.6.0)
+
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Linting Errors | 0 | 0 | ✅ |
+| Test Count | 1200+ | 1000+ | ✅ |
+| Test Pass Rate | 100% | 100% | ✅ |
+| Code Coverage | >85% | >80% | ✅ |
+| CI Pass Rate | 100% | >95% | ✅ |
+| Python Versions | 3.10-3.13 | 3.10+ | ✅ |
+| Platforms | Ubuntu, macOS | 2+ | ✅ |
+
+### Historical Improvements
+
+| Version | Linting Errors | Tests | Coverage |
+|---------|----------------|-------|----------|
+| v2.5.0 | 38 | 602 | 75% |
+| v2.6.0 | 21 | 700+ | 80% |
+| v2.7.0 | 0 | 1200+ | 85%+ |
+
+**Progress:** Continuous improvement in all quality metrics.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Linting Errors After Update
+
+```bash
+# Update ruff
+pip install --upgrade ruff
+
+# Re-run checks
+ruff check .
+```
+
+#### 2. Tests Failing Locally
+
+```bash
+# Ensure package is installed
+pip install -e ".[all-llms,dev]"
+
+# Clear pytest cache
+rm -rf .pytest_cache/
+rm -rf **/__pycache__/
+
+# Re-run tests
+pytest tests/ -v
+```
+
+#### 3. Coverage Too Low
+
+```bash
+# Generate detailed coverage report
+pytest tests/ --cov=src/skill_seekers --cov-report=html
+
+# Open report
+open htmlcov/index.html
+
+# Identify untested code (red lines)
+# Add tests for uncovered lines
+```
+
+---
+
+## Related Documentation
+
+- **[Testing Guide](../guides/TESTING_GUIDE.md)** - Comprehensive testing documentation
+- **[Contributing Guide](../../CONTRIBUTING.md)** - Contribution guidelines
+- **[API Reference](API_REFERENCE.md)** - Programmatic usage
+- **[CHANGELOG](../../CHANGELOG.md)** - Version history and changes
+
+---
+
+**Version:** 3.6.0
+**Last Updated:** 2026-02-18
+**Status:** ✅ Production Ready

docs/reference/CONFIG_FORMAT.md

@@ -0,0 +1,859 @@
+# Config Format Reference - Skill Seekers
+
+> **Version:** 3.6.0
+> **Last Updated:** 2026-03-15
+> **Complete JSON configuration specification for 18 source types**
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Single-Source Config](#single-source-config)
+  - [Documentation Source](#documentation-source)
+  - [GitHub Source](#github-source)
+  - [PDF Source](#pdf-source)
+  - [Local Source](#local-source)
+  - [Additional Source Types](#additional-source-types)
+- [Unified (Multi-Source) Config](#unified-multi-source-config)
+- [Common Fields](#common-fields)
+- [Selectors](#selectors)
+- [Categories](#categories)
+- [URL Patterns](#url-patterns)
+- [Examples](#examples)
+
+---
+
+## Overview
+
+Skill Seekers uses JSON configuration files with a unified format. All configs use a `sources` array, even for single-source scraping.
+
+> **Important:** Legacy configs without `sources` were removed in v2.11.0. All configs must use the unified format shown below.
+
+| Use Case | Example |
+|----------|---------|
+| **Single source** | `"sources": [{ "type": "documentation", ... }]` |
+| **Multiple sources** | `"sources": [{ "type": "documentation", ... }, { "type": "github", ... }]` |
+
+---
+
+## Single-Source Config
+
+Even for a single source, wrap it in a `sources` array.
+
+### Documentation Source
+
+For scraping documentation websites.
+
+```json
+{
+  "name": "react",
+  "description": "React - JavaScript library for building UIs",
+  "sources": [
+    {
+      "type": "documentation",
+      "base_url": "https://react.dev/",
+
+      "start_urls": [
+        "https://react.dev/learn",
+        "https://react.dev/reference/react"
+      ],
+
+      "selectors": {
+        "main_content": "article",
+        "title": "h1",
+        "code_blocks": "pre code"
+      },
+
+      "url_patterns": {
+        "include": ["/learn/", "/reference/"],
+        "exclude": ["/blog/", "/community/"]
+      },
+
+      "categories": {
+        "getting_started": ["learn", "tutorial", "intro"],
+        "api": ["reference", "api", "hooks"]
+      },
+
+      "rate_limit": 0.5,
+      "max_pages": 300
+    }
+  ]
+}
+```
+
+#### Documentation Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Skill name (alphanumeric, dashes, underscores) |
+| `base_url` | string | Yes | - | Base documentation URL |
+| `description` | string | No | "" | Skill description for SKILL.md |
+| `start_urls` | array | No | `[base_url]` | URLs to start crawling from |
+| `selectors` | object | No | see below | CSS selectors for content extraction |
+| `url_patterns` | object | No | `{}` | Include/exclude URL patterns |
+| `categories` | object | No | `{}` | Content categorization rules |
+| `rate_limit` | number | No | 0.5 | Seconds between requests |
+| `max_pages` | number | No | 500 | Maximum pages to scrape |
+| `merge_mode` | string | No | "claude-enhanced" | Merge strategy |
+| `extract_api` | boolean | No | false | Extract API references |
+| `llms_txt_url` | string | No | auto | Path to llms.txt file |
+
+---
+
+### GitHub Source
+
+For analyzing GitHub repositories.
+
+```json
+{
+  "name": "react-github",
+  "description": "React GitHub repository analysis",
+  "sources": [
+    {
+      "type": "github",
+      "repo": "facebook/react",
+
+      "enable_codebase_analysis": true,
+      "code_analysis_depth": "deep",
+
+      "fetch_issues": true,
+      "max_issues": 100,
+      "issue_labels": ["bug", "enhancement"],
+
+      "fetch_releases": true,
+      "max_releases": 20,
+
+      "fetch_changelog": true,
+      "analyze_commit_history": true,
+
+      "file_patterns": ["*.js", "*.ts", "*.tsx"],
+      "exclude_patterns": ["*.test.js", "node_modules/**"],
+
+      "rate_limit": 1.0
+    }
+  ]
+}
+```
+
+#### GitHub Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Skill name |
+| `type` | string | Yes | - | Must be `"github"` |
+| `repo` | string | Yes | - | Repository in `owner/repo` format |
+| `description` | string | No | "" | Skill description |
+| `enable_codebase_analysis` | boolean | No | true | Analyze source code |
+| `code_analysis_depth` | string | No | "standard" | `surface`, `standard`, `deep` |
+| `fetch_issues` | boolean | No | true | Fetch GitHub issues |
+| `max_issues` | number | No | 100 | Maximum issues to fetch |
+| `issue_labels` | array | No | [] | Filter by labels |
+| `fetch_releases` | boolean | No | true | Fetch releases |
+| `max_releases` | number | No | 20 | Maximum releases |
+| `fetch_changelog` | boolean | No | true | Extract CHANGELOG |
+| `analyze_commit_history` | boolean | No | false | Analyze commits |
+| `file_patterns` | array | No | [] | Include file patterns |
+| `exclude_patterns` | array | No | [] | Exclude file patterns |
+
+---
+
+### PDF Source
+
+For extracting content from PDF files.
+
+```json
+{
+  "name": "product-manual",
+  "description": "Product documentation manual",
+  "sources": [
+    {
+      "type": "pdf",
+      "pdf_path": "docs/manual.pdf",
+
+      "enable_ocr": false,
+      "password": "",
+
+      "extract_images": true,
+      "image_output_dir": "output/images/",
+
+      "extract_tables": true,
+      "table_format": "markdown",
+
+      "page_range": [1, 100],
+      "split_by_chapters": true,
+
+      "chunk_size": 1000,
+      "chunk_overlap": 100
+    }
+  ]
+}
+```
+
+#### PDF Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Skill name |
+| `type` | string | Yes | - | Must be `"pdf"` |
+| `pdf_path` | string | Yes | - | Path to PDF file |
+| `description` | string | No | "" | Skill description |
+| `enable_ocr` | boolean | No | false | OCR for scanned PDFs |
+| `password` | string | No | "" | PDF password if encrypted |
+| `extract_images` | boolean | No | false | Extract embedded images |
+| `image_output_dir` | string | No | auto | Directory for images |
+| `extract_tables` | boolean | No | false | Extract tables |
+| `table_format` | string | No | "markdown" | `markdown`, `json`, `csv` |
+| `page_range` | array | No | all | `[start, end]` page range |
+| `split_by_chapters` | boolean | No | false | Split by detected chapters |
+| `chunk_size` | number | No | 1000 | Characters per chunk |
+| `chunk_overlap` | number | No | 100 | Overlap between chunks |
+
+---
+
+### Local Source
+
+For analyzing local codebases.
+
+```json
+{
+  "name": "my-project",
+  "description": "Local project analysis",
+  "sources": [
+    {
+      "type": "local",
+      "directory": "./my-project",
+
+      "languages": ["Python", "JavaScript"],
+      "file_patterns": ["*.py", "*.js"],
+      "exclude_patterns": ["*.pyc", "node_modules/**", ".git/**"],
+
+      "analysis_depth": "comprehensive",
+
+      "extract_api": true,
+      "extract_patterns": true,
+      "extract_test_examples": true,
+      "extract_how_to_guides": true,
+      "extract_config_patterns": true,
+
+      "include_comments": true,
+      "include_docstrings": true,
+      "include_readme": true
+    }
+  ]
+}
+```
+
+#### Local Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Skill name |
+| `type` | string | Yes | - | Must be `"local"` |
+| `directory` | string | Yes | - | Path to directory |
+| `description` | string | No | "" | Skill description |
+| `languages` | array | No | auto | Languages to analyze |
+| `file_patterns` | array | No | all | Include patterns |
+| `exclude_patterns` | array | No | common | Exclude patterns |
+| `analysis_depth` | string | No | "standard" | `quick`, `standard`, `comprehensive` |
+| `extract_api` | boolean | No | true | Extract API documentation |
+| `extract_patterns` | boolean | No | true | Detect patterns |
+| `extract_test_examples` | boolean | No | true | Extract test examples |
+| `extract_how_to_guides` | boolean | No | true | Generate guides |
+| `extract_config_patterns` | boolean | No | true | Extract config patterns |
+| `include_comments` | boolean | No | true | Include code comments |
+| `include_docstrings` | boolean | No | true | Include docstrings |
+| `include_readme` | boolean | No | true | Include README |
+
+---
+
+### Additional Source Types
+
+The following 10 source types were added in v3.2.0. Each can be used as a standalone config or within a unified `sources` array.
+
+#### Jupyter Notebook Source
+
+```json
+{
+  "name": "ml-tutorial",
+  "sources": [{
+    "type": "jupyter",
+    "notebook_path": "notebooks/tutorial.ipynb"
+  }]
+}
+```
+
+#### Local HTML Source
+
+```json
+{
+  "name": "offline-docs",
+  "sources": [{
+    "type": "html",
+    "html_path": "./exported-docs/"
+  }]
+}
+```
+
+#### OpenAPI/Swagger Source
+
+```json
+{
+  "name": "petstore-api",
+  "sources": [{
+    "type": "openapi",
+    "spec_path": "api/openapi.yaml",
+    "spec_url": "https://petstore.swagger.io/v2/swagger.json"
+  }]
+}
+```
+
+#### AsciiDoc Source
+
+```json
+{
+  "name": "project-guide",
+  "sources": [{
+    "type": "asciidoc",
+    "asciidoc_path": "./docs/guide.adoc"
+  }]
+}
+```
+
+#### PowerPoint Source
+
+```json
+{
+  "name": "training-slides",
+  "sources": [{
+    "type": "pptx",
+    "pptx_path": "presentations/training.pptx"
+  }]
+}
+```
+
+#### RSS/Atom Feed Source
+
+```json
+{
+  "name": "engineering-blog",
+  "sources": [{
+    "type": "rss",
+    "feed_url": "https://engineering.example.com/feed.xml",
+    "follow_links": true,
+    "max_articles": 50
+  }]
+}
+```
+
+#### Man Page Source
+
+```json
+{
+  "name": "unix-tools",
+  "sources": [{
+    "type": "manpage",
+    "man_names": "ls,grep,find,awk,sed",
+    "sections": "1,3"
+  }]
+}
+```
+
+#### Confluence Source
+
+```json
+{
+  "name": "team-wiki",
+  "sources": [{
+    "type": "confluence",
+    "base_url": "https://wiki.example.com",
+    "space_key": "DEV",
+    "username": "user@example.com",
+    "max_pages": 500
+  }]
+}
+```
+
+#### Notion Source
+
+```json
+{
+  "name": "product-docs",
+  "sources": [{
+    "type": "notion",
+    "database_id": "abc123def456",
+    "max_pages": 500
+  }]
+}
+```
+
+#### Chat (Slack/Discord) Source
+
+```json
+{
+  "name": "team-knowledge",
+  "sources": [{
+    "type": "chat",
+    "export_path": "./slack-export/",
+    "platform": "slack",
+    "channel": "engineering",
+    "max_messages": 10000
+  }]
+}
+```
+
+#### Additional Source Fields Reference
+
+| Source Type | Required Fields | Optional Fields |
+|-------------|-----------------|-----------------|
+| `jupyter` | `notebook_path` | — |
+| `html` | `html_path` | — |
+| `openapi` | `spec_path` or `spec_url` | — |
+| `asciidoc` | `asciidoc_path` | — |
+| `pptx` | `pptx_path` | — |
+| `rss` | `feed_url` or `feed_path` | `follow_links`, `max_articles` |
+| `manpage` | `man_names` or `man_path` | `sections` |
+| `confluence` | `base_url` + `space_key` or `export_path` | `username`, `token`, `max_pages` |
+| `notion` | `database_id` or `page_id` or `export_path` | `token`, `max_pages` |
+| `chat` | `export_path` | `platform`, `token`, `channel`, `max_messages` |
+
+---
+
+## Unified (Multi-Source) Config
+
+Combine multiple sources into one skill with conflict detection.
+
+```json
+{
+  "name": "react-complete",
+  "description": "React docs + GitHub + examples",
+  "merge_mode": "claude-enhanced",
+  
+  "sources": [
+    {
+      "type": "docs",
+      "name": "react-docs",
+      "base_url": "https://react.dev/",
+      "max_pages": 200,
+      "categories": {
+        "getting_started": ["learn"],
+        "api": ["reference"]
+      }
+    },
+    {
+      "type": "github",
+      "name": "react-github",
+      "repo": "facebook/react",
+      "fetch_issues": true,
+      "max_issues": 50
+    },
+    {
+      "type": "pdf",
+      "name": "react-cheatsheet",
+      "pdf_path": "docs/react-cheatsheet.pdf"
+    },
+    {
+      "type": "local",
+      "name": "react-examples",
+      "directory": "./react-examples"
+    }
+  ],
+  
+  "conflict_detection": {
+    "enabled": true,
+    "rules": [
+      {
+        "field": "api_signature",
+        "action": "flag_mismatch"
+      }
+    ]
+  },
+  
+  "output_structure": {
+    "group_by_source": false,
+    "cross_reference": true
+  }
+}
+```
+
+#### Unified Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Combined skill name |
+| `description` | string | No | "" | Skill description |
+| `merge_mode` | string | No | "claude-enhanced" | `rule-based`, `claude-enhanced` |
+| `sources` | array | Yes | - | List of source configs |
+| `conflict_detection` | object | No | `{}` | Conflict detection settings |
+| `output_structure` | object | No | `{}` | Output organization |
+| `workflows` | array | No | `[]` | Workflow presets to apply |
+| `workflow_stages` | array | No | `[]` | Inline enhancement stages |
+| `workflow_vars` | object | No | `{}` | Workflow variable overrides |
+| `workflow_dry_run` | boolean | No | `false` | Preview workflows without executing |
+
+#### Workflow Configuration (Unified)
+
+Unified configs support defining enhancement workflows at the top level:
+
+```json
+{
+  "name": "react-complete",
+  "description": "React docs + GitHub with security enhancement",
+  "merge_mode": "claude-enhanced",
+  
+  "workflows": ["security-focus", "api-documentation"],
+  "workflow_stages": [
+    {
+      "name": "cleanup",
+      "prompt": "Remove boilerplate sections and standardize formatting"
+    }
+  ],
+  "workflow_vars": {
+    "focus_area": "performance",
+    "detail_level": "comprehensive"
+  },
+  
+  "sources": [
+    {"type": "docs", "base_url": "https://react.dev/"},
+    {"type": "github", "repo": "facebook/react"}
+  ]
+}
+```
+
+**Workflow Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `workflows` | array | List of workflow preset names to apply |
+| `workflow_stages` | array | Inline stages with `name` and `prompt` |
+| `workflow_vars` | object | Key-value pairs for workflow variables |
+| `workflow_dry_run` | boolean | Preview workflows without executing |
+
+**Note:** CLI flags override config values (CLI takes precedence).
+
+#### Source Types in Unified Config
+
+Each source in the `sources` array can be any of the 17 supported types:
+
+| Type | Required Fields |
+|------|-----------------|
+| `documentation` / `docs` | `base_url` |
+| `github` | `repo` |
+| `pdf` | `pdf_path` |
+| `word` | `docx_path` |
+| `epub` | `epub_path` |
+| `video` | `url` or `video_path` |
+| `local` | `directory` |
+| `jupyter` | `notebook_path` |
+| `html` | `html_path` |
+| `openapi` | `spec_path` or `spec_url` |
+| `asciidoc` | `asciidoc_path` |
+| `pptx` | `pptx_path` |
+| `rss` | `feed_url` or `feed_path` |
+| `manpage` | `man_names` or `man_path` |
+| `confluence` | `base_url` + `space_key` or `export_path` |
+| `notion` | `database_id` or `page_id` or `export_path` |
+| `chat` | `export_path` |
+
+---
+
+## Common Fields
+
+Fields available in all config types:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Skill identifier. Must match `^[a-zA-Z0-9_-]+$` (letters, numbers, dashes, underscores). Required for community-registry submission. |
+| `description` | string | Human-readable description |
+| `metadata.detected_version` | string \| null | **Optional, stamped by `skill-seekers scan`.** The framework version detected from the project's manifest (e.g. `"18.3.1"` for React from `package.json`). Lives under `metadata` alongside `metadata.version` (which is the config-schema version — different thing). Used by re-scans to report version bumps. Legacy top-level placement is still read for backwards-compat but new writes go to metadata. |
+| `metadata._url_unverified` | list[str] \| absent | **Optional, stamped by `skill-seekers scan --probe-urls`.** List of URLs in this config that returned 4xx/5xx on the post-generation HEAD probe and weren't fixable by re-prompting the AI. Present only when the AI invented an unreachable `base_url` or GitHub repo. Treat as a TODO: replace the bad URLs and remove the field. Underscore prefix marks it as scan-tooling metadata, not part of the canonical schema. |
+| `rate_limit` | number | Delay between requests in seconds |
+| `output_dir` | string | Custom output directory |
+| `skip_scrape` | boolean | Use existing data |
+| `enhance_level` | number | 0=off, 1=SKILL.md, 2=+config, 3=full |
+
+---
+
+## Selectors
+
+CSS selectors for content extraction from HTML:
+
+```json
+{
+  "selectors": {
+    "main_content": "article",
+    "title": "h1",
+    "code_blocks": "pre code",
+    "navigation": "nav.sidebar",
+    "breadcrumbs": "nav[aria-label='breadcrumb']",
+    "next_page": "a[rel='next']",
+    "prev_page": "a[rel='prev']"
+  }
+}
+```
+
+### Default Selectors
+
+If `main_content` is not specified, the scraper tries these selectors in order until one matches:
+
+1. `main`
+2. `div[role="main"]`
+3. `article`
+4. `[role="main"]`
+5. `.content`
+6. `.doc-content`
+7. `#main-content`
+
+> **Tip:** Omit `main_content` from your config to let auto-detection work.
+> Only specify it when auto-detection picks the wrong element.
+
+Other defaults:
+
+| Element | Default Selector |
+|---------|-----------------|
+| `title` | `title` |
+| `code_blocks` | `pre code` |
+
+---
+
+## Categories
+
+Map URL patterns to content categories:
+
+```json
+{
+  "categories": {
+    "getting_started": [
+      "intro", "tutorial", "quickstart", 
+      "installation", "getting-started"
+    ],
+    "core_concepts": [
+      "concept", "fundamental", "architecture",
+      "principle", "overview"
+    ],
+    "api_reference": [
+      "reference", "api", "method", "function",
+      "class", "interface", "type"
+    ],
+    "guides": [
+      "guide", "how-to", "example", "recipe",
+      "pattern", "best-practice"
+    ],
+    "advanced": [
+      "advanced", "expert", "performance",
+      "optimization", "internals"
+    ]
+  }
+}
+```
+
+Categories appear as sections in the generated SKILL.md.
+
+---
+
+## URL Patterns
+
+Control which URLs are included or excluded:
+
+```json
+{
+  "url_patterns": {
+    "include": [
+      "/docs/",
+      "/guide/",
+      "/api/",
+      "/reference/"
+    ],
+    "exclude": [
+      "/blog/",
+      "/news/",
+      "/community/",
+      "/search",
+      "?print=1",
+      "/_static/",
+      "/_images/"
+    ]
+  }
+}
+```
+
+### Pattern Rules
+
+- Patterns are matched against the URL path
+- Use `*` for wildcards: `/api/v*/`
+- Use `**` for recursive: `/docs/**/*.html`
+- Exclude takes precedence over include
+
+---
+
+## Examples
+
+### React Documentation
+
+```json
+{
+  "name": "react",
+  "description": "React - JavaScript library for building UIs",
+  "sources": [
+    {
+      "type": "documentation",
+      "base_url": "https://react.dev/",
+      "start_urls": [
+        "https://react.dev/learn",
+        "https://react.dev/reference/react",
+        "https://react.dev/reference/react-dom"
+      ],
+      "selectors": {
+        "main_content": "article",
+        "title": "h1",
+        "code_blocks": "pre code"
+      },
+      "url_patterns": {
+        "include": ["/learn/", "/reference/"],
+        "exclude": ["/community/", "/search"]
+      },
+      "categories": {
+        "getting_started": ["learn", "tutorial"],
+        "api": ["reference", "api"]
+      },
+      "rate_limit": 0.5,
+      "max_pages": 300
+    }
+  ]
+}
+```
+
+### Django GitHub
+
+```json
+{
+  "name": "django-github",
+  "description": "Django web framework source code",
+  "sources": [
+    {
+      "type": "github",
+      "repo": "django/django",
+      "enable_codebase_analysis": true,
+      "code_analysis_depth": "deep",
+      "fetch_issues": true,
+      "max_issues": 100,
+      "fetch_releases": true,
+      "file_patterns": ["*.py"],
+      "exclude_patterns": ["tests/**", "docs/**"]
+    }
+  ]
+}
+```
+
+### Unified Multi-Source
+
+```json
+{
+  "name": "godot-complete",
+  "description": "Godot Engine - docs, source, and manual",
+  "merge_mode": "claude-enhanced",
+  "sources": [
+    {
+      "type": "docs",
+      "name": "godot-docs",
+      "base_url": "https://docs.godotengine.org/en/stable/",
+      "max_pages": 500
+    },
+    {
+      "type": "github",
+      "name": "godot-source",
+      "repo": "godotengine/godot",
+      "fetch_issues": false
+    },
+    {
+      "type": "pdf",
+      "name": "godot-manual",
+      "pdf_path": "docs/godot-manual.pdf"
+    }
+  ]
+}
+```
+
+### Unified with New Source Types
+
+```json
+{
+  "name": "project-complete",
+  "description": "Full project knowledge from multiple source types",
+  "merge_mode": "claude-enhanced",
+  "sources": [
+    {
+      "type": "docs",
+      "name": "project-docs",
+      "base_url": "https://docs.example.com/",
+      "max_pages": 200
+    },
+    {
+      "type": "github",
+      "name": "project-code",
+      "repo": "example/project"
+    },
+    {
+      "type": "openapi",
+      "name": "project-api",
+      "spec_path": "api/openapi.yaml"
+    },
+    {
+      "type": "confluence",
+      "name": "project-wiki",
+      "export_path": "./confluence-export/"
+    },
+    {
+      "type": "jupyter",
+      "name": "project-notebooks",
+      "notebook_path": "./notebooks/"
+    }
+  ]
+}
+```
+
+### Local Project
+
+```json
+{
+  "name": "my-api",
+  "description": "My REST API implementation",
+  "sources": [
+    {
+      "type": "local",
+      "directory": "./my-api-project",
+      "languages": ["Python"],
+      "file_patterns": ["*.py"],
+      "exclude_patterns": ["tests/**", "migrations/**"],
+      "analysis_depth": "comprehensive",
+      "extract_api": true,
+      "extract_test_examples": true
+    }
+  ]
+}
+```
+
+---
+
+## Validation
+
+Validate your config before scraping:
+
+```bash
+# Using CLI
+skill-seekers create --config my-config.json --dry-run
+
+# Using MCP tool
+validate_config({"config": "my-config.json"})
+```
+
+---
+
+## See Also
+
+- [CLI Reference](CLI_REFERENCE.md) - Command reference
+- [Environment Variables](ENVIRONMENT_VARIABLES.md) - Configuration environment
+
+---
+
+*For more examples, see `configs/` directory in the repository*

docs/reference/ENVIRONMENT_VARIABLES.md

@@ -0,0 +1,885 @@
+# Environment Variables Reference - Skill Seekers
+
+> **Version:** 3.7.0  
+> **Last Updated:** 2026-02-16  
+> **Complete environment variable reference**
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [API Keys](#api-keys)
+- [Platform Configuration](#platform-configuration)
+- [LLM Provider Selection](#llm-provider-selection)
+- [Paths and Directories](#paths-and-directories)
+- [Scraping Behavior](#scraping-behavior)
+- [Enhancement Settings](#enhancement-settings)
+- [GitHub Configuration](#github-configuration)
+- [Vector Database Settings](#vector-database-settings)
+- [Debug and Development](#debug-and-development)
+- [MCP Server Settings](#mcp-server-settings)
+- [Examples](#examples)
+
+---
+
+## Overview
+
+Skill Seekers uses environment variables for:
+- API authentication (Claude, Gemini, OpenAI, GitHub)
+- Configuration paths
+- Output directories
+- Behavior customization
+- Debug settings
+
+Variables are read at runtime and override default settings.
+
+---
+
+## API Keys
+
+### ANTHROPIC_API_KEY
+
+**Purpose:** Claude AI API access for enhancement and upload.
+
+**Format:** `sk-ant-api03-...`
+
+**Used by:**
+- `skill-seekers enhance` (API mode)
+- `skill-seekers upload` (Claude target)
+- AI enhancement features
+
+**Example:**
+```bash
+export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+**Alternative:** Use `--api-key` flag per command.
+
+---
+
+### GOOGLE_API_KEY
+
+**Purpose:** Google Gemini API access for upload.
+
+**Format:** `AIza...`
+
+**Used by:**
+- `skill-seekers upload` (Gemini target)
+
+**Example:**
+```bash
+export GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+---
+
+### OPENAI_API_KEY
+
+**Purpose:** OpenAI (and OpenAI-compatible) API access for enhancement, upload, and embeddings.
+
+**Format:** `sk-...`
+
+**Used by:**
+- `skill-seekers create` / `scan` / `enhance` (AI enhancement, API mode)
+- `skill-seekers upload` (OpenAI target)
+- Embedding generation for vector DBs
+
+**Example:**
+```bash
+export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+> Combine with `OPENAI_BASE_URL` + `OPENAI_MODEL` to route enhancement through any
+> OpenAI-compatible provider (OpenRouter, Groq, Cerebras, Mistral, NVIDIA NIM).
+> See [LLM Provider Selection](#llm-provider-selection).
+
+---
+
+### MOONSHOT_API_KEY
+
+**Purpose:** Moonshot AI (Kimi) API access for enhancement (API mode).
+
+**Format:** `sk-...`
+
+**Used by:**
+- `skill-seekers create` / `scan` / `enhance` (enhancement, Kimi/Moonshot)
+
+**Example:**
+```bash
+export MOONSHOT_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+---
+
+### GITHUB_TOKEN
+
+**Purpose:** GitHub API authentication for higher rate limits, plus authoring community-registry submissions.
+
+**Format:** `ghp_...` (personal access token) or `github_pat_...` (fine-grained)
+
+**Used by:**
+- `skill-seekers create` (GitHub repos)
+- `skill-seekers create --config` (unified multi-source)
+- `skill-seekers scan` (local codebases)
+- `skill-seekers scan` — *required* to submit AI-generated configs to the community registry (the scan itself runs without it; the publish prompt is just skipped with a hint)
+
+**Benefits:**
+- 5000 requests/hour vs 60 for unauthenticated
+- Access to private repositories
+- Higher GraphQL API limits
+- Enables opening community-config GitHub issues from `scan`
+
+**Example:**
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+**Create token:** https://github.com/settings/tokens
+
+---
+
+## Platform Configuration
+
+### ANTHROPIC_BASE_URL
+
+**Purpose:** Custom Claude API endpoint.
+
+**Default:** `https://api.anthropic.com`
+
+**Use case:** Proxy servers, enterprise deployments, regional endpoints.
+
+**Example:**
+```bash
+export ANTHROPIC_BASE_URL=https://custom-api.example.com
+```
+
+---
+
+### OPENAI_BASE_URL
+
+**Purpose:** Custom OpenAI-compatible API endpoint for enhancement.
+
+**Default:** `https://api.openai.com/v1`
+
+**Use case:** Any OpenAI-compatible provider — OpenRouter, Groq, Cerebras, Mistral,
+NVIDIA NIM, local servers (Ollama, vLLM, LM Studio), proxies.
+
+**Example:**
+```bash
+export OPENAI_BASE_URL=https://openrouter.ai/api/v1
+```
+
+> Read automatically by the OpenAI SDK. Pair with `OPENAI_API_KEY` and `OPENAI_MODEL`.
+
+---
+
+## LLM Provider Selection
+
+The AI **enhancement** step (`create`, `scan`, `enhance`) supports multiple providers
+through one abstraction (`AgentClient` — every API enhancement call routes through it).
+The provider is chosen by the **first** API key found, in the order of the
+`API_PROVIDERS` registry in `cli/agent_client.py`: `ANTHROPIC_API_KEY` →
+`ANTHROPIC_AUTH_TOKEN` → `GOOGLE_API_KEY` → `OPENAI_API_KEY` → `MOONSHOT_API_KEY`.
+If none is set, it falls back to **LOCAL agent mode** (`--agent`, no API key
+required — uses your Claude Pro / ChatGPT Plus subscription).
+
+To force a provider when the key prefix is ambiguous (Moonshot keys also start
+with `sk-`), set `SKILL_SEEKER_PROVIDER` to `anthropic`, `google`, `openai`,
+`moonshot` (alias: `kimi`):
+
+```bash
+export SKILL_SEEKER_PROVIDER=moonshot
+```
+
+### Any OpenAI-compatible provider (OpenRouter, Groq, Cerebras, Mistral, NVIDIA NIM)
+
+```bash
+export OPENAI_API_KEY="<provider key>"
+export OPENAI_BASE_URL="https://api.groq.com/openai/v1"   # provider endpoint
+export OPENAI_MODEL="llama-3.3-70b-versatile"             # a model that provider offers
+skill-seekers create <source>
+```
+
+| Provider     | `OPENAI_BASE_URL`                     |
+|--------------|---------------------------------------|
+| OpenRouter   | `https://openrouter.ai/api/v1`        |
+| Groq         | `https://api.groq.com/openai/v1`      |
+| Cerebras     | `https://api.cerebras.ai/v1`          |
+| Mistral      | `https://api.mistral.ai/v1`           |
+| NVIDIA NIM   | `https://integrate.api.nvidia.com/v1` |
+
+> Set `OPENAI_MODEL` — the OpenAI default (`gpt-4o`) won't exist on other providers.
+> Ensure no higher-priority key (e.g. `ANTHROPIC_API_KEY`) is set, or it wins.
+
+### Subscriptions instead of API credits (LOCAL mode)
+
+```bash
+skill-seekers create <source> --agent codex    # ChatGPT Plus via Codex CLI
+skill-seekers create <source> --agent claude   # Claude Pro/Max via Claude Code
+```
+
+---
+
+## Paths and Directories
+
+### SKILL_SEEKERS_HOME
+
+**Purpose:** Base directory for Skill Seekers data.
+
+**Default:**
+- Linux/macOS: `~/.config/skill-seekers/`
+- Windows: `%APPDATA%\skill-seekers\`
+
+**Used for:**
+- Configuration files
+- Workflow presets
+- Cache data
+- Checkpoints
+
+**Example:**
+```bash
+export SKILL_SEEKERS_HOME=/opt/skill-seekers
+```
+
+---
+
+### SKILL_SEEKERS_OUTPUT
+
+**Purpose:** Default output directory for skills.
+
+**Default:** `./output/`
+
+**Used by:**
+- All scraping commands
+- Package output
+- Skill generation
+
+**Example:**
+```bash
+export SKILL_SEEKERS_OUTPUT=/var/skills/output
+```
+
+---
+
+### SKILL_SEEKERS_CONFIG_DIR
+
+**Purpose:** Directory containing preset configs.
+
+**Default:** `configs/` (relative to working directory)
+
+**Example:**
+```bash
+export SKILL_SEEKERS_CONFIG_DIR=/etc/skill-seekers/configs
+```
+
+---
+
+## Scraping Behavior
+
+### SKILL_SEEKERS_RATE_LIMIT
+
+**Purpose:** Default rate limit for HTTP requests.
+
+**Default:** `0.5` (seconds)
+
+**Unit:** Seconds between requests
+
+**Example:**
+```bash
+# More aggressive (faster)
+export SKILL_SEEKERS_RATE_LIMIT=0.2
+
+# More conservative (slower)
+export SKILL_SEEKERS_RATE_LIMIT=1.0
+```
+
+**Override:** Use `--rate-limit` flag per command.
+
+---
+
+### SKILL_SEEKERS_MAX_PAGES
+
+**Purpose:** Default maximum pages to scrape.
+
+**Default:** `500`
+
+**Example:**
+```bash
+export SKILL_SEEKERS_MAX_PAGES=1000
+```
+
+**Override:** Use `--max-pages` flag or config file.
+
+---
+
+### SKILL_SEEKERS_WORKERS
+
+**Purpose:** Default number of parallel workers.
+
+**Default:** `1`
+
+**Maximum:** `10`
+
+**Example:**
+```bash
+export SKILL_SEEKERS_WORKERS=4
+```
+
+**Override:** Use `--workers` flag.
+
+---
+
+### SKILL_SEEKERS_TIMEOUT
+
+**Purpose:** HTTP request timeout.
+
+**Default:** `30` (seconds)
+
+**Example:**
+```bash
+# For slow servers
+export SKILL_SEEKERS_TIMEOUT=60
+```
+
+---
+
+### SKILL_SEEKERS_USER_AGENT
+
+**Purpose:** Custom User-Agent header.
+
+**Default:** `Skill-Seekers/3.7.0`
+
+**Example:**
+```bash
+export SKILL_SEEKERS_USER_AGENT="MyBot/1.0 (contact@example.com)"
+```
+
+---
+
+## Enhancement Settings
+
+### SKILL_SEEKER_AGENT
+
+**Purpose:** Default local coding agent for enhancement and scan detection/generation.
+
+**Default:** `claude`
+
+**Options:** `claude`, `codex`, `copilot`, `opencode`, `kimi`, `custom`, plus IDE-mode aliases (`cursor`, `windsurf`, `cline`, `continue`)
+
+**Used by:**
+- `skill-seekers enhance`
+- `skill-seekers scan` (overridable per-invocation via `--agent`)
+
+**Example:**
+```bash
+export SKILL_SEEKER_AGENT=cursor
+```
+
+---
+
+### SKILL_SEEKER_AGENT_CMD
+
+**Purpose:** Custom CLI command template for `--agent custom` (LOCAL mode).
+
+**Used by:** `skill-seekers create` / `scan` / `enhance` when `SKILL_SEEKER_AGENT=custom`.
+
+**Example:**
+```bash
+export SKILL_SEEKER_AGENT=custom
+export SKILL_SEEKER_AGENT_CMD="my-llm-cli --prompt-file {prompt_file}"
+```
+
+---
+
+### SKILL_SEEKER_PROVIDER
+
+**Purpose:** Force the API provider when key-prefix detection is ambiguous
+(Moonshot keys also start with `sk-` and would otherwise be classified as OpenAI).
+
+**Values:** `anthropic`, `google`, `openai`, `moonshot` (alias: `kimi`)
+
+**Example:**
+```bash
+export SKILL_SEEKER_PROVIDER=moonshot
+```
+
+---
+
+### SKILL_SEEKER_MODEL
+
+**Purpose:** Global model override for API-mode enhancement (wins over all
+per-provider model vars below).
+
+**Example:**
+```bash
+export SKILL_SEEKER_MODEL=llama-3.3-70b-versatile
+```
+
+---
+
+### Per-provider model overrides
+
+Used only when `SKILL_SEEKER_MODEL` is unset. Each falls back to a per-provider default.
+
+| Variable          | Provider           | Default (if unset)          |
+|-------------------|--------------------|-----------------------------|
+| `ANTHROPIC_MODEL` | Anthropic          | `claude-sonnet-4-20250514`  |
+| `OPENAI_MODEL`    | OpenAI/-compatible | `gpt-4o`                    |
+| `GOOGLE_MODEL`    | Gemini             | `gemini-2.0-flash`          |
+| `MOONSHOT_MODEL`  | Moonshot/Kimi      | `moonshot-v1-auto`          |
+
+```bash
+export OPENAI_MODEL=llama-3.3-70b-versatile
+```
+
+---
+
+### SKILL_SEEKER_ENHANCE_TIMEOUT
+
+**Purpose:** Timeout for AI enhancement operations (seconds).
+
+**Default:** `2700` (45 minutes)
+
+**Special values:** `unlimited`, `none`, or `0` map to a 24-hour ceiling.
+
+**Example:**
+```bash
+# For large skills
+export SKILL_SEEKER_ENHANCE_TIMEOUT=3600
+
+# No practical limit
+export SKILL_SEEKER_ENHANCE_TIMEOUT=unlimited
+```
+
+---
+
+### SKILL_SEEKER_ENHANCE_ACTIVE
+
+**Purpose:** Recursion guard for LOCAL agent enhancement. Skill Seekers sets
+this to `1` in the environment of every local agent it spawns (all spawn
+paths); when it is already set, LOCAL enhancement refuses to spawn a nested
+agent. You normally never set this yourself — only when wrapping Skill Seekers
+inside another agent and you want enhancement suppressed.
+
+**Example:**
+```bash
+export SKILL_SEEKER_ENHANCE_ACTIVE=1   # suppress nested local-agent spawns
+```
+
+---
+
+## GitHub Configuration
+
+### GITHUB_API_URL
+
+**Purpose:** Custom GitHub API endpoint.
+
+**Default:** `https://api.github.com`
+
+**Use case:** GitHub Enterprise Server.
+
+**Example:**
+```bash
+export GITHUB_API_URL=https://github.company.com/api/v3
+```
+
+---
+
+### GITHUB_ENTERPRISE_TOKEN
+
+**Purpose:** Separate token for GitHub Enterprise.
+
+**Use case:** Different tokens for github.com vs enterprise.
+
+**Example:**
+```bash
+export GITHUB_TOKEN=ghp_...           # github.com
+export GITHUB_ENTERPRISE_TOKEN=...   # enterprise
+```
+
+---
+
+## Vector Database Settings
+
+### CHROMA_URL
+
+**Purpose:** ChromaDB server URL.
+
+**Default:** `http://localhost:8000`
+
+**Used by:**
+- `skill-seekers upload --target chroma`
+- `export_to_chroma` MCP tool
+
+**Example:**
+```bash
+export CHROMA_URL=http://chroma.example.com:8000
+```
+
+---
+
+### CHROMA_PERSIST_DIRECTORY
+
+**Purpose:** Local directory for ChromaDB persistence.
+
+**Default:** `./chroma_db/`
+
+**Example:**
+```bash
+export CHROMA_PERSIST_DIRECTORY=/var/lib/chroma
+```
+
+---
+
+### WEAVIATE_URL
+
+**Purpose:** Weaviate server URL.
+
+**Default:** `http://localhost:8080`
+
+**Used by:**
+- `skill-seekers upload --target weaviate`
+- `export_to_weaviate` MCP tool
+
+**Example:**
+```bash
+export WEAVIATE_URL=https://weaviate.example.com
+```
+
+---
+
+### WEAVIATE_API_KEY
+
+**Purpose:** Weaviate API key for authentication.
+
+**Used by:**
+- Weaviate Cloud
+- Authenticated Weaviate instances
+
+**Example:**
+```bash
+export WEAVIATE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+---
+
+### QDRANT_URL
+
+**Purpose:** Qdrant server URL.
+
+**Default:** `http://localhost:6333`
+
+**Example:**
+```bash
+export QDRANT_URL=http://qdrant.example.com:6333
+```
+
+---
+
+### QDRANT_API_KEY
+
+**Purpose:** Qdrant API key for authentication.
+
+**Example:**
+```bash
+export QDRANT_API_KEY=xxxxxxxxxxxxxxxx
+```
+
+---
+
+## Debug and Development
+
+### SKILL_SEEKERS_DEBUG
+
+**Purpose:** Enable debug logging.
+
+**Values:** `1`, `true`, `yes`
+
+**Equivalent to:** `--verbose` flag
+
+**Example:**
+```bash
+export SKILL_SEEKERS_DEBUG=1
+```
+
+---
+
+### SKILL_SEEKERS_LOG_LEVEL
+
+**Purpose:** Set logging level.
+
+**Default:** `INFO`
+
+**Options:** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+**Example:**
+```bash
+export SKILL_SEEKERS_LOG_LEVEL=DEBUG
+```
+
+---
+
+### SKILL_SEEKERS_LOG_FILE
+
+**Purpose:** Log to file instead of stdout.
+
+**Example:**
+```bash
+export SKILL_SEEKERS_LOG_FILE=/var/log/skill-seekers.log
+```
+
+---
+
+### SKILL_SEEKERS_CACHE_DIR
+
+**Purpose:** Custom cache directory.
+
+**Default:** `~/.cache/skill-seekers/`
+
+**Example:**
+```bash
+export SKILL_SEEKERS_CACHE_DIR=/tmp/skill-seekers-cache
+```
+
+---
+
+### SKILL_SEEKERS_NO_CACHE
+
+**Purpose:** Disable caching.
+
+**Values:** `1`, `true`, `yes`
+
+**Example:**
+```bash
+export SKILL_SEEKERS_NO_CACHE=1
+```
+
+---
+
+## MCP Server Settings
+
+### MCP_TRANSPORT
+
+**Purpose:** Default MCP transport mode.
+
+**Default:** `stdio`
+
+**Options:** `stdio`, `http`
+
+**Example:**
+```bash
+export MCP_TRANSPORT=http
+```
+
+**Override:** Use `--transport` flag.
+
+---
+
+### MCP_PORT
+
+**Purpose:** Default MCP HTTP port.
+
+**Default:** `8765`
+
+**Example:**
+```bash
+export MCP_PORT=8080
+```
+
+**Override:** Use `--port` flag.
+
+---
+
+### MCP_HOST
+
+**Purpose:** Default MCP HTTP host.
+
+**Default:** `127.0.0.1`
+
+**Example:**
+```bash
+export MCP_HOST=0.0.0.0
+```
+
+**Override:** Use `--host` flag.
+
+---
+
+## Examples
+
+### Development Environment
+
+```bash
+# Debug mode
+export SKILL_SEEKERS_DEBUG=1
+export SKILL_SEEKERS_LOG_LEVEL=DEBUG
+
+# Custom paths
+export SKILL_SEEKERS_HOME=./.skill-seekers
+export SKILL_SEEKERS_OUTPUT=./output
+
+# Faster scraping for testing
+export SKILL_SEEKERS_RATE_LIMIT=0.1
+export SKILL_SEEKERS_MAX_PAGES=50
+```
+
+### Production Environment
+
+```bash
+# API keys
+export ANTHROPIC_API_KEY=sk-ant-...
+export GITHUB_TOKEN=ghp_...
+
+# Custom output directory
+export SKILL_SEEKERS_OUTPUT=/var/www/skills
+
+# Conservative scraping
+export SKILL_SEEKERS_RATE_LIMIT=1.0
+export SKILL_SEEKERS_WORKERS=2
+
+# Logging
+export SKILL_SEEKERS_LOG_FILE=/var/log/skill-seekers.log
+export SKILL_SEEKERS_LOG_LEVEL=WARNING
+```
+
+### CI/CD Environment
+
+```bash
+# Non-interactive
+export SKILL_SEEKERS_LOG_LEVEL=ERROR
+
+# API keys from secrets
+export ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY_SECRET}
+export GITHUB_TOKEN=${GITHUB_TOKEN_SECRET}
+
+# Fresh runs (no cache)
+export SKILL_SEEKERS_NO_CACHE=1
+```
+
+### Multi-Platform Setup
+
+```bash
+# All API keys
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=AIza...
+export OPENAI_API_KEY=sk-...
+export GITHUB_TOKEN=ghp_...
+
+# Vector databases
+export CHROMA_URL=http://localhost:8000
+export WEAVIATE_URL=http://localhost:8080
+export WEAVIATE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+---
+
+## Configuration File
+
+Environment variables can also be set in a `.env` file:
+
+```bash
+# .env file
+ANTHROPIC_API_KEY=sk-ant-...
+GITHUB_TOKEN=ghp_...
+SKILL_SEEKERS_OUTPUT=./output
+SKILL_SEEKERS_RATE_LIMIT=0.5
+```
+
+Load with:
+```bash
+# Automatically loaded if python-dotenv is installed
+# Or manually:
+export $(cat .env | xargs)
+```
+
+---
+
+## Priority Order
+
+Settings are applied in this order (later overrides earlier):
+
+1. Default values
+2. Environment variables
+3. Configuration file
+4. Command-line flags
+
+Example:
+```bash
+# Default: rate_limit = 0.5
+export SKILL_SEEKERS_RATE_LIMIT=1.0  # Env var overrides default
+# Config file: rate_limit = 0.2      # Config overrides env
+skill-seekers create --rate-limit 2.0  # Flag overrides all
+```
+
+---
+
+## Security Best Practices
+
+### Never commit API keys
+
+```bash
+# Add to .gitignore
+echo ".env" >> .gitignore
+echo "*.key" >> .gitignore
+```
+
+### Use secret management
+
+```bash
+# macOS Keychain
+export ANTHROPIC_API_KEY=$(security find-generic-password -s "anthropic-api" -w)
+
+# Linux Secret Service (with secret-tool)
+export ANTHROPIC_API_KEY=$(secret-tool lookup service anthropic)
+
+# 1Password CLI
+export ANTHROPIC_API_KEY=$(op read "op://vault/anthropic/credential")
+```
+
+### File permissions
+
+```bash
+# Restrict .env file
+chmod 600 .env
+```
+
+---
+
+## Troubleshooting
+
+### Variable not recognized
+
+```bash
+# Check if set
+echo $ANTHROPIC_API_KEY
+
+# Check in Python
+python -c "import os; print(os.getenv('ANTHROPIC_API_KEY'))"
+```
+
+### Priority issues
+
+```bash
+# See effective configuration
+skill-seekers config --show
+```
+
+### Path expansion
+
+```bash
+# Use full path or expand tilde
+export SKILL_SEEKERS_HOME=$HOME/.skill-seekers
+# NOT: ~/.skill-seekers (may not expand in all shells)
+```
+
+---
+
+## See Also
+
+- [CLI Reference](CLI_REFERENCE.md) - Command reference
+- [Config Format](CONFIG_FORMAT.md) - JSON configuration
+
+---
+
+*For platform-specific setup, see [Installation Guide](../getting-started/01-installation.md)*

docs/reference/FEATURE_MATRIX.md

@@ -0,0 +1,382 @@
+# Skill Seekers Feature Matrix
+
+Complete feature support across all platforms and skill modes.
+
+## Platform Support
+
+| Platform | Package Format | Upload | Enhancement | API Key Required |
+|----------|---------------|--------|-------------|------------------|
+| **Claude AI** | ZIP | ✅ Anthropic API | ✅ Sonnet 4 | ANTHROPIC_API_KEY |
+| **Google Gemini** | tar.gz | ✅ Files API | ✅ Gemini 2.0 | GOOGLE_API_KEY |
+| **OpenAI ChatGPT** | ZIP | ✅ Assistants API | ✅ GPT-4o | OPENAI_API_KEY |
+| **MiniMax** | ZIP | ❌ Manual | ❌ None | None |
+| **OpenCode** | ZIP | ❌ Manual | ❌ None | None |
+| **Kimi** | ZIP | ❌ Manual | ❌ None | None |
+| **DeepSeek** | ZIP | ❌ Manual | ❌ None | None |
+| **Qwen** | ZIP | ❌ Manual | ❌ None | None |
+| **OpenRouter** | ZIP | ❌ Manual | ❌ None | None |
+| **Together AI** | ZIP | ❌ Manual | ❌ None | None |
+| **Fireworks AI** | ZIP | ❌ Manual | ❌ None | None |
+| **IBM Bob** | Directory | ❌ Manual | ❌ None | None |
+| **LangChain** | JSON | ❌ Manual | ❌ None | None |
+| **LlamaIndex** | JSON | ❌ Manual | ❌ None | None |
+| **Haystack** | JSON | ❌ Manual | ❌ None | None |
+| **Pinecone** | Vectors | ❌ Manual | ❌ None | PINECONE_API_KEY |
+| **Weaviate** | Vectors | ❌ Manual | ❌ None | None |
+| **Chroma** | Vectors | ❌ Manual | ❌ None | None |
+| **FAISS** | Index | ❌ Manual | ❌ None | None |
+| **Qdrant** | Vectors | ❌ Manual | ❌ None | None |
+| **Generic Markdown** | ZIP | ❌ Manual | ❌ None | None |
+
+## Skill Mode Support
+
+| Mode | Description | Platforms | CLI Command | `create` Detection |
+|------|-------------|-----------|-------------|-------------------|
+| **Documentation** | Scrape HTML docs | All 21 | `scrape` | `https://...` URLs |
+| **GitHub** | Analyze repositories | All 21 | `github` | `owner/repo` or github.com URLs |
+| **PDF** | Extract from PDFs | All 21 | `pdf` | `.pdf` extension |
+| **Word** | Extract from DOCX | All 21 | `word` | `.docx` extension |
+| **EPUB** | Extract from EPUB | All 21 | `epub` | `.epub` extension |
+| **Video** | Video transcription | All 21 | `video` | YouTube/Vimeo URLs, video extensions |
+| **Local Repo** | Local codebase analysis | All 21 | `analyze` | Directory paths |
+| **Jupyter** | Extract from notebooks | All 21 | `jupyter` | `.ipynb` extension |
+| **HTML** | Extract local HTML files | All 21 | `html` | `.html`/`.htm` extension |
+| **OpenAPI** | Extract API specs | All 21 | `openapi` | `.yaml`/`.yml` with OpenAPI content |
+| **AsciiDoc** | Extract AsciiDoc files | All 21 | `asciidoc` | `.adoc`/`.asciidoc` extension |
+| **PowerPoint** | Extract from PPTX | All 21 | `pptx` | `.pptx` extension |
+| **RSS/Atom** | Extract from feeds | All 21 | `rss` | `.rss`/`.atom` extension |
+| **Man Pages** | Extract man pages | All 21 | `manpage` | `.1`-`.8`/`.man` extension |
+| **Confluence** | Extract from Confluence | All 21 | `confluence` | API or export directory |
+| **Notion** | Extract from Notion | All 21 | `notion` | API or export directory |
+| **Chat** | Extract Slack/Discord | All 21 | `chat` | Export directory or API |
+| **Unified** | Multi-source combination | All 21 | `unified` | N/A (config-driven) |
+
+## CLI Command Support
+
+| Command | Platforms | Skill Modes | Multi-Platform Flag | Optional Deps |
+|---------|-----------|-------------|---------------------|---------------|
+| `scrape` | All | Docs only | No (output is universal) | None |
+| `github` | All | GitHub only | No (output is universal) | None |
+| `pdf` | All | PDF only | No (output is universal) | `[pdf]` |
+| `word` | All | Word only | No (output is universal) | `[word]` |
+| `epub` | All | EPUB only | No (output is universal) | `[epub]` |
+| `video` | All | Video only | No (output is universal) | `[video]` |
+| `analyze` | All | Local only | No (output is universal) | None |
+| `jupyter` | All | Jupyter only | No (output is universal) | `[jupyter]` |
+| `html` | All | HTML only | No (output is universal) | None |
+| `openapi` | All | OpenAPI only | No (output is universal) | `[openapi]` |
+| `asciidoc` | All | AsciiDoc only | No (output is universal) | `[asciidoc]` |
+| `pptx` | All | PPTX only | No (output is universal) | `[pptx]` |
+| `rss` | All | RSS only | No (output is universal) | `[rss]` |
+| `manpage` | All | Man pages only | No (output is universal) | None |
+| `confluence` | All | Confluence only | No (output is universal) | `[confluence]` |
+| `notion` | All | Notion only | No (output is universal) | `[notion]` |
+| `chat` | All | Chat only | No (output is universal) | `[chat]` |
+| `unified` | All | Unified only | No (output is universal) | Varies by source |
+| `scan` | All | Project bootstrap | No (output is universal) | None (uses existing `AgentClient`) |
+| `enhance` | Claude, Gemini, OpenAI | All | ✅ `--target` | None |
+| `package` | All | All | ✅ `--target` | None |
+| `upload` | Claude, Gemini, OpenAI | All | ✅ `--target` | None |
+| `estimate` | All | Docs only | No (estimation is universal) | None |
+| `install` | All | All | ✅ `--target` | None |
+| `install-agent` | All | All | No (agent-specific paths) | None |
+
+## MCP Tool Support
+
+| Tool | Platforms | Skill Modes | Multi-Platform Param |
+|------|-----------|-------------|----------------------|
+| **Config Tools** |
+| `generate_config` | All | All | No (creates generic JSON) |
+| `list_configs` | All | All | No |
+| `validate_config` | All | All | No |
+| `fetch_config` | All | All | No |
+| **Scraping Tools** |
+| `estimate_pages` | All | Docs only | No |
+| `scrape_docs` | All | Docs + Unified | No (output is universal) |
+| `scrape_github` | All | GitHub only | No (output is universal) |
+| `scrape_pdf` | All | PDF only | No (output is universal) |
+| `scrape_generic` | All | 10 new types | No (output is universal) |
+| **Packaging Tools** |
+| `package_skill` | All | All | ✅ `target` parameter |
+| `upload_skill` | Claude, Gemini, OpenAI | All | ✅ `target` parameter |
+| `enhance_skill` | Claude, Gemini, OpenAI | All | ✅ `target` parameter |
+| `install_skill` | All | All | ✅ `target` parameter |
+| **Splitting Tools** |
+| `split_config` | All | Docs + Unified | No |
+| `generate_router` | All | Docs only | No |
+
+## Feature Comparison by Platform
+
+### Claude AI (Default)
+- **Format:** YAML frontmatter + markdown
+- **Package:** ZIP with SKILL.md, references/, scripts/, assets/
+- **Upload:** POST to https://api.anthropic.com/v1/skills
+- **Enhancement:** Claude Sonnet 4 (local or API)
+- **Unique Features:** MCP integration, Skills API
+- **Limitations:** No vector store, no file search
+
+### Google Gemini
+- **Format:** Plain markdown (no frontmatter)
+- **Package:** tar.gz with system_instructions.md, references/, metadata
+- **Upload:** Google Files API
+- **Enhancement:** Gemini 2.0 Flash
+- **Unique Features:** Grounding support, long context (1M tokens)
+- **Limitations:** tar.gz format only
+
+### OpenAI ChatGPT
+- **Format:** Assistant instructions (plain text)
+- **Package:** ZIP with assistant_instructions.txt, vector_store_files/, metadata
+- **Upload:** Assistants API + Vector Store creation
+- **Enhancement:** GPT-4o
+- **Unique Features:** Vector store, file_search tool, semantic search
+- **Limitations:** Requires Assistants API structure
+
+### Generic Markdown
+- **Format:** Pure markdown (universal)
+- **Package:** ZIP with README.md, DOCUMENTATION.md, references/
+- **Upload:** None (manual distribution)
+- **Enhancement:** None
+- **Unique Features:** Works with any LLM, no API dependencies
+- **Limitations:** No upload, no enhancement
+
+## Workflow Coverage
+
+### Single-Source Workflow
+```
+Config → Scrape → Build → [Enhance] → Package --target X → [Upload --target X]
+```
+**Platforms:** All 21
+**Modes:** Docs, GitHub, PDF
+
+### Unified Multi-Source Workflow
+```
+Config → Scrape All → Detect Conflicts → Merge → Build → [Enhance] → Package --target X → [Upload --target X]
+```
+**Platforms:** All 21
+**Modes:** Unified only
+
+### Complete Installation Workflow
+```
+install --target X → Fetch → Scrape → Enhance → Package → Upload
+```
+**Platforms:** All 21
+**Modes:** All (via config type detection)
+
+## API Key Requirements
+
+| Platform | Environment Variable | Key Format | Required For |
+|----------|---------------------|------------|--------------|
+| Claude | `ANTHROPIC_API_KEY` | `sk-ant-*` | Upload, API Enhancement |
+| Gemini | `GOOGLE_API_KEY` | `AIza*` | Upload, API Enhancement |
+| OpenAI | `OPENAI_API_KEY` | `sk-*` | Upload, API Enhancement |
+| Markdown | None | N/A | Nothing |
+
+**Note:** Local enhancement (Claude Code Max) requires no API key for any platform.
+
+## Installation Options
+
+```bash
+# Core package (Claude only)
+pip install skill-seekers
+
+# With Gemini support
+pip install skill-seekers[gemini]
+
+# With OpenAI support
+pip install skill-seekers[openai]
+
+# With all platforms
+pip install skill-seekers[all-llms]
+```
+
+## Examples
+
+### Package for Multiple Platforms (Same Skill)
+```bash
+# Scrape once (platform-agnostic)
+skill-seekers create --config configs/react.json
+
+# Package for all platforms
+skill-seekers package output/react/ --target claude
+skill-seekers package output/react/ --target gemini
+skill-seekers package output/react/ --target openai
+skill-seekers package output/react/ --target markdown
+
+# Result:
+# - react.zip (Claude)
+# - react-gemini.tar.gz (Gemini)
+# - react-openai.zip (OpenAI)
+# - react-markdown.zip (Universal)
+```
+
+### Upload to Multiple Platforms
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=AIzaSy...
+export OPENAI_API_KEY=sk-proj-...
+
+skill-seekers upload react.zip --target claude
+skill-seekers upload react-gemini.tar.gz --target gemini
+skill-seekers upload react-openai.zip --target openai
+```
+
+### Use MCP Tools for Any Platform
+```python
+# In Claude Code or any MCP client
+
+# Package for Gemini
+package_skill(skill_dir="output/react", target="gemini")
+
+# Upload to OpenAI
+upload_skill(skill_zip="output/react-openai.zip", target="openai")
+
+# Enhance with Gemini
+enhance_skill(skill_dir="output/react", target="gemini", mode="api")
+```
+
+### Complete Workflow with Different Platforms
+```bash
+# Install React skill for Claude (default)
+skill-seekers install --config react
+
+# Install Django skill for Gemini
+skill-seekers install --config django --target gemini
+
+# Install FastAPI skill for OpenAI
+skill-seekers install --config fastapi --target openai
+
+# Install Vue skill as generic markdown
+skill-seekers install --config vue --target markdown
+```
+
+### Split Unified Config by Source
+```bash
+# Split multi-source config into separate configs
+python -m skill_seekers.cli.split_config configs/react_unified.json --strategy source
+
+# Creates:
+# - react-documentation.json (docs only)
+# - react-github.json (GitHub only)
+
+# Then scrape each separately
+skill-seekers create --config react-documentation.json
+skill-seekers create --config react-github.json
+
+# Or scrape in parallel for speed
+skill-seekers create --config react-documentation.json &
+skill-seekers create --config react-github.json &
+wait
+```
+
+## Verification Checklist
+
+Before release, verify all combinations:
+
+### CLI Commands × Platforms
+- [ ] scrape → package claude → upload claude
+- [ ] scrape → package gemini → upload gemini
+- [ ] scrape → package openai → upload openai
+- [ ] scrape → package markdown
+- [ ] github → package (all platforms)
+- [ ] pdf → package (all platforms)
+- [ ] unified → package (all platforms)
+- [ ] enhance claude
+- [ ] enhance gemini
+- [ ] enhance openai
+
+### MCP Tools × Platforms
+- [ ] package_skill target=claude
+- [ ] package_skill target=gemini
+- [ ] package_skill target=openai
+- [ ] package_skill target=markdown
+- [ ] upload_skill target=claude
+- [ ] upload_skill target=gemini
+- [ ] upload_skill target=openai
+- [ ] enhance_skill target=claude
+- [ ] enhance_skill target=gemini
+- [ ] enhance_skill target=openai
+- [ ] install_skill target=claude
+- [ ] install_skill target=gemini
+- [ ] install_skill target=openai
+
+### Skill Modes × Platforms
+- [ ] Docs → Claude
+- [ ] Docs → Gemini
+- [ ] Docs → OpenAI
+- [ ] Docs → Markdown
+- [ ] GitHub → All platforms
+- [ ] PDF → All platforms
+- [ ] Word → All platforms
+- [ ] EPUB → All platforms
+- [ ] Video → All platforms
+- [ ] Local Repo → All platforms
+- [ ] Jupyter → All platforms
+- [ ] HTML → All platforms
+- [ ] OpenAPI → All platforms
+- [ ] AsciiDoc → All platforms
+- [ ] PPTX → All platforms
+- [ ] RSS → All platforms
+- [ ] Man Pages → All platforms
+- [ ] Confluence → All platforms
+- [ ] Notion → All platforms
+- [ ] Chat → All platforms
+- [ ] Unified → All platforms
+
+## Platform-Specific Notes
+
+### Claude AI
+- **Best for:** General-purpose skills, MCP integration
+- **When to use:** Default choice, best MCP support
+- **File size limit:** 25 MB per skill package
+
+### Google Gemini
+- **Best for:** Large context skills, grounding support
+- **When to use:** Need long context (1M tokens), grounding features
+- **File size limit:** 100 MB per upload
+
+### OpenAI ChatGPT
+- **Best for:** Vector search, semantic retrieval
+- **When to use:** Need semantic search across documentation
+- **File size limit:** 512 MB per vector store
+
+### Generic Markdown
+- **Best for:** Universal compatibility, no API dependencies
+- **When to use:** Using non-Claude/Gemini/OpenAI LLMs, offline use
+- **Distribution:** Manual - share ZIP file directly
+
+## Frequently Asked Questions
+
+**Q: Can I package once and upload to multiple platforms?**
+A: No. Each platform requires a platform-specific package format. You must:
+1. Scrape once (universal)
+2. Package separately for each platform (`--target` flag)
+3. Upload each platform-specific package
+
+**Q: Do I need to scrape separately for each platform?**
+A: No! Scraping is platform-agnostic. Scrape once, then package for multiple platforms.
+
+**Q: Which platform should I choose?**
+A:
+- **Claude:** Best default choice, excellent MCP integration
+- **Gemini:** Choose if you need long context (1M tokens) or grounding
+- **OpenAI:** Choose if you need vector search and semantic retrieval
+- **MiniMax/Kimi/DeepSeek/Qwen:** Choose for Chinese LLM ecosystem compatibility
+- **OpenRouter/Together/Fireworks:** Choose for multi-model routing or open-source model access
+- **Markdown:** Choose for universal compatibility or offline use
+
+**Q: Can I enhance a skill for different platforms?**
+A: Yes! Enhancement adds platform-specific formatting:
+- Claude: YAML frontmatter + markdown
+- Gemini: Plain markdown with system instructions
+- OpenAI: Plain text assistant instructions
+
+**Q: Do all skill modes work with all platforms?**
+A: Yes! All 18 source types work with all 21 platforms (Claude, Gemini, OpenAI, MiniMax, OpenCode, Kimi, DeepSeek, Qwen, OpenRouter, Together AI, Fireworks AI, IBM Bob, LangChain, LlamaIndex, Haystack, Pinecone, Weaviate, Chroma, FAISS, Qdrant, and Markdown).
+
+## See Also
+
+- **[README.md](../README.md)** - Complete user documentation
+- **[UNIFIED_SCRAPING.md](UNIFIED_SCRAPING.md)** - Multi-source scraping guide
+- **[ENHANCEMENT.md](ENHANCEMENT.md)** - AI enhancement guide
+- **[UPLOAD_GUIDE.md](UPLOAD_GUIDE.md)** - Upload instructions
+- **[MCP_SETUP.md](MCP_SETUP.md)** - MCP server setup

docs/reference/GIT_CONFIG_SOURCES.md

@@ -0,0 +1,921 @@
+# Git-Based Config Sources - Complete Guide
+
+**Version:** v3.6.0
+**Feature:** A1.9 - Multi-Source Git Repository Support
+**Last Updated:** December 21, 2025
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [MCP Tools Reference](#mcp-tools-reference)
+- [Authentication](#authentication)
+- [Use Cases](#use-cases)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Topics](#advanced-topics)
+
+---
+
+## Overview
+
+### What is this feature?
+
+Git-based config sources allow you to fetch config files from **private/team git repositories** in addition to the public API. This unlocks:
+
+- 🔐 **Private configs** - Company/internal documentation
+- 👥 **Team collaboration** - Share configs across 3-5 person teams
+- 🏢 **Enterprise scale** - Support 500+ developers
+- 📦 **Custom collections** - Curated config repositories
+- 🌐 **Decentralized** - Like npm (public + private registries)
+
+### How it works
+
+```
+User → fetch_config(source="team", config_name="react-custom")
+    ↓
+SourceManager (~/.skill-seekers/sources.json)
+    ↓
+GitConfigRepo (clone/pull with GitPython)
+    ↓
+Local cache (~/.skill-seekers/cache/team/)
+    ↓
+Config JSON returned
+```
+
+### Three modes
+
+1. **API Mode** (existing, unchanged)
+   - `fetch_config(config_name="react")`
+   - Fetches from api.skillseekersweb.com
+
+2. **Source Mode** (NEW - recommended)
+   - `fetch_config(source="team", config_name="react-custom")`
+   - Uses registered git source
+
+3. **Git URL Mode** (NEW - one-time)
+   - `fetch_config(git_url="https://...", config_name="react-custom")`
+   - Direct clone without registration
+
+---
+
+## Quick Start
+
+### 1. Set up authentication
+
+```bash
+# GitHub
+export GITHUB_TOKEN=ghp_your_token_here
+
+# GitLab
+export GITLAB_TOKEN=glpat_your_token_here
+
+# Bitbucket
+export BITBUCKET_TOKEN=your_token_here
+```
+
+### 2. Register a source
+
+Using MCP tools (recommended):
+
+```python
+add_config_source(
+    name="team",
+    git_url="https://github.com/mycompany/skill-configs.git",
+    source_type="github",  # Optional, auto-detected
+    token_env="GITHUB_TOKEN",  # Optional, auto-detected
+    branch="main",  # Optional, default: "main"
+    priority=100  # Optional, lower = higher priority
+)
+```
+
+### 3. Fetch configs
+
+```python
+# From registered source
+fetch_config(source="team", config_name="react-custom")
+
+# List available sources
+list_config_sources()
+
+# Remove when done
+remove_config_source(name="team")
+```
+
+### 4. Quick test with example repository
+
+```bash
+cd /path/to/Skill_Seekers
+
+# Run E2E test
+python3 configs/example-team/test_e2e.py
+
+# Or test manually
+add_config_source(
+    name="example",
+    git_url="file://$(pwd)/configs/example-team",
+    branch="master"
+)
+
+fetch_config(source="example", config_name="react-custom")
+```
+
+---
+
+## Architecture
+
+### Storage Locations
+
+**Sources Registry:**
+```
+~/.skill-seekers/sources.json
+```
+
+Example content:
+```json
+{
+  "version": "1.0",
+  "sources": [
+    {
+      "name": "team",
+      "git_url": "https://github.com/myorg/configs.git",
+      "type": "github",
+      "token_env": "GITHUB_TOKEN",
+      "branch": "main",
+      "enabled": true,
+      "priority": 1,
+      "added_at": "2025-12-21T10:00:00Z",
+      "updated_at": "2025-12-21T10:00:00Z"
+    }
+  ]
+}
+```
+
+**Cache Directory:**
+```
+$SKILL_SEEKERS_CACHE_DIR  (default: ~/.skill-seekers/cache/)
+```
+
+Structure:
+```
+~/.skill-seekers/
+├── sources.json       # Source registry
+└── cache/             # Git clones
+    ├── team/          # One directory per source
+    │   ├── .git/
+    │   ├── react-custom.json
+    │   └── vue-internal.json
+    └── company/
+        ├── .git/
+        └── internal-api.json
+```
+
+### Git Strategy
+
+- **Shallow clone**: `git clone --depth 1 --single-branch`
+  - 10-50x faster
+  - Minimal disk space
+  - No history, just latest commit
+
+- **Auto-pull**: Updates cache automatically
+  - Checks for changes on each fetch
+  - Use `refresh=true` to force re-clone
+
+- **Config discovery**: Recursively scans for `*.json` files
+  - No hardcoded paths
+  - Flexible repository structure
+  - Excludes `.git` directory
+
+---
+
+## MCP Tools Reference
+
+### add_config_source
+
+Register a git repository as a config source.
+
+**Parameters:**
+- `name` (required): Source identifier (lowercase, alphanumeric, hyphens/underscores)
+- `git_url` (required): Git repository URL (HTTPS or SSH)
+- `source_type` (optional): "github", "gitlab", "gitea", "bitbucket", "custom" (auto-detected from URL)
+- `token_env` (optional): Environment variable name for token (auto-detected from type)
+- `branch` (optional): Git branch (default: "main")
+- `priority` (optional): Priority number (default: 100, lower = higher priority)
+- `enabled` (optional): Whether source is active (default: true)
+
+**Returns:**
+- Source details including registration timestamp
+
+**Examples:**
+
+```python
+# Minimal (auto-detects everything)
+add_config_source(
+    name="team",
+    git_url="https://github.com/myorg/configs.git"
+)
+
+# Full parameters
+add_config_source(
+    name="company",
+    git_url="https://gitlab.company.com/platform/configs.git",
+    source_type="gitlab",
+    token_env="GITLAB_COMPANY_TOKEN",
+    branch="develop",
+    priority=1,
+    enabled=true
+)
+
+# SSH URL (auto-converts to HTTPS with token)
+add_config_source(
+    name="team",
+    git_url="git@github.com:myorg/configs.git",
+    token_env="GITHUB_TOKEN"
+)
+```
+
+### list_config_sources
+
+List all registered config sources.
+
+**Parameters:**
+- `enabled_only` (optional): Only show enabled sources (default: false)
+
+**Returns:**
+- List of sources sorted by priority
+
+**Example:**
+
+```python
+# List all sources
+list_config_sources()
+
+# List only enabled sources
+list_config_sources(enabled_only=true)
+```
+
+**Output:**
+```
+📋 Config Sources (2 total)
+
+✓ **team**
+  📁 https://github.com/myorg/configs.git
+  🔖 Type: github | 🌿 Branch: main
+  🔑 Token: GITHUB_TOKEN | ⚡ Priority: 1
+  🕒 Added: 2025-12-21 10:00:00
+
+✓ **company**
+  📁 https://gitlab.company.com/configs.git
+  🔖 Type: gitlab | 🌿 Branch: develop
+  🔑 Token: GITLAB_TOKEN | ⚡ Priority: 2
+  🕒 Added: 2025-12-21 11:00:00
+```
+
+### remove_config_source
+
+Remove a registered config source.
+
+**Parameters:**
+- `name` (required): Source identifier
+
+**Returns:**
+- Success/failure message
+
+**Note:** Does NOT delete cached git repository data. To free disk space, manually delete `~/.skill-seekers/cache/{source_name}/`
+
+**Example:**
+
+```python
+remove_config_source(name="team")
+```
+
+### fetch_config
+
+Fetch config from API, git URL, or named source.
+
+**Mode 1: Named Source (highest priority)**
+
+```python
+fetch_config(
+    source="team",  # Use registered source
+    config_name="react-custom",
+    destination="configs/",  # Optional
+    branch="main",  # Optional, overrides source default
+    refresh=false  # Optional, force re-clone
+)
+```
+
+**Mode 2: Direct Git URL**
+
+```python
+fetch_config(
+    git_url="https://github.com/myorg/configs.git",
+    config_name="react-custom",
+    branch="main",  # Optional
+    token="ghp_token",  # Optional, prefer env vars
+    destination="configs/",  # Optional
+    refresh=false  # Optional
+)
+```
+
+**Mode 3: API (existing, unchanged)**
+
+```python
+fetch_config(
+    config_name="react",
+    destination="configs/"  # Optional
+)
+
+# Or list available
+fetch_config(list_available=true)
+```
+
+---
+
+## Authentication
+
+### Environment Variables Only
+
+Tokens are **ONLY** stored in environment variables. This is:
+- ✅ **Secure** - Not in files, not in git
+- ✅ **Standard** - Same as GitHub CLI, Docker, etc.
+- ✅ **Temporary** - Cleared on logout
+- ✅ **Flexible** - Different tokens for different services
+
+### Creating Tokens
+
+**GitHub:**
+1. Go to https://github.com/settings/tokens
+2. Generate new token (classic)
+3. Select scopes: `repo` (for private repos)
+4. Copy token: `ghp_xxxxxxxxxxxxx`
+5. Export: `export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx`
+
+**GitLab:**
+1. Go to https://gitlab.com/-/profile/personal_access_tokens
+2. Create token with `read_repository` scope
+3. Copy token: `glpat-xxxxxxxxxxxxx`
+4. Export: `export GITLAB_TOKEN=glpat-xxxxxxxxxxxxx`
+
+**Bitbucket:**
+1. Go to https://bitbucket.org/account/settings/app-passwords/
+2. Create app password with `Repositories: Read` permission
+3. Copy password
+4. Export: `export BITBUCKET_TOKEN=your_password`
+
+### Persistent Tokens
+
+Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+# GitHub token
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+
+# GitLab token
+export GITLAB_TOKEN=glpat-xxxxxxxxxxxxx
+
+# Company GitLab (separate token)
+export GITLAB_COMPANY_TOKEN=glpat-yyyyyyyyyyyyy
+```
+
+Then: `source ~/.bashrc`
+
+### Token Injection
+
+GitConfigRepo automatically:
+1. Converts SSH URLs to HTTPS
+2. Injects token into URL
+3. Uses token for authentication
+
+**Example:**
+- Input: `git@github.com:myorg/repo.git` + token `ghp_xxx`
+- Output: `https://ghp_xxx@github.com/myorg/repo.git`
+
+---
+
+## Use Cases
+
+### Small Team (3-5 people)
+
+**Scenario:** Frontend team needs custom React configs for internal docs.
+
+**Setup:**
+
+```bash
+# 1. Team lead creates repo
+gh repo create myteam/skill-configs --private
+
+# 2. Add configs
+cd myteam-skill-configs
+cp ../Skill_Seekers/configs/react.json ./react-internal.json
+
+# Edit for internal docs:
+# - Change base_url to internal docs site
+# - Adjust selectors for company theme
+# - Customize categories
+
+git add . && git commit -m "Add internal React config" && git push
+
+# 3. Team members register (one-time)
+export GITHUB_TOKEN=ghp_their_token
+add_config_source(
+    name="team",
+    git_url="https://github.com/myteam/skill-configs.git"
+)
+
+# 4. Daily usage
+fetch_config(source="team", config_name="react-internal")
+```
+
+**Benefits:**
+- ✅ Shared configs across team
+- ✅ Version controlled
+- ✅ Private to company
+- ✅ Easy updates (git push)
+
+### Enterprise (500+ developers)
+
+**Scenario:** Large company with multiple teams, internal docs, and priority-based config resolution.
+
+**Setup:**
+
+```bash
+# IT pre-configures sources for all developers
+# (via company setup script or documentation)
+
+# 1. Platform team configs (highest priority)
+add_config_source(
+    name="platform",
+    git_url="https://gitlab.company.com/platform/skill-configs.git",
+    source_type="gitlab",
+    token_env="GITLAB_COMPANY_TOKEN",
+    priority=1
+)
+
+# 2. Mobile team configs
+add_config_source(
+    name="mobile",
+    git_url="https://gitlab.company.com/mobile/skill-configs.git",
+    source_type="gitlab",
+    token_env="GITLAB_COMPANY_TOKEN",
+    priority=2
+)
+
+# 3. Public/official configs (fallback)
+# (API mode, no registration needed, lowest priority)
+```
+
+**Developer usage:**
+
+```python
+# Automatically finds config with highest priority
+fetch_config(config_name="platform-api")  # Found in platform source
+fetch_config(config_name="react-native")  # Found in mobile source
+fetch_config(config_name="react")  # Falls back to public API
+```
+
+**Benefits:**
+- ✅ Centralized config management
+- ✅ Team-specific overrides
+- ✅ Fallback to public configs
+- ✅ Priority-based resolution
+- ✅ Scales to hundreds of developers
+
+### Open Source Project
+
+**Scenario:** Open source project wants curated configs for contributors.
+
+**Setup:**
+
+```bash
+# 1. Create public repo
+gh repo create myproject/skill-configs --public
+
+# 2. Add configs for project stack
+- react.json (frontend)
+- django.json (backend)
+- postgres.json (database)
+- nginx.json (deployment)
+
+# 3. Contributors use directly (no token needed for public repos)
+add_config_source(
+    name="myproject",
+    git_url="https://github.com/myproject/skill-configs.git"
+)
+
+fetch_config(source="myproject", config_name="react")
+```
+
+**Benefits:**
+- ✅ Curated configs for project
+- ✅ No API dependency
+- ✅ Community contributions via PR
+- ✅ Version controlled
+
+---
+
+## Best Practices
+
+### Config Naming
+
+**Good:**
+- `react-internal.json` - Clear purpose
+- `api-v2.json` - Version included
+- `platform-auth.json` - Specific topic
+
+**Bad:**
+- `config1.json` - Generic
+- `react.json` - Conflicts with official
+- `test.json` - Not descriptive
+
+### Repository Structure
+
+**Flat (recommended for small repos):**
+```
+skill-configs/
+├── README.md
+├── react-internal.json
+├── vue-internal.json
+└── api-v2.json
+```
+
+**Organized (recommended for large repos):**
+```
+skill-configs/
+├── README.md
+├── frontend/
+│   ├── react-internal.json
+│   └── vue-internal.json
+├── backend/
+│   ├── django-api.json
+│   └── fastapi-platform.json
+└── mobile/
+    ├── react-native.json
+    └── flutter.json
+```
+
+**Note:** Config discovery works recursively, so both structures work!
+
+### Source Priorities
+
+Lower number = higher priority. Use sensible defaults:
+
+- `1-10`: Critical/override configs
+- `50-100`: Team configs (default: 100)
+- `1000+`: Fallback/experimental
+
+**Example:**
+```python
+# Override official React config with internal version
+add_config_source(name="team", ..., priority=1)  # Checked first
+# Official API is checked last (priority: infinity)
+```
+
+### Security
+
+✅ **DO:**
+- Use environment variables for tokens
+- Use private repos for sensitive configs
+- Rotate tokens regularly
+- Use fine-grained tokens (read-only if possible)
+
+❌ **DON'T:**
+- Commit tokens to git
+- Share tokens between people
+- Use personal tokens for teams (use service accounts)
+- Store tokens in config files
+
+### Maintenance
+
+**Regular tasks:**
+```bash
+# Update configs in repo
+cd myteam-skill-configs
+# Edit configs...
+git commit -m "Update React config" && git push
+
+# Developers get updates automatically on next fetch
+fetch_config(source="team", config_name="react-internal")
+# ^--- Auto-pulls latest changes
+```
+
+**Force refresh:**
+```python
+# Delete cache and re-clone
+fetch_config(source="team", config_name="react-internal", refresh=true)
+```
+
+**Clean up old sources:**
+```bash
+# Remove unused sources
+remove_config_source(name="old-team")
+
+# Free disk space
+rm -rf ~/.skill-seekers/cache/old-team/
+```
+
+---
+
+## Troubleshooting
+
+### Authentication Failures
+
+**Error:** "Authentication failed for https://github.com/org/repo.git"
+
+**Solutions:**
+1. Check token is set:
+   ```bash
+   echo $GITHUB_TOKEN  # Should show token
+   ```
+
+2. Verify token has correct permissions:
+   - GitHub: `repo` scope for private repos
+   - GitLab: `read_repository` scope
+
+3. Check token isn't expired:
+   - Regenerate if needed
+
+4. Try direct access:
+   ```bash
+   git clone https://$GITHUB_TOKEN@github.com/org/repo.git test-clone
+   ```
+
+### Config Not Found
+
+**Error:** "Config 'react' not found in repository. Available configs: django, vue"
+
+**Solutions:**
+1. List available configs:
+   ```python
+   # Shows what's actually in the repo
+   list_config_sources()
+   ```
+
+2. Check config file exists in repo:
+   ```bash
+   # Clone locally and inspect
+   git clone <git_url> temp-inspect
+   find temp-inspect -name "*.json"
+   ```
+
+3. Verify config name (case-insensitive):
+   - `react` matches `React.json` or `react.json`
+
+### Slow Cloning
+
+**Issue:** Repository takes minutes to clone.
+
+**Solutions:**
+1. Shallow clone is already enabled (depth=1)
+
+2. Check repository size:
+   ```bash
+   # See repo size
+   gh repo view owner/repo --json diskUsage
+   ```
+
+3. If very large (>100MB), consider:
+   - Splitting configs into separate repos
+   - Using sparse checkout
+   - Contacting IT to optimize repo
+
+### Cache Issues
+
+**Issue:** Getting old configs even after updating repo.
+
+**Solutions:**
+1. Force refresh:
+   ```python
+   fetch_config(source="team", config_name="react", refresh=true)
+   ```
+
+2. Manual cache clear:
+   ```bash
+   rm -rf ~/.skill-seekers/cache/team/
+   ```
+
+3. Check auto-pull worked:
+   ```bash
+   cd ~/.skill-seekers/cache/team
+   git log -1  # Shows latest commit
+   ```
+
+---
+
+## Advanced Topics
+
+### Multiple Git Accounts
+
+Use different tokens for different repos:
+
+```bash
+# Personal GitHub
+export GITHUB_TOKEN=ghp_personal_xxx
+
+# Work GitHub
+export GITHUB_WORK_TOKEN=ghp_work_yyy
+
+# Company GitLab
+export GITLAB_COMPANY_TOKEN=glpat-zzz
+```
+
+Register with specific tokens:
+```python
+add_config_source(
+    name="personal",
+    git_url="https://github.com/myuser/configs.git",
+    token_env="GITHUB_TOKEN"
+)
+
+add_config_source(
+    name="work",
+    git_url="https://github.com/mycompany/configs.git",
+    token_env="GITHUB_WORK_TOKEN"
+)
+```
+
+### Custom Cache Location
+
+Set custom cache directory:
+
+```bash
+export SKILL_SEEKERS_CACHE_DIR=/mnt/large-disk/skill-seekers-cache
+```
+
+Or pass to GitConfigRepo:
+```python
+from skill_seekers.mcp.git_repo import GitConfigRepo
+
+gr = GitConfigRepo(cache_dir="/custom/path/cache")
+```
+
+### SSH URLs
+
+SSH URLs are automatically converted to HTTPS + token:
+
+```python
+# Input
+add_config_source(
+    name="team",
+    git_url="git@github.com:myorg/configs.git",
+    token_env="GITHUB_TOKEN"
+)
+
+# Internally becomes
+# https://ghp_xxx@github.com/myorg/configs.git
+```
+
+### Priority Resolution
+
+When same config exists in multiple sources:
+
+```python
+add_config_source(name="team", ..., priority=1)     # Checked first
+add_config_source(name="company", ..., priority=2)  # Checked second
+# API mode is checked last (priority: infinity)
+
+fetch_config(config_name="react")
+# 1. Checks team source
+# 2. If not found, checks company source
+# 3. If not found, falls back to API
+```
+
+### CI/CD Integration
+
+Use in GitHub Actions:
+
+```yaml
+name: Generate Skills
+
+on: push
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install Skill Seekers
+        run: pip install skill-seekers
+
+      - name: Register config source
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python3 << EOF
+          from skill_seekers.mcp.source_manager import SourceManager
+          sm = SourceManager()
+          sm.add_source(
+              name="team",
+              git_url="https://github.com/myorg/configs.git"
+          )
+          EOF
+
+      - name: Fetch and use config
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Use MCP fetch_config or direct Python
+          skill-seekers create --config <fetched_config>
+```
+
+---
+
+## API Reference
+
+### GitConfigRepo Class
+
+**Location:** `src/skill_seekers/mcp/git_repo.py`
+
+**Methods:**
+
+```python
+def __init__(cache_dir: Optional[str] = None)
+    """Initialize with optional cache directory."""
+
+def clone_or_pull(
+    source_name: str,
+    git_url: str,
+    branch: str = "main",
+    token: Optional[str] = None,
+    force_refresh: bool = False
+) -> Path:
+    """Clone if not cached, else pull latest changes."""
+
+def find_configs(repo_path: Path) -> list[Path]:
+    """Find all *.json files in repository."""
+
+def get_config(repo_path: Path, config_name: str) -> dict:
+    """Load specific config by name."""
+
+@staticmethod
+def inject_token(git_url: str, token: str) -> str:
+    """Inject token into git URL."""
+
+@staticmethod
+def validate_git_url(git_url: str) -> bool:
+    """Validate git URL format."""
+```
+
+### SourceManager Class
+
+**Location:** `src/skill_seekers/mcp/source_manager.py`
+
+**Methods:**
+
+```python
+def __init__(config_dir: Optional[str] = None)
+    """Initialize with optional config directory."""
+
+def add_source(
+    name: str,
+    git_url: str,
+    source_type: str = "github",
+    token_env: Optional[str] = None,
+    branch: str = "main",
+    priority: int = 100,
+    enabled: bool = True
+) -> dict:
+    """Add or update config source."""
+
+def get_source(name: str) -> dict:
+    """Get source by name."""
+
+def list_sources(enabled_only: bool = False) -> list[dict]:
+    """List all sources."""
+
+def remove_source(name: str) -> bool:
+    """Remove source."""
+
+def update_source(name: str, **kwargs) -> dict:
+    """Update specific fields."""
+```
+
+---
+
+## See Also
+
+- [README.md](../README.md) - Main documentation
+- [MCP_SETUP.md](MCP_SETUP.md) - MCP server setup
+- [UNIFIED_SCRAPING.md](UNIFIED_SCRAPING.md) - Multi-source scraping
+- [configs/example-team/](../configs/example-team/) - Example repository
+
+---
+
+## Changelog
+
+### v2.2.0 (2025-12-21)
+- Initial release of git-based config sources
+- 3 fetch modes: API, Git URL, Named Source
+- 4 MCP tools: add/list/remove/fetch
+- Support for GitHub, GitLab, Bitbucket, Gitea
+- Shallow clone optimization
+- Priority-based resolution
+- 83 tests (100% passing)
+
+---
+
+**Questions?** Open an issue at https://github.com/yusufkaraaslan/Skill_Seekers/issues

docs/reference/LARGE_DOCUMENTATION.md

@@ -0,0 +1,431 @@
+# Handling Large Documentation Sites (10K+ Pages)
+
+Complete guide for scraping and managing large documentation sites with Skill Seeker.
+
+---
+
+## Table of Contents
+
+- [When to Split Documentation](#when-to-split-documentation)
+- [Split Strategies](#split-strategies)
+- [Quick Start](#quick-start)
+- [Detailed Workflows](#detailed-workflows)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## When to Split Documentation
+
+### Size Guidelines
+
+| Documentation Size | Recommendation | Strategy |
+|-------------------|----------------|----------|
+| < 5,000 pages | **One skill** | No splitting needed |
+| 5,000 - 10,000 pages | **Consider splitting** | Category-based |
+| 10,000 - 30,000 pages | **Recommended** | Router + Categories |
+| 30,000+ pages | **Strongly recommended** | Router + Categories |
+
+### Why Split Large Documentation?
+
+**Benefits:**
+- ✅ Faster scraping (parallel execution)
+- ✅ More focused skills (better Claude performance)
+- ✅ Easier maintenance (update one topic at a time)
+- ✅ Better user experience (precise answers)
+- ✅ Avoids context window limits
+
+**Trade-offs:**
+- ⚠️ Multiple skills to manage
+- ⚠️ Initial setup more complex
+- ⚠️ Router adds one extra skill
+
+---
+
+## Split Strategies
+
+### 1. **No Split** (One Big Skill)
+**Best for:** Small to medium documentation (< 5K pages)
+
+```bash
+# Just use the config as-is
+skill-seekers create --config configs/react.json
+```
+
+**Pros:** Simple, one skill to maintain
+**Cons:** Can be slow for large docs, may hit limits
+
+---
+
+### 2. **Category Split** (Multiple Focused Skills)
+**Best for:** 5K-15K pages with clear topic divisions
+
+```bash
+# Auto-split by categories
+python -m skill_seekers.cli.split_config configs/godot.json --strategy category
+
+# Creates:
+# - godot-scripting.json
+# - godot-2d.json
+# - godot-3d.json
+# - godot-physics.json
+# - etc.
+```
+
+**Pros:** Focused skills, clear separation
+**Cons:** User must know which skill to use
+
+---
+
+### 3. **Router + Categories** (Intelligent Hub) ⭐ RECOMMENDED
+**Best for:** 10K+ pages, best user experience
+
+```bash
+# Create router + sub-skills
+python -m skill_seekers.cli.split_config configs/godot.json --strategy router
+
+# Creates:
+# - godot.json (router/hub)
+# - godot-scripting.json
+# - godot-2d.json
+# - etc.
+```
+
+**Pros:** Best of both worlds, intelligent routing, natural UX
+**Cons:** Slightly more complex setup
+
+---
+
+### 4. **Size-Based Split**
+**Best for:** Docs without clear categories
+
+```bash
+# Split every 5000 pages
+python -m skill_seekers.cli.split_config configs/bigdocs.json --strategy size --target-pages 5000
+
+# Creates:
+# - bigdocs-part1.json
+# - bigdocs-part2.json
+# - bigdocs-part3.json
+# - etc.
+```
+
+**Pros:** Simple, predictable
+**Cons:** May split related topics
+
+---
+
+## Quick Start
+
+### Option 1: Automatic (Recommended)
+
+```bash
+# 1. Create config
+skill-seekers create --interactive
+# Name: godot
+# URL: https://docs.godotengine.org
+# ... fill in prompts ...
+
+# 2. Estimate pages (discovers it's large)
+skill-seekers estimate configs/godot.json
+# Output: ⚠️  40,000 pages detected - splitting recommended
+
+# 3. Auto-split with router
+python -m skill_seekers.cli.split_config configs/godot.json --strategy router
+
+# 4. Scrape all sub-skills
+for config in configs/godot-*.json; do
+  skill-seekers create --config $config &
+done
+wait
+
+# 5. Generate router
+skill-seekers create configs/godot-*.json
+
+# 6. Package all
+skill-seekers package output/godot*/
+
+# 7. Upload all .zip files to Claude
+```
+
+---
+
+### Option 2: Manual Control
+
+```bash
+# 1. Define split in config
+nano configs/godot.json
+
+# Add:
+{
+  "split_strategy": "router",
+  "split_config": {
+    "target_pages_per_skill": 5000,
+    "create_router": true,
+    "split_by_categories": ["scripting", "2d", "3d", "physics"]
+  }
+}
+
+# 2. Split
+skill-seekers create configs/godot.json
+
+# 3. Continue as above...
+```
+
+---
+
+## Detailed Workflows
+
+### Workflow 1: Router + Categories (40K Pages)
+
+**Scenario:** Godot documentation (40,000 pages)
+
+**Step 1: Estimate**
+```bash
+skill-seekers estimate configs/godot.json
+
+# Output:
+# Estimated: 40,000 pages
+# Recommended: Split into 8 skills (5K each)
+```
+
+**Step 2: Split Configuration**
+```bash
+python -m skill_seekers.cli.split_config configs/godot.json --strategy router --target-pages 5000
+
+# Creates:
+# configs/godot.json (router)
+# configs/godot-scripting.json (5K pages)
+# configs/godot-2d.json (8K pages)
+# configs/godot-3d.json (10K pages)
+# configs/godot-physics.json (6K pages)
+# configs/godot-shaders.json (11K pages)
+```
+
+**Step 3: Scrape Sub-Skills (Parallel)**
+```bash
+# Open multiple terminals or use background jobs
+skill-seekers create --config configs/godot-scripting.json &
+skill-seekers create --config configs/godot-2d.json &
+skill-seekers create --config configs/godot-3d.json &
+skill-seekers create --config configs/godot-physics.json &
+skill-seekers create --config configs/godot-shaders.json &
+
+# Wait for all to complete
+wait
+
+# Time: 4-8 hours (parallel) vs 20-40 hours (sequential)
+```
+
+**Step 4: Generate Router**
+```bash
+skill-seekers create configs/godot-*.json
+
+# Creates:
+# output/godot/SKILL.md (router skill)
+```
+
+**Step 5: Package All**
+```bash
+skill-seekers package output/godot*/
+
+# Creates:
+# output/godot.zip (router)
+# output/godot-scripting.zip
+# output/godot-2d.zip
+# output/godot-3d.zip
+# output/godot-physics.zip
+# output/godot-shaders.zip
+```
+
+**Step 6: Upload to Claude**
+Upload all 6 .zip files to Claude. The router will intelligently direct queries to the right sub-skill!
+
+---
+
+### Workflow 2: Category Split Only (15K Pages)
+
+**Scenario:** Vue.js documentation (15,000 pages)
+
+**No router needed - just focused skills:**
+
+```bash
+# 1. Split
+python -m skill_seekers.cli.split_config configs/vue.json --strategy category
+
+# 2. Scrape each
+for config in configs/vue-*.json; do
+  skill-seekers create --config $config
+done
+
+# 3. Package
+skill-seekers package output/vue*/
+
+# 4. Upload all to Claude
+```
+
+**Result:** 5 focused Vue skills (components, reactivity, routing, etc.)
+
+---
+
+## Best Practices
+
+### 1. **Choose Target Size Wisely**
+
+```bash
+# Small focused skills (3K-5K pages) - more skills, very focused
+python -m skill_seekers.cli.split_config config.json --target-pages 3000
+
+# Medium skills (5K-8K pages) - balanced (RECOMMENDED)
+python -m skill_seekers.cli.split_config config.json --target-pages 5000
+
+# Larger skills (8K-10K pages) - fewer skills, broader
+python -m skill_seekers.cli.split_config config.json --target-pages 8000
+```
+
+### 2. **Use Parallel Scraping**
+
+```bash
+# Serial (slow - 40 hours)
+for config in configs/godot-*.json; do
+  skill-seekers create --config $config
+done
+
+# Parallel (fast - 8 hours) ⭐
+for config in configs/godot-*.json; do
+  skill-seekers create --config $config &
+done
+wait
+```
+
+### 3. **Test Before Full Scrape**
+
+```bash
+# Test with limited pages first
+nano configs/godot-2d.json
+# Set: "max_pages": 50
+
+skill-seekers create --config configs/godot-2d.json
+
+# If output looks good, increase to full
+```
+
+### 4. **Use Checkpoints for Long Scrapes**
+
+```bash
+# Enable checkpoints in config
+{
+  "checkpoint": {
+    "enabled": true,
+    "interval": 1000
+  }
+}
+
+# If scrape fails, resume
+skill-seekers create --config config.json --resume
+```
+
+---
+
+## Examples
+
+### Example 1: AWS Documentation (Hypothetical 50K Pages)
+
+```bash
+# 1. Split by AWS services
+python -m skill_seekers.cli.split_config configs/aws.json --strategy router --target-pages 5000
+
+# Creates ~10 skills:
+# - aws (router)
+# - aws-compute (EC2, Lambda)
+# - aws-storage (S3, EBS)
+# - aws-database (RDS, DynamoDB)
+# - etc.
+
+# 2. Scrape in parallel (overnight)
+# 3. Upload all skills to Claude
+# 4. User asks "How do I create an S3 bucket?"
+# 5. Router activates aws-storage skill
+# 6. Focused, accurate answer!
+```
+
+### Example 2: Microsoft Docs (100K+ Pages)
+
+```bash
+# Too large even with splitting - use selective categories
+
+# Only scrape key topics
+python -m skill_seekers.cli.split_config configs/microsoft.json --strategy category
+
+# Edit configs to include only:
+# - microsoft-azure (Azure docs only)
+# - microsoft-dotnet (.NET docs only)
+# - microsoft-typescript (TS docs only)
+
+# Skip less relevant sections
+```
+
+---
+
+## Troubleshooting
+
+### Issue: "Splitting creates too many skills"
+
+**Solution:** Increase target size or combine categories
+
+```bash
+# Instead of 5K per skill, use 8K
+python -m skill_seekers.cli.split_config config.json --target-pages 8000
+
+# Or manually combine categories in config
+```
+
+### Issue: "Router not routing correctly"
+
+**Solution:** Check routing keywords in router SKILL.md
+
+```bash
+# Review router
+cat output/godot/SKILL.md
+
+# Update keywords if needed
+nano output/godot/SKILL.md
+```
+
+### Issue: "Parallel scraping fails"
+
+**Solution:** Reduce parallelism or check rate limits
+
+```bash
+# Scrape 2-3 at a time instead of all
+skill-seekers create --config config1.json &
+skill-seekers create --config config2.json &
+wait
+
+skill-seekers create --config config3.json &
+skill-seekers create --config config4.json &
+wait
+```
+
+---
+
+## Summary
+
+**For 40K+ Page Documentation:**
+
+1. ✅ **Estimate first**: `skill-seekers estimate config.json`
+2. ✅ **Split with router**: `python -m skill_seekers.cli.split_config config.json --strategy router`
+3. ✅ **Scrape in parallel**: Multiple terminals or background jobs
+4. ✅ **Generate router**: `skill-seekers create configs/*-*.json`
+5. ✅ **Package all**: `skill-seekers package output/*/`
+6. ✅ **Upload to Claude**: All .zip files
+
+**Result:** Intelligent, fast, focused skills that work seamlessly together!
+
+---
+
+**Questions? See:**
+- [Main README](../README.md)
+- [MCP Setup Guide](MCP_SETUP.md)
+- [Enhancement Guide](ENHANCEMENT.md)

docs/reference/LLMS_TXT_SUPPORT.md

@@ -0,0 +1,60 @@
+# llms.txt Support
+
+## Overview
+
+Skill_Seekers now automatically detects and uses llms.txt files when available, providing 10x faster documentation ingestion.
+
+## What is llms.txt?
+
+The llms.txt convention is a growing standard where documentation sites provide pre-formatted, LLM-ready markdown files:
+
+- `llms-full.txt` - Complete documentation
+- `llms.txt` - Standard balanced version
+- `llms-small.txt` - Quick reference
+
+## How It Works
+
+1. Before HTML scraping, Skill_Seekers checks for llms.txt files
+2. If found, downloads and parses the markdown
+3. If not found, falls back to HTML scraping
+4. Zero config changes needed
+
+## Configuration
+
+### Automatic Detection (Recommended)
+
+No config changes needed. Just run normally:
+
+```bash
+skill-seekers create --config configs/hono.json
+```
+
+### Explicit URL
+
+Optionally specify llms.txt URL:
+
+```json
+{
+  "name": "hono",
+  "llms_txt_url": "https://hono.dev/llms-full.txt",
+  "base_url": "https://hono.dev/docs"
+}
+```
+
+## Performance Comparison
+
+| Method | Time | Requests |
+|--------|------|----------|
+| HTML Scraping (20 pages) | 20-60s | 20+ |
+| llms.txt | < 5s | 1 |
+
+## Supported Sites
+
+Sites known to provide llms.txt:
+
+- Hono: https://hono.dev/llms-full.txt
+- (More to be discovered)
+
+## Fallback Behavior
+
+If llms.txt download or parsing fails, automatically falls back to HTML scraping with no user intervention required.

docs/reference/SKILL_ARCHITECTURE.md

@@ -0,0 +1,930 @@
+# Skill Architecture Guide: Layering and Splitting
+
+Complete guide for architecting complex multi-skill systems using the router/dispatcher pattern.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [When to Split Skills](#when-to-split-skills)
+- [The Router Pattern](#the-router-pattern)
+- [Manual Skill Architecture](#manual-skill-architecture)
+- [Best Practices](#best-practices)
+- [Complete Examples](#complete-examples)
+- [Implementation Guide](#implementation-guide)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+### The 500-Line Guideline
+
+Claude recommends keeping skill files under **500 lines** for optimal performance. This guideline exists because:
+
+- ✅ **Better parsing** - AI can more effectively understand focused content
+- ✅ **Context efficiency** - Only relevant information loaded per task
+- ✅ **Maintainability** - Easier to debug, update, and manage
+- ✅ **Single responsibility** - Each skill does one thing well
+
+### The Problem with Monolithic Skills
+
+As applications grow complex, developers often create skills that:
+
+- ❌ **Exceed 500 lines** - Too much information for effective parsing
+- ❌ **Mix concerns** - Handle multiple unrelated responsibilities
+- ❌ **Waste context** - Load entire file even when only small portion is relevant
+- ❌ **Hard to maintain** - Changes require careful navigation of large file
+
+### The Solution: Skill Layering
+
+**Skill layering** involves:
+
+1. **Splitting** - Breaking large skill into focused sub-skills
+2. **Routing** - Creating master skill that directs queries to appropriate sub-skill
+3. **Loading** - Only activating relevant sub-skills per task
+
+**Result:** Build sophisticated applications while maintaining 500-line guideline per skill.
+
+---
+
+## When to Split Skills
+
+### Decision Matrix
+
+| Skill Size | Complexity | Recommendation |
+|-----------|-----------|----------------|
+| < 500 lines | Single concern | ✅ **Keep monolithic** |
+| 500-1000 lines | Related concerns | ⚠️ **Consider splitting** |
+| 1000+ lines | Multiple concerns | ❌ **Must split** |
+
+### Split Indicators
+
+**You should split when:**
+
+- ✅ Skill exceeds 500 lines
+- ✅ Multiple distinct responsibilities (CRUD, workflows, etc.)
+- ✅ Different team members maintain different sections
+- ✅ Only portions are relevant to specific tasks
+- ✅ Context window frequently exceeded
+
+**You can keep monolithic when:**
+
+- ✅ Under 500 lines
+- ✅ Single, cohesive responsibility
+- ✅ All content frequently relevant together
+- ✅ Simple, focused use case
+
+---
+
+## The Router Pattern
+
+### What is a Router Skill?
+
+A **router skill** (also called **dispatcher** or **hub** skill) is a lightweight master skill that:
+
+1. **Analyzes** the user's query
+2. **Identifies** which sub-skill(s) are relevant
+3. **Directs** Claude to activate appropriate sub-skill(s)
+4. **Coordinates** responses from multiple sub-skills if needed
+
+### How It Works
+
+```
+User Query: "How do I book a flight to Paris?"
+     ↓
+Router Skill: Analyzes keywords → "flight", "book"
+     ↓
+Activates: flight_booking sub-skill
+     ↓
+Response: Flight booking guidance (only this skill loaded)
+```
+
+### Router Skill Structure
+
+```markdown
+# Travel Planner (Router)
+
+## When to Use This Skill
+
+Use for travel planning, booking, and itinerary management.
+
+This is a router skill that directs your questions to specialized sub-skills.
+
+## Sub-Skills Available
+
+### flight_booking
+For booking flights, searching airlines, comparing prices, seat selection.
+**Keywords:** flight, airline, booking, ticket, departure, arrival
+
+### hotel_reservation
+For hotel search, room booking, amenities, check-in/check-out.
+**Keywords:** hotel, accommodation, room, reservation, stay
+
+### itinerary_generation
+For creating travel plans, scheduling activities, route optimization.
+**Keywords:** itinerary, schedule, plan, activities, route
+
+## Routing Logic
+
+Based on your question keywords:
+- Flight-related → Activate `flight_booking`
+- Hotel-related → Activate `hotel_reservation`
+- Planning-related → Activate `itinerary_generation`
+- Multiple topics → Activate relevant combination
+
+## Usage Examples
+
+**"Find me a flight to Paris"** → flight_booking
+**"Book hotel in Tokyo"** → hotel_reservation
+**"Create 5-day Rome itinerary"** → itinerary_generation
+**"Plan Paris trip with flights and hotel"** → flight_booking + hotel_reservation + itinerary_generation
+```
+
+---
+
+## Manual Skill Architecture
+
+### Example 1: E-Commerce Platform
+
+**Problem:** E-commerce skill is 2000+ lines covering catalog, cart, checkout, orders, and admin.
+
+**Solution:** Split into focused sub-skills with router.
+
+#### Sub-Skills
+
+**1. `ecommerce.md` (Router - 150 lines)**
+```markdown
+# E-Commerce Platform (Router)
+
+## Sub-Skills
+- product_catalog - Browse, search, filter products
+- shopping_cart - Add/remove items, quantities
+- checkout_payment - Process orders, payments
+- order_management - Track orders, returns
+- admin_tools - Inventory, analytics
+
+## Routing
+product/catalog/search → product_catalog
+cart/basket/add/remove → shopping_cart
+checkout/payment/billing → checkout_payment
+order/track/return → order_management
+admin/inventory/analytics → admin_tools
+```
+
+**2. `product_catalog.md` (350 lines)**
+```markdown
+# Product Catalog
+
+## When to Use
+Product browsing, searching, filtering, recommendations.
+
+## Quick Reference
+- Search products: `search(query, filters)`
+- Get details: `getProduct(id)`
+- Filter: `filter(category, price, brand)`
+...
+```
+
+**3. `shopping_cart.md` (280 lines)**
+```markdown
+# Shopping Cart
+
+## When to Use
+Managing cart items, quantities, totals.
+
+## Quick Reference
+- Add item: `cart.add(productId, quantity)`
+- Update quantity: `cart.update(itemId, quantity)`
+...
+```
+
+**Result:**
+- Router: 150 lines ✅
+- Each sub-skill: 200-400 lines ✅
+- Total functionality: Unchanged
+- Context efficiency: 5x improvement
+
+---
+
+### Example 2: Code Assistant
+
+**Problem:** Code assistant handles debugging, refactoring, documentation, testing - 1800+ lines.
+
+**Solution:** Specialized sub-skills with smart routing.
+
+#### Architecture
+
+```
+code_assistant.md (Router - 200 lines)
+├── debugging.md (450 lines)
+├── refactoring.md (380 lines)
+├── documentation.md (320 lines)
+└── testing.md (400 lines)
+```
+
+#### Router Logic
+
+```markdown
+# Code Assistant (Router)
+
+## Routing Keywords
+
+### debugging
+error, bug, exception, crash, fix, troubleshoot, debug
+
+### refactoring
+refactor, clean, optimize, simplify, restructure, improve
+
+### documentation
+docs, comment, docstring, readme, api, explain
+
+### testing
+test, unit, integration, coverage, assert, mock
+```
+
+---
+
+### Example 3: Data Pipeline
+
+**Problem:** ETL pipeline skill covers extraction, transformation, loading, validation, monitoring.
+
+**Solution:** Pipeline stages as sub-skills.
+
+```
+data_pipeline.md (Router)
+├── data_extraction.md - Source connectors, API calls
+├── data_transformation.md - Cleaning, mapping, enrichment
+├── data_loading.md - Database writes, file exports
+├── data_validation.md - Quality checks, error handling
+└── pipeline_monitoring.md - Logging, alerts, metrics
+```
+
+---
+
+## Best Practices
+
+### 1. Single Responsibility Principle
+
+**Each sub-skill should have ONE clear purpose.**
+
+❌ **Bad:** `user_management.md` handles auth, profiles, permissions, notifications
+✅ **Good:**
+- `user_authentication.md` - Login, logout, sessions
+- `user_profiles.md` - Profile CRUD
+- `user_permissions.md` - Roles, access control
+- `user_notifications.md` - Email, push, alerts
+
+### 2. Clear Routing Keywords
+
+**Make routing keywords explicit and unambiguous.**
+
+❌ **Bad:** Vague keywords like "data", "user", "process"
+✅ **Good:** Specific keywords like "login", "authenticate", "extract", "transform"
+
+### 3. Minimize Router Complexity
+
+**Keep router lightweight - just routing logic.**
+
+❌ **Bad:** Router contains actual implementation code
+✅ **Good:** Router only contains:
+- Sub-skill descriptions
+- Routing keywords
+- Usage examples
+- No implementation details
+
+### 4. Logical Grouping
+
+**Group by responsibility, not by code structure.**
+
+❌ **Bad:** Split by file type (controllers, models, views)
+✅ **Good:** Split by feature (user_auth, product_catalog, order_processing)
+
+### 5. Avoid Over-Splitting
+
+**Don't create sub-skills for trivial distinctions.**
+
+❌ **Bad:** Separate skills for "add_user" and "update_user"
+✅ **Good:** Single "user_management" skill covering all CRUD
+
+### 6. Document Dependencies
+
+**Explicitly state when sub-skills work together.**
+
+```markdown
+## Multi-Skill Operations
+
+**Place order:** Requires coordination between:
+1. product_catalog - Validate product availability
+2. shopping_cart - Get cart contents
+3. checkout_payment - Process payment
+4. order_management - Create order record
+```
+
+### 7. Maintain Consistent Structure
+
+**Use same SKILL.md structure across all sub-skills.**
+
+Standard sections:
+```markdown
+# Skill Name
+
+## When to Use This Skill
+[Clear description]
+
+## Quick Reference
+[Common operations]
+
+## Key Concepts
+[Domain terminology]
+
+## Working with This Skill
+[Usage guidance]
+
+## Reference Files
+[Documentation organization]
+```
+
+---
+
+## Complete Examples
+
+### Travel Planner (Full Implementation)
+
+#### Directory Structure
+
+```
+skills/
+├── travel_planner.md (Router - 180 lines)
+├── flight_booking.md (420 lines)
+├── hotel_reservation.md (380 lines)
+├── itinerary_generation.md (450 lines)
+├── travel_insurance.md (290 lines)
+└── budget_tracking.md (340 lines)
+```
+
+#### travel_planner.md (Router)
+
+```markdown
+---
+name: travel_planner
+description: Travel planning, booking, and itinerary management router
+---
+
+# Travel Planner (Router)
+
+## When to Use This Skill
+
+Use for all travel-related planning, bookings, and itinerary management.
+
+This router skill analyzes your travel needs and activates specialized sub-skills.
+
+## Available Sub-Skills
+
+### flight_booking
+**Purpose:** Flight search, booking, seat selection, airline comparisons
+**Keywords:** flight, airline, plane, ticket, departure, arrival, airport, booking
+**Use for:** Finding and booking flights, comparing prices, selecting seats
+
+### hotel_reservation
+**Purpose:** Hotel search, room booking, amenities, check-in/out
+**Keywords:** hotel, accommodation, room, lodging, reservation, stay, check-in
+**Use for:** Finding hotels, booking rooms, checking amenities
+
+### itinerary_generation
+**Purpose:** Travel planning, scheduling, route optimization
+**Keywords:** itinerary, schedule, plan, route, activities, sightseeing
+**Use for:** Creating day-by-day plans, organizing activities
+
+### travel_insurance
+**Purpose:** Travel insurance options, coverage, claims
+**Keywords:** insurance, coverage, protection, medical, cancellation, claim
+**Use for:** Insurance recommendations, comparing policies
+
+### budget_tracking
+**Purpose:** Travel budget planning, expense tracking
+**Keywords:** budget, cost, expense, price, spending, money
+**Use for:** Estimating costs, tracking expenses
+
+## Routing Logic
+
+The router analyzes your question and activates relevant skills:
+
+| Query Pattern | Activated Skills |
+|--------------|------------------|
+| "Find flights to [destination]" | flight_booking |
+| "Book hotel in [city]" | hotel_reservation |
+| "Plan [duration] trip to [destination]" | itinerary_generation |
+| "Need travel insurance" | travel_insurance |
+| "How much will trip cost?" | budget_tracking |
+| "Plan complete Paris vacation" | ALL (coordinated) |
+
+## Multi-Skill Coordination
+
+Some requests require multiple skills working together:
+
+### Complete Trip Planning
+1. **budget_tracking** - Set budget constraints
+2. **flight_booking** - Find flights within budget
+3. **hotel_reservation** - Book accommodation
+4. **itinerary_generation** - Create daily schedule
+5. **travel_insurance** - Recommend coverage
+
+### Booking Modification
+1. **flight_booking** - Check flight change fees
+2. **hotel_reservation** - Verify cancellation policy
+3. **budget_tracking** - Calculate cost impact
+
+## Usage Examples
+
+**Simple (single skill):**
+- "Find direct flights to Tokyo" → flight_booking
+- "5-star hotels in Paris under $200/night" → hotel_reservation
+- "Create 3-day Rome itinerary" → itinerary_generation
+
+**Complex (multiple skills):**
+- "Plan week-long Paris trip for 2, budget $3000" → budget_tracking → flight_booking → hotel_reservation → itinerary_generation
+- "Cheapest way to visit London next month" → budget_tracking + flight_booking + hotel_reservation
+
+## Quick Reference
+
+### Flight Booking
+- Search flights by route, dates, airline
+- Compare prices across carriers
+- Select seats, meals, baggage
+
+### Hotel Reservation
+- Filter by price, rating, amenities
+- Check availability, reviews
+- Book rooms with cancellation policy
+
+### Itinerary Planning
+- Generate day-by-day schedules
+- Optimize routes between attractions
+- Balance activities with free time
+
+### Travel Insurance
+- Compare coverage options
+- Understand medical, cancellation policies
+- File claims if needed
+
+### Budget Tracking
+- Estimate total trip cost
+- Track expenses vs budget
+- Optimize spending
+
+## Working with This Skill
+
+**Beginners:** Start with single-purpose queries ("Find flights to Paris")
+**Intermediate:** Combine 2-3 aspects ("Find flights and hotel in Tokyo")
+**Advanced:** Request complete trip planning with multiple constraints
+
+The router handles complexity automatically - just ask naturally!
+```
+
+#### flight_booking.md (Sub-Skill)
+
+```markdown
+---
+name: flight_booking
+description: Flight search, booking, and airline comparisons
+---
+
+# Flight Booking
+
+## When to Use This Skill
+
+Use when searching for flights, comparing airlines, booking tickets, or managing flight reservations.
+
+## Quick Reference
+
+### Searching Flights
+
+**Search by route:**
+```
+Find flights from [origin] to [destination]
+Examples:
+- "Flights from NYC to London"
+- "JFK to Heathrow direct flights"
+```
+
+**Search with dates:**
+```
+Flights from [origin] to [destination] on [date]
+Examples:
+- "Flights from LAX to Paris on June 15"
+- "Return flights NYC to Tokyo, depart May 1, return May 15"
+```
+
+**Filter by preferences:**
+```
+[direct/nonstop] flights from [origin] to [destination]
+[airline] flights to [destination]
+Cheapest/fastest flights to [destination]
+
+Examples:
+- "Direct flights from Boston to Dublin"
+- "Delta flights to Seattle"
+- "Cheapest flights to Miami next month"
+```
+
+### Booking Process
+
+1. **Search** - Find flights matching criteria
+2. **Compare** - Review prices, times, airlines
+3. **Select** - Choose specific flight
+4. **Customize** - Add seat, baggage, meals
+5. **Confirm** - Book and receive confirmation
+
+### Price Comparison
+
+Compare across:
+- Airlines (Delta, United, American, etc.)
+- Booking sites (Expedia, Kayak, etc.)
+- Direct vs connections
+- Dates (flexible date search)
+- Classes (Economy, Business, First)
+
+### Seat Selection
+
+Options:
+- Window, aisle, middle
+- Extra legroom
+- Bulkhead, exit row
+- Section preferences (front, middle, rear)
+
+## Key Concepts
+
+### Flight Types
+- **Direct** - No stops, same plane
+- **Nonstop** - Same as direct
+- **Connecting** - One or more stops, change planes
+- **Multi-city** - Different return city
+- **Open-jaw** - Different origin/destination cities
+
+### Fare Classes
+- **Basic Economy** - Cheapest, most restrictions
+- **Economy** - Standard coach
+- **Premium Economy** - Extra space, amenities
+- **Business** - Lie-flat seats, premium service
+- **First Class** - Maximum luxury
+
+### Booking Terms
+- **Fare rules** - Cancellation, change policies
+- **Baggage allowance** - Checked and carry-on limits
+- **Layover** - Time between connecting flights
+- **Codeshare** - Same flight, different airline numbers
+
+## Working with This Skill
+
+### For Beginners
+Start with simple searches:
+1. State origin and destination
+2. Provide travel dates
+3. Mention any preferences (direct, airline)
+
+The skill will guide you through options step-by-step.
+
+### For Intermediate Users
+Provide more details upfront:
+- Preferred airlines or alliances
+- Class of service
+- Maximum connections
+- Price range
+- Specific times of day
+
+### For Advanced Users
+Complex multi-city routing:
+- Multiple destinations
+- Open-jaw bookings
+- Award ticket searches
+- Specific aircraft types
+- Detailed fare class codes
+
+## Reference Files
+
+All flight booking documentation is in `references/`:
+
+- `flight_search.md` - Search strategies, filters
+- `airline_policies.md` - Carrier-specific rules
+- `booking_process.md` - Step-by-step booking
+- `seat_selection.md` - Seating guides
+- `fare_classes.md` - Ticket types, restrictions
+- `baggage_rules.md` - Luggage policies
+- `frequent_flyer.md` - Loyalty programs
+```
+
+---
+
+## Implementation Guide
+
+### Step 1: Identify Split Points
+
+**Analyze your monolithic skill:**
+
+1. List all major responsibilities
+2. Group related functionality
+3. Identify natural boundaries
+4. Count lines per group
+
+**Example:**
+
+```
+user_management.md (1800 lines)
+├── Authentication (450 lines) ← Sub-skill
+├── Profile CRUD (380 lines) ← Sub-skill
+├── Permissions (320 lines) ← Sub-skill
+├── Notifications (280 lines) ← Sub-skill
+└── Activity logs (370 lines) ← Sub-skill
+```
+
+### Step 2: Extract Sub-Skills
+
+**For each identified group:**
+
+1. Create new `{subskill}.md` file
+2. Copy relevant content
+3. Add proper frontmatter
+4. Ensure 200-500 line range
+5. Remove dependencies on other groups
+
+**Template:**
+
+```markdown
+---
+name: {subskill_name}
+description: {clear, specific description}
+---
+
+# {Subskill Title}
+
+## When to Use This Skill
+[Specific use cases]
+
+## Quick Reference
+[Common operations]
+
+## Key Concepts
+[Domain terms]
+
+## Working with This Skill
+[Usage guidance by skill level]
+
+## Reference Files
+[Documentation structure]
+```
+
+### Step 3: Create Router
+
+**Router skill template:**
+
+```markdown
+---
+name: {router_name}
+description: {overall system description}
+---
+
+# {System Name} (Router)
+
+## When to Use This Skill
+{High-level description}
+
+This is a router skill that directs queries to specialized sub-skills.
+
+## Available Sub-Skills
+
+### {subskill_1}
+**Purpose:** {What it does}
+**Keywords:** {routing, keywords, here}
+**Use for:** {When to use}
+
+### {subskill_2}
+[Same pattern]
+
+## Routing Logic
+
+Based on query keywords:
+- {keyword_group_1} → {subskill_1}
+- {keyword_group_2} → {subskill_2}
+- Multiple matches → Coordinate relevant skills
+
+## Multi-Skill Operations
+
+{Describe when multiple skills work together}
+
+## Usage Examples
+
+**Single skill:**
+- "{example_query_1}" → {subskill_1}
+- "{example_query_2}" → {subskill_2}
+
+**Multiple skills:**
+- "{complex_query}" → {subskill_1} + {subskill_2}
+```
+
+### Step 4: Define Routing Keywords
+
+**Best practices:**
+
+- Use 5-10 keywords per sub-skill
+- Include synonyms and variations
+- Be specific, not generic
+- Test with real queries
+
+**Example:**
+
+```markdown
+### user_authentication
+**Keywords:**
+- Primary: login, logout, signin, signout, authenticate
+- Secondary: password, credentials, session, token
+- Variations: log-in, log-out, sign-in, sign-out
+```
+
+### Step 5: Test Routing
+
+**Create test queries:**
+
+```markdown
+## Test Routing (Internal Notes)
+
+Should route to user_authentication:
+✓ "How do I log in?"
+✓ "User login process"
+✓ "Authentication failed"
+
+Should route to user_profiles:
+✓ "Update user profile"
+✓ "Change profile picture"
+
+Should route to multiple skills:
+✓ "Create account and set up profile" → user_authentication + user_profiles
+```
+
+### Step 6: Update References
+
+**In each sub-skill:**
+
+1. Link to router for context
+2. Reference related sub-skills
+3. Update navigation paths
+
+```markdown
+## Related Skills
+
+This skill is part of the {System Name} suite:
+- **Router:** {router_name} - Main entry point
+- **Related:** {related_subskill} - For {use case}
+```
+
+---
+
+## Troubleshooting
+
+### Router Not Activating Correct Sub-Skill
+
+**Problem:** Query routed to wrong sub-skill
+
+**Solutions:**
+1. Add missing keywords to router
+2. Use more specific routing keywords
+3. Add disambiguation examples
+4. Test with variations of query phrasing
+
+### Sub-Skills Too Granular
+
+**Problem:** Too many tiny sub-skills (< 200 lines each)
+
+**Solution:**
+- Merge related sub-skills
+- Use sections within single skill instead
+- Aim for 300-500 lines per sub-skill
+
+### Sub-Skills Too Large
+
+**Problem:** Sub-skills still exceeding 500 lines
+
+**Solution:**
+- Further split into more granular concerns
+- Consider 3-tier architecture (router → category routers → specific skills)
+- Move reference documentation to separate files
+
+### Cross-Skill Dependencies
+
+**Problem:** Sub-skills frequently need each other
+
+**Solutions:**
+1. Create shared reference documentation
+2. Use router to coordinate multi-skill operations
+3. Reconsider split boundaries (may be too granular)
+
+### Router Logic Too Complex
+
+**Problem:** Router has extensive conditional logic
+
+**Solution:**
+- Simplify to keyword-based routing
+- Create intermediate routers (2-tier)
+- Document explicit routing table
+
+**Example 2-tier:**
+
+```
+main_router.md
+├── user_features_router.md
+│   ├── authentication.md
+│   ├── profiles.md
+│   └── permissions.md
+└── admin_features_router.md
+    ├── analytics.md
+    ├── reporting.md
+    └── configuration.md
+```
+
+---
+
+## Adapting Auto-Generated Routers
+
+Skill Seeker auto-generates router skills for large documentation using `generate_router.py`.
+
+**You can adapt this for manual skills:**
+
+### 1. Study the Pattern
+
+```bash
+# Generate a router from documentation configs
+python -m skill_seekers.cli.split_config configs/godot.json --strategy router
+skill-seekers create configs/godot-*.json
+
+# Examine generated router SKILL.md
+cat output/godot/SKILL.md
+```
+
+### 2. Extract the Template
+
+The generated router has:
+- Sub-skill descriptions
+- Keyword-based routing
+- Usage examples
+- Multi-skill coordination notes
+
+### 3. Customize for Your Use Case
+
+Replace documentation-specific content with your application logic:
+
+```markdown
+# Generated (documentation):
+### godot-scripting
+GDScript programming, signals, nodes
+Keywords: gdscript, code, script, programming
+
+# Customized (your app):
+### order_processing
+Process customer orders, payments, fulfillment
+Keywords: order, purchase, payment, checkout, fulfillment
+```
+
+---
+
+## Summary
+
+### Key Takeaways
+
+1. ✅ **500-line guideline** is important for optimal Claude performance
+2. ✅ **Router pattern** enables sophisticated applications while staying within limits
+3. ✅ **Single responsibility** - Each sub-skill does one thing well
+4. ✅ **Context efficiency** - Only load what's needed per task
+5. ✅ **Proven approach** - Already used successfully for large documentation
+
+### When to Apply This Pattern
+
+**Do use skill layering when:**
+- Skill exceeds 500 lines
+- Multiple distinct responsibilities
+- Different parts rarely used together
+- Team wants modular maintenance
+
+**Don't use skill layering when:**
+- Skill under 500 lines
+- Single, cohesive responsibility
+- All content frequently relevant together
+- Simplicity is priority
+
+### Next Steps
+
+1. Review your existing skills for split candidates
+2. Create router + sub-skills following templates above
+3. Test routing with real queries
+4. Refine keywords based on usage
+5. Iterate and improve
+
+---
+
+## Additional Resources
+
+- **Auto-Generated Routers:** See `docs/reference/LARGE_DOCUMENTATION.md` for automated splitting of scraped documentation
+- **Router Implementation:** See `src/skill_seekers/cli/generate_router.py` for reference implementation
+- **Examples:** See configs in `configs/` for real-world router patterns
+
+**Questions or feedback?** Open an issue on GitHub!