docs: Add comprehensive skill architecture guide for layering and splitting
Addresses #199 - Developer guidance for multi-skill systems **What's New:** Added SKILL_ARCHITECTURE.md covering: - Router/dispatcher pattern for complex applications - When and how to split skills (500-line guideline) - Manual skill architecture (not just auto-generated) - Best practices (single responsibility, routing keywords) - Complete examples (travel planner, e-commerce, code assistant) - Implementation guide (step-by-step) - Troubleshooting common issues **Key Patterns:** 1. **Router Pattern:** - Master skill analyzes query - Routes to appropriate sub-skill(s) - Only loads relevant context 2. **Example Architectures:** - Travel planner → flight_booking + hotel + itinerary - E-commerce → catalog + cart + checkout + orders - Code assistant → debugging + refactoring + docs + testing 3. **Guidelines:** - Keep each skill under 500 lines - Use single responsibility principle - Define clear routing keywords - Document multi-skill coordination **Based on Existing Implementation:** Adapts our proven router pattern from LARGE_DOCUMENTATION.md and generate_router.py, now documented for manual use cases. **Impact:** Enables developers to build enterprise-level multi-skill systems while maintaining optimal Claude performance and context efficiency. Closes #199
This commit is contained in:
yusyus
930
docs/SKILL_ARCHITECTURE.md
Normal file
930
docs/SKILL_ARCHITECTURE.md
Normal file
@@ -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
|
||||
python3 cli/split_config.py configs/godot.json --strategy router
|
||||
python3 cli/generate_router.py 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/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!
|
||||
Reference in New Issue
Block a user