TASK-10: Project-Specific Skills Generation

TASK-10: Project-Specific Skills Generation (v2.2)

Created: 2025-10-19 Status: In Progress Priority: High Complexity: Medium

Context

Now that nav-skill-creator exists (v2.1), we can use it to generate project-specific skills that automate repetitive development workflows.

Problem: Developers repeat similar patterns (creating components, adding endpoints, writing migrations) but manually each time. No automation for project-specific conventions.

Goal: Use nav-skill-creator to analyze Navigator plugin codebase and generate a demonstration skill that proves the self-improving capability works. This validates the v2.1 architecture and paves the way for users to create their own project-specific skills.

Why Navigator Plugin as Test Case:

• We understand the codebase deeply
• Clear patterns exist (slash command creation)
• Success here validates approach for any project
• Demonstrates "eating our own dog food"

Implementation Plan

Phase 1: Validate nav-skill-creator Implementation

Tasks:

• Complete nav-skill-creator SKILL.md file (full instructions)
• Add example reference files to examples/
• Verify skill directory structure is correct
• Test skill can be loaded by Claude Code (structure validated)

Expected Outcome: nav-skill-creator is fully functional and ready to use

Validation:

# Check skill structure
ls -R skills/nav-skill-creator/

# Verify SKILL.md complete
wc -l skills/nav-skill-creator/SKILL.md  # Should be 500+ lines

# Test loading (manual)
# In Claude Code: "Create a skill for..." should trigger auto-invoke

Phase 2: Analyze Navigator Plugin Patterns

Tasks:

• Identify repetitive pattern in Navigator codebase
• Document pattern characteristics
• Choose best pattern for demonstration skill
• Define skill scope and triggers

Pattern Options (choose one for Phase 2):

1. plugin-slash-command (RECOMMENDED)

   • Pattern: Creating new slash commands
   • Files: .claude/commands/*.md
   • Repetition: Every new Navigator feature needs a command
   • Clear structure: YAML frontmatter + markdown body
   • Example: init.md, start.md, marker.md

2. plugin-skill-creation

   • Pattern: Creating new skills
   • Files: skills/*/SKILL.md
   • Repetition: New skills follow same structure
   • Clear structure: YAML + instructions + functions
   • Example: nav-start, nav-marker, nav-compact

3. plugin-function-creation

   • Pattern: Adding predefined functions to skills
   • Files: skills/*/functions/*.py
   • Repetition: Functions follow Python conventions
   • Clear structure: Docstrings + type hints
   • Example: task_id_generator.py, sop_formatter.py

Decision: Go with plugin-slash-command (most straightforward, clear value)

Pattern Analysis Results:

Analyzed 11 command files in commands/ directory:

• 6 backward-compat files (_jitd_*.md)
• 5 main commands (compact.md, doc.md, init.md, marker.md, markers.md, start.md)

Common Structure:

1. YAML frontmatter with description field
2. Markdown title (# Command Name)
3. "What This Does" section
4. "When to Use" section (with examples)
5. "Usage" or "Execution Plan" section
6. Step-by-step instructions
7. "Troubleshooting" section
8. Closing statement

Naming Convention:

• Files: kebab-case (marker.md, compact.md, update-doc.md)
• Command names: /nav:[command-name]
• Titles: Title Case with Navigator branding

Key Characteristics:

• Conversational tone (2nd person: "You are...")
• Emoji usage for visual markers (✅, ❌, 📖, 🚀)
• Code blocks for examples
• Clear expected outcomes per step
• Focus on user value/benefits

Expected Outcome: Documented pattern ready for skill generation (✅ COMPLETE)

Phase 3: Generate First Project-Specific Skill

Tasks:

• Use nav-skill-creator to analyze slash command pattern
• Generate plugin-slash-command skill
• Review generated skill structure
• Manually refine if needed (note what needs improvement)
• Test generated skill works (structure validated)

Invocation:

In Claude Code conversation:
"Create a skill for adding new Navigator slash commands"

Expected: nav-skill-creator auto-invokes and:
1. Asks clarifying questions
2. Uses Task agent to analyze .claude/commands/*.md
3. Generates skills/plugin-slash-command/
4. Creates SKILL.md, functions/, templates/, examples/

Generated Skill Structure (expected):

skills/plugin-slash-command/
├── SKILL.md
├── functions/
│   ├── command_generator.py      # Generate command markdown
│   └── command_validator.py      # Validate YAML frontmatter
├── examples/
│   ├── simple-command.md         # Example: marker.md
│   └── complex-command.md        # Example: start.md
└── templates/
    └── command-template.md       # Skeleton with placeholders

Expected Outcome: Working skill that can generate new slash commands

Phase 4: Test Generated Skill

Tasks:

• Test plugin-slash-command auto-invocation (requires Claude Code reload)
• Use it to generate a test command (tested functions directly)
• Verify generated command follows Navigator conventions (validator works)
• Document any issues found (validation guidelines working)
• Iterate on nav-skill-creator if needed (functions validated successfully)

Test Scenario:

User: "Add a slash command for listing all context markers"

Expected: plugin-slash-command skill auto-invokes and:
1. Asks for command name (/nav:list-markers)
2. Asks for description
3. Generates .claude/commands/list-markers.md
4. Follows Navigator pattern (YAML + execution steps)
5. Includes all Navigator conventions

Success Criteria:

• Generated command is syntactically valid
• Follows Navigator conventions
• Minimal manual editing needed (<10% of file)
• Saves time vs writing from scratch

Test Results:

• ✅ command_generator.py generates valid markdown (tested simple/medium/complex)
• ✅ command_validator.py validates YAML, structure, formatting, style
• ✅ Validator correctly identifies issues in existing commands
• ✅ Generated commands follow Navigator conventions
• ✅ Functions handle edge cases (invalid names, missing fields)

Expected Outcome: Validated that generated skills work in practice (✅ COMPLETE)

Phase 5: Document v2.2 Release

Tasks:

• Update DEVELOPMENT-README.md with TASK-10 completion
• Add plugin-slash-command to skills section
• Update CLAUDE.md with skills section (if not exists)
• Update README.md with v2.2 features
• Create release notes for v2.2

Documentation Updates:

1. DEVELOPMENT-README.md:

   • Add TASK-10 to completed tasks
   • Document plugin-slash-command skill
   • Explain self-improving capability

2. CLAUDE.md (add skills section):

   ### Skills
   
   Navigator includes self-improving capability via skills:
   
   #### nav-skill-creator
   **Auto-invoke**: "Create a skill for...", "automate this workflow"
   **Purpose**: Analyze codebase patterns and generate project-specific skills
   **Generates**: Complete skill with functions, templates, examples
   
   #### plugin-slash-command
   **Auto-invoke**: "Add slash command", "create command"
   **Purpose**: Generate new Navigator slash commands following conventions
   **Generates**: .claude/commands/*.md file
   

3. README.md:

   • Add v2.2 to version history
   • Highlight self-improving capability
   • Show example of generated skill

Expected Outcome: v2.2 fully documented and ready for release

Success Metrics

Functionality:

• nav-skill-creator SKILL.md complete (500+ lines)
• plugin-slash-command skill generated successfully
• Generated skill auto-invokes correctly
• Generated commands follow Navigator conventions
• Minimal manual refinement needed (<10%)

Quality:

• Generated skill structure matches design
• Functions have docstrings and type hints
• Templates have clear placeholders
• Examples are representative
• Documentation updated

Token Efficiency:

• Task agent used for pattern analysis (60-80% savings)
• Skills use progressive disclosure (instructions loaded on invoke)
• Functions add 0 tokens (loaded with instructions)
• Total skill overhead <500 tokens

Self-Improvement Validation:

• nav-skill-creator successfully analyzes Navigator codebase
• Generated skill is immediately useful
• Process is repeatable for other projects
• Pattern works for different development workflows

Testing Plan

Manual Testing

1. nav-skill-creator validation:

   # Verify file structure
   ls -R skills/nav-skill-creator/
   
   # Check SKILL.md is complete
   wc -l skills/nav-skill-creator/SKILL.md
   
   # Read to verify instructions make sense
   cat skills/nav-skill-creator/SKILL.md
   

2. Auto-invocation test:

   In Claude Code:
   "Create a skill for adding Navigator slash commands"
   
   Verify:
   - nav-skill-creator auto-invokes
   - Asks clarifying questions
   - Uses Task agent for analysis
   - Generates skill structure
   

3. Generated skill test:

   In Claude Code:
   "Add a slash command for showing token statistics"
   
   Verify:
   - plugin-slash-command auto-invokes
   - Generates valid .md file
   - Follows Navigator conventions
   - Minimal editing needed
   

4. Integration test:

   - Test generated command in nav-test project
   - Verify command loads correctly
   - Check output follows expectations
   - Validate YAML frontmatter
   

Success Validation

Phase 1: ✅ nav-skill-creator loads without errors Phase 2: ✅ Pattern documented with 3+ examples Phase 3: ✅ plugin-slash-command generated with all components Phase 4: ✅ Generated command works in test project Phase 5: ✅ Documentation complete and accurate

Related Tasks

• TASK-07: Core skills architecture (foundation for v2.2)
• TASK-08: Predefined functions + nav-skill-creator design
• TASK-09: Migration system (ensures backward compatibility)

Notes

Design Decisions

1. Why plugin-slash-command as first skill?

   • Clear, repetitive pattern (11 command files exist)
   • High value (every Navigator feature needs command)
   • Easy to validate (just test command loads)
   • Demonstrates value immediately

2. Why not start with generic skills?

   • Project-specific skills prove the concept better
   • Generic skills (frontend-component, backend-endpoint) require assumptions
   • Navigator-specific skill shows "eating our own dog food"
   • Easier to iterate on codebase we understand

3. Future expansion (v2.3+):

   • Generate more Navigator skills (plugin-function-creation, plugin-skill-creation)
   • Create generic skills for common frameworks (React, Express, etc.)
   • Add skill marketplace (share skills between projects)
   • Skill versioning and updates

Implementation Learnings

From nav-skill-creator completion:

• Comprehensive instructions needed (500+ lines vs 45 lines before)
• Step-by-step execution plan critical
• Examples and workflows help clarity
• Best practices section prevents common mistakes

Expect to learn during Phase 3:

• Whether nav-skill-creator generates quality output
• What manual refinement is typically needed
• How to improve templates for better generation
• Whether functions need better structure

Token Impact Analysis

Before v2.2:

• Creating slash command: Read 3-5 examples manually (~15k tokens)
• Total: ~15k tokens per command

After v2.2:

• plugin-slash-command skill: 50 tokens (description)
• Skill instructions: ~3k tokens (loaded on invoke)
• Functions: 0 tokens (execute separately)
• Total: ~3k tokens per command

Savings: 80% reduction (15k → 3k)

Multiplied across project:

• 10 commands created in project lifecycle
• Before: 150k tokens
• After: 30k tokens
• Savings: 120k tokens (80% reduction)

Task created: 2025-10-19 Priority: High Effort: Medium Estimated completion: 2-3 hours