tools-only TASK-08: Skills Enhancements & Hybrid Architecture (v2.1-v2.2)
Created: 2025-10-18 Updated: 2025-10-18 Status: Planning Priority: High Complexity: Medium
Context
After analyzing the official Claude Skills video tutorial and evaluating Agents vs Skills architecture, defined a comprehensive roadmap for Navigator v2.1-v2.2 with hybrid approach (Agents for research, Skills for execution).
Key Video Insights
Skill descriptions always loaded (~70 tokens each)
- Navigator: 5 skills × ~50 tokens = 250 tokens (GOOD ✅)
- This is acceptable overhead for auto-invocation capability
Progressive disclosure works correctly
- Description: Always in context
- Instructions (SKILL.md body): Loaded on invocation only
- Assets/functions: Loaded with instructions (0 extra tokens)
Predefined functions make skills more powerful
- Example:
slack-gif-creatorincludes Python functions - Functions are imported and used by instructions
- Enables complex workflows out-of-box
- Example:
Reference files ensure consistency
- Example implementations loaded as context
- Templates guide output format
- Makes agent output more predictable
Self-improving codebase pattern
skill-creatorskill analyzes code and generates new skills- Skills gather best practices before implementing
- Continuous improvement loop
Agents vs Skills - Use Both (Hybrid Pattern)
- Agents: Separate context, research/exploration (60-80% token savings)
- Skills: Main context, execution/consistency (predefined functions/templates)
- Video shows both can auto-invoke based on descriptions
- Don't replace one with the other - complementary tools
Agents vs Skills Architecture (CRITICAL)
The Decision: Hybrid Pattern (Use Both Strategically)
┌─────────────────────────────────────────────────────┐
│ User: "Add authentication to the frontend" │
└─────────────────────────────────────────────────────┘
↓
┌───────────────┴───────────────┐
↓ ↓
[AGENT] [SKILL]
Research Execute
↓ ↓
┌──────────────────┐ ┌──────────────────┐
│ Task Agent: │ │ Skill: │
│ "Analyze auth │ │ "frontend-auth" │
│ patterns" │ │ │
│ │ │ Uses: │
│ Searches 50 files│ │ - auth template │
│ Returns summary: │ │ - hook generator │
│ "Uses JWT in │ │ - test template │
│ api/auth.ts" │ │ │
│ │ │ Generates: │
│ (8k tokens in │ │ - useAuth hook │
│ agent context) │ │ - AuthProvider │
│ (200 token │ │ - Login form │
│ summary back) │ │ │
└──────────────────┘ └──────────────────┘
92% saved Consistent output
When to Use Agents
Agents = Research & Exploration (Separate Context)
✅ Use Task agent (subagent_type=Explore) for:
- Multi-file codebase searches
- Pattern discovery across project
- Understanding existing architecture
- "How does X work?"
- "Find all Y"
- "What's the structure of Z?"
Benefits:
- 60-80% token savings (separate context)
- No pollution of main conversation
- Returns summary only (200 tokens vs 50k)
- Can search 100+ files without overhead
Example:
User: "How does authentication work in this app?"
→ Task agent (Explore): Searches auth files
→ Returns: "JWT in api/auth.ts, Context in App.tsx, useAuth hook"
→ Main context: +200 tokens only
When to Use Skills
Skills = Execution & Consistency (Main Context)
✅ Use Skills for:
- Implementing features following patterns
- Generating boilerplate code
- Enforcing project conventions
- Creating consistent outputs
- Complex workflows with multiple steps
- Auto-invoked when user says trigger phrases
Benefits:
- Auto-invocation (no manual command needed)
- Predefined functions (no reinventing wheel)
- Templates ensure consistency
- Examples guide output format
- Instructions loaded only on invocation
Example:
User: "Add a new React component for user profile"
→ Skill auto-invokes: frontend-component
→ Uses: component_generator.py, test_generator.py
→ Uses: component-template.tsx, test-template.spec.tsx
→ Output: Consistent, follows conventions
→ Main context: +5k tokens (skill instructions)
❌ Don't Create "Backend Engineer" or "Frontend Engineer" Skills
Why not?
Too broad - could mean anything:
- Adding endpoint?
- Database migration?
- Writing tests?
- Debugging?
- Refactoring?
✅ Better: Specific skills per task type
backend-endpoint- Clear trigger: "add API endpoint"database-migration- Clear trigger: "create migration"frontend-component- Clear trigger: "create component"backend-test- Clear trigger: "write test for..."
Each has clear:
- Auto-invocation triggers
- Expected output format
- Predefined functions
- Templates
Hybrid Workflow Example
User: "Add user profile page with avatar upload"
Step 1: Agent explores (if needed)
→ Task agent: "Find existing upload patterns"
→ Returns: "File upload in utils/upload.ts, S3 config in api/storage.ts"
→ Token cost: 200 tokens (summary)
Step 2: Skill executes
→ Skill auto-invokes: frontend-component
→ Uses findings from agent
→ Uses predefined functions:
- page_generator.py
- upload_component_generator.py
- route_updater.py
→ Uses templates:
- page-template.tsx
- upload-form-template.tsx
→ Output: Consistent implementation
→ Token cost: 5k tokens (skill instructions)
Total: 5.2k tokens vs 100k+ if reading all files manually
Problems to Solve
Current State Analysis
✅ What we did right:
- Skill descriptions optimized (~50 tokens each)
- Progressive disclosure architecture correct
- YAML frontmatter follows spec
- Clear execution steps in SKILL.md
❌ What's missing:
- Predefined functions - Only nav-start has
session_stats.py, others don't - Example references - No example outputs to guide consistency
- Templates - Not explicitly referenced in skills (exist in
/templatesbut not linked) - Self-improvement capability - No skill to analyze codebase and create new skills
- Asset organization - No clear pattern for functions/examples/templates per skill
- Agents vs Skills clarity - CLAUDE.md mentions agents but doesn't explain when to use each
- Project-specific skills - No skills for common project patterns (components, endpoints, etc.)
Implementation Plan
Phase 1: Add Predefined Functions (v2.1)
nav-task enhancements:
skills/nav-task/
├── SKILL.md
├── templates/
│ ├── task-plan-template.md
│ └── task-archive-template.md
└── functions/
├── task_id_generator.py # Generate next TASK-XX ID
├── task_formatter.py # Format task markdown
└── index_updater.py # Update navigator index
nav-sop enhancements:
skills/nav-sop/
├── SKILL.md
├── examples/
│ ├── integration-sop-example.md
│ ├── debugging-sop-example.md
│ └── deployment-sop-example.md
├── templates/
│ └── sop-template.md
└── functions/
└── sop_formatter.py
nav-marker enhancements:
skills/nav-marker/
├── SKILL.md
├── examples/
│ └── marker-example.md
└── functions/
├── marker_compressor.py # Compress conversation to summary
└── marker_analyzer.py # Analyze files modified since marker
nav-compact enhancements:
skills/nav-compact/
├── SKILL.md
└── functions/
└── context_analyzer.py # Analyze what to preserve
Phase 2: Add Self-Improving Skill (v2.1)
New skill: nav-skill-creator
---
name: nav-skill-creator
description: Analyze codebase patterns and create custom skills for repetitive workflows. Use when project needs automation or pattern enforcement.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
version: 1.0.0
---
# Skill Creator
Create project-specific skills by analyzing codebase patterns.
## When to Invoke
Automatically invoke when:
- User mentions "create a skill for..."
- User says "automate this workflow"
- User requests "enforce this pattern"
- User mentions "we keep doing X manually"
## Execution Steps
### 1. Understand Skill Request
- Clarify what pattern/workflow to automate
- Identify trigger phrases for auto-invocation
- Determine required tools
### 2. Analyze Codebase
Use Task agent to:
- Find similar patterns in project
- Identify best practices from existing code
- Locate relevant configuration/setup files
- Extract example implementations
### 3. Design Skill Structure
Determine:
- Skill name (project-specific-pattern)
- Description (when to auto-invoke)
- Required tools
- Predefined functions needed
- Example references needed
- Templates to include
### 4. Generate Skill Files
Create:
- `SKILL.md` with YAML frontmatter and instructions
- `functions/` directory with helper scripts
- `examples/` directory with reference implementations
- `templates/` directory with output formats
### 5. Test Skill
- Load skill description into context
- Test auto-invocation with sample prompts
- Verify output consistency
- Iterate based on results
### 6. Document Skill
Add to:
- `.agent/system/plugin-patterns.md` (skill registry)
- Project CLAUDE.md (skill usage)
- README.md (skill listing)
## Example Use Cases
### Use Case 1: API Endpoint Pattern
**User**: "We keep adding API endpoints with similar structure. Create a skill for this."
**Skill generates**:
skills/add-api-endpoint/ ├── SKILL.md # Instructions for adding endpoints ├── functions/ │ ├── endpoint_generator.py # Generate boilerplate │ └── route_validator.py # Validate route structure ├── examples/ │ ├── rest-endpoint.ts # Example REST endpoint │ └── graphql-resolver.ts # Example GraphQL resolver └── templates/ ├── endpoint-template.ts └── test-template.spec.ts
### Use Case 2: Component Creation Pattern
**User**: "Automate creating new React components following our conventions."
**Skill generates**:
skills/create-component/ ├── SKILL.md ├── functions/ │ ├── component_generator.py │ └── style_generator.py ├── examples/ │ ├── example-component.tsx │ └── example-hook.ts └── templates/ ├── component-template.tsx ├── test-template.spec.tsx └── styles-template.css
## Success Criteria
- [ ] Skill created in `skills/[name]/` directory
- [ ] SKILL.md has proper YAML frontmatter
- [ ] Description is concise (<70 tokens)
- [ ] Predefined functions work correctly
- [ ] Examples demonstrate expected patterns
- [ ] Templates generate consistent output
- [ ] Skill auto-invokes on appropriate triggers
- [ ] Documentation updated
Phase 3: Update Existing Skills (v2.1)
Update all skill SKILL.md files to reference predefined functions and examples:
Example for nav-task:
## Predefined Functions
This skill includes helper functions in `./functions/`:
1. **task_id_generator.py** - Generate next sequential TASK-XX ID
```python
python skills/nav-task/functions/task_id_generator.py
# Output: TASK-09
task_formatter.py - Format task markdown with proper structure
python skills/nav-task/functions/task_formatter.py \ --title "Feature Name" \ --priority high \ --complexity mediumindex_updater.py - Update DEVELOPMENT-README.md index
python skills/nav-task/functions/index_updater.py \ --add TASK-09-feature-name.md
Example References
See ./examples/ for reference implementations:
task-plan-example.md- Well-structured implementation plantask-archive-example.md- Completed task documentation
Templates
Available in ./templates/:
task-plan-template.md- Starter template for new taskstask-archive-template.md- Archive format template
---
## Token Impact Analysis
### Before (v2.0)
- 5 skills × 50 tokens (descriptions) = 250 tokens always loaded
- Instructions loaded on-demand = 0 tokens until invoked
- **Total baseline**: 250 tokens
### After (v2.1)
- 6 skills × 50 tokens (descriptions) = 300 tokens always loaded
- Instructions + functions + examples loaded on-demand = 0 tokens until invoked
- **Total baseline**: 300 tokens (+50 tokens for nav-skill-creator)
**Trade-off**: +50 tokens baseline for massive capability increase (self-improving codebase)
---
## Benefits
### 1. More Consistent Output
- Templates ensure format consistency
- Examples guide implementation style
- Functions handle boilerplate automatically
### 2. More Powerful Skills
- Predefined functions enable complex workflows
- Multi-step processes automated
- Less manual prompt engineering needed
### 3. Self-Improving System
- nav-skill-creator analyzes project patterns
- Generates project-specific automation
- Continuous improvement over time
### 4. Better Token Efficiency
- Functions run without context pollution
- Examples loaded only when skill invoked
- Templates reused without duplication
---
## Migration Strategy
### v2.0 (Completed)
✅ Core Navigator skills created
✅ Plugin renamed: jitd → navigator
✅ Commands renamed: /jitd:* → /nav:*
✅ 5 skills: nav-start, nav-marker, nav-compact, nav-task, nav-sop
✅ Basic architecture in place
✅ Agent usage documented in CLAUDE.md
### v2.1 (Next - Core Enhancements)
**Focus**: Add predefined functions and self-improving capability
**Tasks**:
- [ ] Add functions to nav-task (task_id_generator.py, task_formatter.py, index_updater.py)
- [ ] Add functions to nav-sop (sop_formatter.py)
- [ ] Add functions to nav-marker (marker_compressor.py, marker_analyzer.py)
- [ ] Add functions to nav-compact (context_analyzer.py)
- [ ] Add examples to nav-sop (integration, debugging, deployment examples)
- [ ] Create nav-skill-creator skill
- [ ] Update all SKILL.md files to reference predefined functions
- [ ] Update CLAUDE.md with Agents vs Skills decision matrix
- [ ] Test locally (symlink approach)
- [ ] Push to GitHub
**Token Impact**:
- Baseline: 300 tokens (6 skill descriptions)
- Functions/examples: 0 tokens (loaded on-demand only)
- Trade-off: +50 tokens for nav-skill-creator = massive capability gain
**Timeline**: 1-2 days
### v2.2 (After v2.1 - Project-Specific Skills)
**Focus**: Use nav-skill-creator to generate common project patterns
**Generated Skills** (via nav-skill-creator):
1. **frontend-component**
- Trigger: "create component", "add component", "new component"
- Functions: component_generator.py, style_generator.py, test_generator.py
- Templates: component-template.tsx, test-template.spec.tsx
- Examples: example-functional-component.tsx, example-hook.ts
- Auto-invokes: When user wants to create React/Vue/etc component
2. **backend-endpoint**
- Trigger: "add endpoint", "create API", "new route"
- Functions: endpoint_generator.py, route_validator.py, middleware_generator.py
- Templates: endpoint-template.ts, test-template.spec.ts
- Examples: rest-endpoint.ts, graphql-resolver.ts
- Auto-invokes: When user wants to add API endpoint
3. **database-migration**
- Trigger: "create migration", "add table", "modify schema"
- Functions: migration_generator.py, schema_validator.py, rollback_generator.py
- Templates: migration-template.sql, rollback-template.sql
- Examples: add-table-migration.sql, modify-column-migration.sql
- Auto-invokes: When user wants to change database schema
4. **backend-test**
- Trigger: "write test for", "add test", "test this"
- Functions: test_generator.py, fixture_generator.py, mock_generator.py
- Templates: unit-test-template.spec.ts, integration-test-template.spec.ts
- Examples: api-test-example.ts, service-test-example.ts
- Auto-invokes: When user wants to write backend tests
5. **frontend-test**
- Trigger: "test this component", "write component test"
- Functions: component_test_generator.py, snapshot_generator.py
- Templates: component-test-template.spec.tsx, e2e-test-template.spec.ts
- Examples: button-test-example.tsx, form-test-example.tsx
- Auto-invokes: When user wants to test frontend components
**How v2.2 Works**:
User: "We keep adding React components with similar structure. Automate this."
→ nav-skill-creator auto-invokes → Task agent explores: "Find all React component patterns" → Agent returns: "Components in src/components/, use hooks, styled-components, tests in tests/" → nav-skill-creator generates: skills/frontend-component/ ├── SKILL.md (with auto-invoke triggers) ├── functions/ │ ├── component_generator.py (extracts project patterns) │ ├── style_generator.py (styled-components boilerplate) │ └── test_generator.py (follows project test patterns) ├── examples/ │ ├── example-button.tsx (from actual codebase) │ └── example-hook.ts (from actual codebase) └── templates/ ├── component-template.tsx (based on project conventions) └── test-template.spec.tsx (based on project test style)
→ Skill added to .claude/skills/ → Documentation updated → User confirms: "Looks good!"
Next time: User: "Create a UserCard component" → frontend-component skill auto-invokes → Uses component_generator.py with component-template.tsx → Follows project conventions automatically → Output: Consistent, tested, ready to use
**Tasks**:
- [ ] Use nav-skill-creator to generate frontend-component skill
- [ ] Use nav-skill-creator to generate backend-endpoint skill
- [ ] Use nav-skill-creator to generate database-migration skill
- [ ] Use nav-skill-creator to generate backend-test skill
- [ ] Use nav-skill-creator to generate frontend-test skill
- [ ] Test each generated skill works correctly
- [ ] Refine nav-skill-creator based on generation quality
- [ ] Update documentation with project-specific skills
- [ ] Commit v2.2
**Token Impact**:
- 6 core skills + 5 project skills = 11 skills
- 11 × 50 tokens = 550 tokens baseline
- Still <1k tokens for massive automation capability
**Timeline**: 1 week (iterative, based on real usage)
### v2.3 (Future - Optimization)
**Focus**: Optimize based on real-world usage
**Tasks**:
- [ ] Analyze which skills used most frequently
- [ ] Optimize predefined functions for speed
- [ ] Add more examples based on common patterns
- [ ] Improve auto-invocation triggers based on user feedback
- [ ] Add skill versioning for breaking changes
- [ ] Create skill analytics (usage tracking)
**Timeline**: Ongoing
### v3.0 (Long-term - Skills-Only)
**Focus**: Remove commands, fully skills-based
**Breaking Changes**:
- Remove all /nav:* commands
- Skills-only architecture
- Backward compatibility via migration guide
**Benefits**:
- Simpler UX (no commands vs skills confusion)
- Full auto-invocation
- Self-improving system
- Project-specific automation everywhere
**Timeline**: 6+ months (after v2.x proven)
---
## Testing Plan
1. **Unit test functions**
```bash
python skills/nav-task/functions/task_id_generator.py
python skills/nav-task/functions/task_formatter.py --help
Test skill invocation
- Load Navigator v2.1 locally (symlink)
- Test auto-invocation: "Help me start a new task"
- Verify functions are used correctly
- Check output matches templates
Test nav-skill-creator
- Request: "Create a skill for adding API endpoints"
- Verify skill directory created
- Test generated skill works
- Check documentation updated
Token measurement
- Run session_stats.py before/after
- Verify only 300 tokens baseline
- Confirm instructions load on-demand
Implementation Tasks
- Create functions for nav-task
- Create functions for nav-sop
- Create functions for nav-marker
- Create functions for nav-compact
- Add examples to nav-sop
- Create nav-skill-creator skill
- Update all SKILL.md files with asset references
- Test all functions work correctly
- Test skills invoke and use functions properly
- Update CLAUDE.md with v2.1 features
- Update README.md with skill enhancements
- Commit v2.1
- Setup local testing (symlink approach)
- Test thoroughly before push
- Push to GitHub
- Update marketplace
Success Metrics
Functionality:
- All functions executable and working
- Skills auto-invoke correctly
- Functions integrate seamlessly with skills
- Output matches templates/examples
Token Efficiency:
- Baseline ≤ 300 tokens (6 skill descriptions)
- Functions don't pollute context
- Examples loaded only on invocation
User Experience:
- Skills "just work" out of box
- Consistent output across invocations
- nav-skill-creator can generate working skills
- Less manual prompt engineering needed
Open Questions
Function language choice: Python vs Bash?
- Python: More powerful, better for complex logic
- Bash: Lighter, faster for simple operations
- Decision: Use Python for consistency
Template format: Mustache vs Jinja2 vs simple string replacement?
- Decision: Start with simple string templates, upgrade if needed
Example storage: In-skill vs centralized?
- Decision: In-skill for portability
nav-skill-creator scope: Generate full skills or just templates?
- Decision: Generate full working skills with basic functions
Related Tasks
- TASK-07: Skills migration (completed in v2.0)
- TASK-06: Session statistics (completed in v2.0)
- TASK-01: Session start PM integration (in progress)
Notes
- Video clearly shows skills >> MCP for token efficiency when multiple tools needed
- Predefined functions are key differentiator vs basic prompts
- Self-improving pattern (skill-creator) is extremely powerful
- Our v2.0 architecture is solid, just needs function enhancement
- Agents vs Skills are complementary, not competitive (hybrid pattern)
- Don't create broad "engineer" skills - create specific task skills
- Project-specific skills (v2.2) will be generated by nav-skill-creator (v2.1)
Summary: Navigator Evolution Roadmap
The Vision
Navigator transforms from documentation system → self-improving development assistant
v2.0 (Now) v2.1 (Next) v2.2 (Soon) v3.0 (Future)
├─ Core skills ├─ + Functions ├─ + Project skills ├─ Skills-only
├─ Commands ├─ + Self-improving ├─ Full automation ├─ No commands
├─ Agent usage ├─ Agents vs Skills ├─ Pattern enforcement ├─ 100% auto
└─ 250 tokens baseline └─ 300 tokens baseline └─ 550 tokens baseline └─ Self-learning
↓ ↓ ↓
Predefined functions Generated skills Fully autonomous
Templates & examples Auto-invocation Project-specific
nav-skill-creator Hybrid workflow Zero manual work
Key Architectural Decisions
1. Hybrid Pattern (Agents + Skills)
- Agents for research (separate context, 60-80% savings)
- Skills for execution (main context, consistency)
- Both auto-invoke based on descriptions
- Complementary, not competitive
2. Specific Skills Over Broad Skills
- ✅ frontend-component, backend-endpoint, database-migration
- ❌ frontend-engineer, backend-engineer
- Clear triggers, clear outputs
3. Progressive Disclosure at Three Levels
- Level 1: Description (~50 tokens, always loaded)
- Level 2: Instructions (2-5k tokens, on-demand)
- Level 3: Functions/templates (0 tokens, on-demand)
4. Self-Improving via nav-skill-creator
- Analyzes codebase patterns
- Generates project-specific skills
- Continuous improvement loop
- Zero manual pattern documentation
Token Efficiency Evolution
Traditional approach:
Load all docs: 150k tokens
Context: 200k total
Available for work: 50k (25%)
Navigator v2.0:
Core skills baseline: 250 tokens
Context: 200k total
Available for work: 199k (99.5%)
Navigator v2.1:
Core + creator baseline: 300 tokens
Functions/examples: On-demand
Available for work: 199k (99.5%)
Navigator v2.2:
11 skills baseline: 550 tokens
Project automation: On-demand
Available for work: 199k (99.7%)
Real-World Impact Example
Before Navigator:
User: "Add user profile page"
→ Manual read: package.json, src/pages/*.tsx, src/components/*.tsx, src/routes.ts
→ Manual understand: routing patterns, component structure, state management
→ Manual implement: following inconsistent patterns
→ Manual test: write tests manually
→ Token cost: 100k+ tokens
→ Time: 2 hours
→ Consistency: Variable
After Navigator v2.2:
User: "Add user profile page"
→ [Agent] Explores routing (if needed)
Returns: "React Router in src/routes.ts, pages in src/pages/"
Token cost: 200 tokens
→ [Skill] frontend-component auto-invokes
Uses: page_generator.py, route_updater.py, test_generator.py
Uses: page-template.tsx, test-template.spec.tsx
Generates: ProfilePage.tsx, ProfilePage.spec.tsx, updated routes.ts
Token cost: 5k tokens
→ Total: 5.2k tokens (95% reduction)
→ Time: 5 minutes
→ Consistency: Perfect (follows project patterns)
Success Metrics
v2.1 Success:
- nav-skill-creator can generate working skills
- Predefined functions reduce manual work by 50%
- All core skills have functions/examples
- Token baseline ≤ 300 tokens
v2.2 Success:
- 5+ project-specific skills generated
- Skills auto-invoke 80%+ of the time
- Generated code follows project patterns 95%+
- Token baseline ≤ 550 tokens
v3.0 Success:
- Zero manual commands needed
- Skills learn from every interaction
- New developers productive in 1 hour
- 10x productivity vs traditional development
Next Actions
Immediate (v2.1):
- Create predefined functions for existing skills
- Build nav-skill-creator skill
- Update CLAUDE.md with Agents vs Skills matrix
- Test locally before push
Short-term (v2.2):
- Use nav-skill-creator for common patterns
- Generate frontend-component skill
- Generate backend-endpoint skill
- Iterate based on real usage
Long-term (v3.0):
- Remove commands entirely
- Full skills-based architecture
- Self-learning system
- Project-specific automation everywhere