TASK-08: Skills Enhancements & Hybrid Architecture (v2.1-v2.2)

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

1. Skill descriptions always loaded (~70 tokens each)

   • Navigator: 5 skills × ~50 tokens = 250 tokens (GOOD ✅)
   • This is acceptable overhead for auto-invocation capability

2. Progressive disclosure works correctly

   • Description: Always in context
   • Instructions (SKILL.md body): Loaded on invocation only
   • Assets/functions: Loaded with instructions (0 extra tokens)

3. Predefined functions make skills more powerful

   • Example: slack-gif-creator includes Python functions
   • Functions are imported and used by instructions
   • Enables complex workflows out-of-box

4. Reference files ensure consistency

   • Example implementations loaded as context
   • Templates guide output format
   • Makes agent output more predictable

5. Self-improving codebase pattern

   • skill-creator skill analyzes code and generates new skills
   • Skills gather best practices before implementing
   • Continuous improvement loop

6. 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:

1. Predefined functions - Only nav-start has session_stats.py, others don't
2. Example references - No example outputs to guide consistency
3. Templates - Not explicitly referenced in skills (exist in /templates but not linked)
4. Self-improvement capability - No skill to analyze codebase and create new skills
5. Asset organization - No clear pattern for functions/examples/templates per skill
6. Agents vs Skills clarity - CLAUDE.md mentions agents but doesn't explain when to use each
7. 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

2. task_formatter.py - Format task markdown with proper structure

   python skills/nav-task/functions/task_formatter.py \
     --title "Feature Name" \
     --priority high \
     --complexity medium
   

3. index_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 plan
• task-archive-example.md - Completed task documentation

Templates

Available in ./templates/:

• task-plan-template.md - Starter template for new tasks
• task-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

2. 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

3. Test nav-skill-creator

   • Request: "Create a skill for adding API endpoints"
   • Verify skill directory created
   • Test generated skill works
   • Check documentation updated

4. 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

1. Function language choice: Python vs Bash?

   • Python: More powerful, better for complex logic
   • Bash: Lighter, faster for simple operations
   • Decision: Use Python for consistency

2. Template format: Mustache vs Jinja2 vs simple string replacement?

   • Decision: Start with simple string templates, upgrade if needed

3. Example storage: In-skill vs centralized?

   • Decision: In-skill for portability

4. 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):

1. Create predefined functions for existing skills
2. Build nav-skill-creator skill
3. Update CLAUDE.md with Agents vs Skills matrix
4. Test locally before push

Short-term (v2.2):

1. Use nav-skill-creator for common patterns
2. Generate frontend-component skill
3. Generate backend-endpoint skill
4. Iterate based on real usage

Long-term (v3.0):

1. Remove commands entirely
2. Full skills-based architecture
3. Self-learning system
4. Project-specific automation everywhere