alekspetrov/nav-skill-creator

Navigator Skill Creator

Create project-specific skills by analyzing codebase patterns and automating repetitive workflows.

When to Invoke

Auto-invoke when user mentions:

• "Create a skill for [pattern]"
• "Automate this workflow"
• "We keep doing X manually"
• "Enforce this pattern"
• "Generate boilerplate for [feature type]"
• "We need consistency for [task type]"

What This Does

1. Analyzes codebase to understand project patterns
2. Identifies best practices from existing code
3. Generates skill with:
   • Auto-invocation triggers
   • Predefined functions
   • Templates
   • Examples
4. Tests the generated skill
5. Documents the new skill

Execution Steps

Step 1: Understand Skill Request

Ask clarifying questions:

• What pattern/workflow to automate?
• What triggers should invoke this skill?
• What output format is expected?
• Are there existing examples in the codebase?

Example dialogue:

User: "Create a skill for adding React components"
Assistant: "I'll analyze your codebase to understand React component patterns.
- What directory are components in?
- Do you use TypeScript or JavaScript?
- Do you want tests generated automatically?
- Are there style files (CSS/SCSS) per component?"

Step 2: Analyze Codebase Patterns

Use Task agent to explore (saves 60-80% tokens):

Use Task agent with subagent_type=Explore:
"Find existing [pattern type] in codebase:
 - Locate all [files matching pattern]
 - Identify common structure
 - Extract best practices
 - Find configuration files
 - Return summary of findings"

What to look for:

• File naming conventions (kebab-case, PascalCase, etc.)
• Directory structure patterns
• Import/export patterns
• Testing patterns
• Configuration patterns
• Documentation patterns

Example for React components:

Task agent finds:
- Components in src/components/
- PascalCase naming (UserProfile.tsx)
- Co-located tests (UserProfile.test.tsx)
- Props interfaces defined above component
- Export default at bottom

Step 3: Design Skill Structure

Determine skill metadata:

name: [project]-[pattern-type]
description: [When to auto-invoke + what it does]
allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Task]
version: 1.0.0

Plan directory structure:

skills/[skill-name]/
├── SKILL.md              # Main instructions
├── functions/            # Python helper scripts
│   └── [generator].py
├── examples/             # Reference implementations
│   └── [example].[ext]
└── templates/            # Output format templates
    └── [template].[ext]

Design predefined functions:

• What repetitive logic can be automated?
• What validation should be enforced?
• What formatting ensures consistency?

Example functions for frontend-component skill:

• component_generator.py - Generate component boilerplate
• test_generator.py - Generate test file
• style_generator.py - Generate style file
• name_validator.py - Validate component naming

Step 4: Generate Skill Files

4.1 Create SKILL.md

---
name: [skill-name]
description: [Auto-invocation triggers + purpose]
allowed-tools: [List of tools]
version: 1.0.0
---

# [Skill Title]

[Brief description of what this skill does]

## When to Invoke

Auto-invoke when user says:
- "[trigger phrase 1]"
- "[trigger phrase 2]"
- "[trigger phrase 3]"

## What This Does

1. [Step 1 overview]
2. [Step 2 overview]
3. [Step 3 overview]

## Execution Steps

### Step 1: [Step Name]

[Detailed instructions for this step]

**Use predefined function**: `functions/[function-name].py`

4.2 Create Predefined Functions

# functions/[generator].py

def generate_[output](name, config):
    """
    Generate [output type] based on project patterns.

    Args:
        name: [Description]
        config: [Description]

    Returns:
        [output]: [Description]
    """
    # Implementation based on codebase analysis
    pass

4.3 Create Examples

examples/
└── [reference-implementation].[ext]
    - Real example from codebase (best practice)
    - Shows expected structure
    - Demonstrates conventions

4.4 Create Templates

templates/
└── [output-template].[ext]
    - Skeleton structure with placeholders
    - ${VAR_NAME} for substitution
    - Comments explaining sections

Step 5: Test Generated Skill

5.1 Verify skill loads:

# In project root
grep -r "name: [skill-name]" skills/

5.2 Test auto-invocation:

In Claude Code conversation:
"[Use one of the auto-invoke trigger phrases]"

Expected: Skill should be detected and loaded

5.3 Test execution:

• Run through skill steps
• Verify functions work correctly
• Check output matches template
• Validate generated code follows patterns

5.4 Iterate if needed:

• Fix function bugs
• Improve templates
• Add missing examples
• Clarify instructions

Step 6: Document New Skill

Update project documentation:

1. CLAUDE.md - Add to skills section:

#### [Skill Name]
**Auto-invoke**: "[trigger phrase]"
**Purpose**: [What it does]
**Generates**: [Output type]

2. README.md - Add to skills list:

- **[skill-name]**: [Brief description]

3. .agent/system/plugin-patterns.md - Add to skill registry:

### [Skill Name]
**Created**: [Date]
**Pattern**: [What pattern it enforces]
**Functions**: [List of predefined functions]

Register in plugin.json (if applicable):

{
  "skills": [
    {
      "name": "[skill-name]",
      "path": "skills/[skill-name]/SKILL.md"
    }
  ]
}

---

Example Workflows

Example 1: Create Skill for Adding API Endpoints

User: "Create a skill for adding REST API endpoints"

Execution:

1. Clarify:

   • Which framework? (Express, Fastify, etc.)
   • Where are routes defined?
   • Authentication required?
   • Testing strategy?

2. Analyze (via Task agent):

   Find existing API endpoints:
   - Routes in api/routes/
   - Controllers in api/controllers/
   - Middleware in api/middleware/
   - Tests in tests/api/
   

3. Design:

   name: backend-api-endpoint
   description: Add new REST API endpoint following project conventions. Use when user says "add endpoint", "create API", or "new route".
   allowed-tools: Read, Write, Edit, Grep, Glob, Bash
   

4. Generate:

   skills/backend-api-endpoint/
   ├── SKILL.md
   ├── functions/
   │   ├── endpoint_generator.py
   │   └── route_validator.py
   ├── examples/
   │   └── user-endpoint.ts
   └── templates/
       ├── route-template.ts
       └── test-template.spec.ts
   

5. Test:

   User: "Add a POST /posts endpoint"
   Skill: Auto-invoked, generates route + controller + test
   Verify: Files follow project conventions
   

6. Document: Update CLAUDE.md, README.md, plugin-patterns.md

Example 2: Create Skill for React Components

User: "Automate creating new React components"

Execution:

1. Clarify:

   • TypeScript or JavaScript?
   • Functional or class components?
   • Style approach? (CSS modules, styled-components, etc.)
   • Test library? (Jest, React Testing Library, etc.)

2. Analyze (via Task agent):

   Find React components:
   - Components in src/components/
   - PascalCase naming
   - TypeScript (.tsx)
   - CSS modules (.module.css)
   - Tests with RTL
   

3. Design:

   name: frontend-component
   description: Create new React component with TypeScript, styles, and tests. Use when user says "create component", "add component", or "new React component".
   allowed-tools: Read, Write, Edit, Grep, Glob, Bash
   

4. Generate:

   skills/frontend-component/
   ├── SKILL.md
   ├── functions/
   │   ├── component_generator.py
   │   ├── test_generator.py
   │   └── style_generator.py
   ├── examples/
   │   ├── Button.tsx
   │   └── Button.test.tsx
   └── templates/
       ├── component-template.tsx
       ├── test-template.test.tsx
       └── style-template.module.css
   

5. Test:

   User: "Create a UserProfile component"
   Skill: Auto-invoked, generates component + test + styles
   Verify: Props interface, exports, naming correct
   

6. Document: Update project docs

---

Output Format

After generating skill, show summary:

✅ Skill Created: [skill-name]

Structure:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 skills/[skill-name]/
   ├── SKILL.md
   ├── functions/
   │   └── [N functions created]
   ├── examples/
   │   └── [N examples added]
   └── templates/
       └── [N templates created]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Auto-Invocation Triggers:
- "[trigger 1]"
- "[trigger 2]"
- "[trigger 3]"

Next Steps:
1. Test the skill: "[example trigger phrase]"
2. Iterate if needed
3. Documentation updated

Try it now: "[example usage]"

---

Best Practices

Pattern Analysis

• Use Task agent for codebase exploration (saves 60-80% tokens)
• Look at 3-5 examples minimum (find patterns vs outliers)
• Identify conventions explicitly followed
• Note edge cases in comments

Skill Design

• Keep skills focused (one pattern per skill)
• Clear auto-invocation triggers (3-5 phrases)
• Minimal tools needed (add only what's required)
• Progressive disclosure (details in functions, not main instructions)

Function Creation

• One function = one responsibility
• Type hints and docstrings required
• Handle errors gracefully
• Return structured data (not print statements)

Template Design

• Use clear placeholders (${VAR_NAME})
• Include comments explaining sections
• Follow project style guide
• Provide sensible defaults

Testing

• Test with real project context
• Verify auto-invocation works
• Check output against best practices
• Iterate based on actual usage

---

Common Patterns to Automate

Backend Patterns

• REST API endpoints
• GraphQL resolvers
• Database migrations
• Background jobs
• Middleware functions
• Authentication guards

Frontend Patterns

• React/Vue/Svelte components
• Redux/Vuex store modules
• API client functions
• Form validation schemas
• Route definitions
• Style component creation

Infrastructure Patterns

• Docker service configs
• CI/CD pipeline steps
• Deployment scripts
• Environment configs
• Monitoring setup

Documentation Patterns

• API documentation
• Component documentation
• Architecture decision records (ADRs)
• Runbook entries
• Changelog entries

---

Troubleshooting

Skill Not Auto-Invoking

Problem: Skill created but doesn't trigger automatically

Solutions:

1. Check description has clear trigger phrases
2. Verify plugin.json includes skill registration
3. Reload Claude Code to refresh skill index
4. Test with exact trigger phrase from description

Functions Not Executing

Problem: Predefined functions throw errors

Solutions:

1. Check Python syntax is valid
2. Verify function imports are correct
3. Test function independently first
4. Check error messages in execution logs

Templates Not Matching Output

Problem: Generated code doesn't match project conventions

Solutions:

1. Re-analyze codebase for missed patterns
2. Update templates with correct structure
3. Add more examples showing variations
4. Validate against linter/formatter

Skill Too Broad

Problem: Skill tries to do too much

Solutions:

1. Split into multiple focused skills
2. Remove optional features to separate skills
3. Keep core pattern simple
4. Add extensions as separate skills

---

Success Criteria

This skill succeeds when:

• [ ] New skill auto-invokes correctly
• [ ] Generated output follows project conventions
• [ ] Functions execute without errors
• [ ] Templates produce valid code
• [ ] Examples are clear and relevant
• [ ] Documentation is updated
• [ ] Skill saves time vs manual work

---

The skill-creator is Navigator's self-improving engine - it learns your patterns and automates them 🔄