dance-lessons-coach/.vibe/skills/skill-creator/references/ADVANCED_FEATURES.md

# Advanced Skill Creator Features

## Known Issues and Troubleshooting

### Nested Path Creation Issue

**Symptom**: Skills created in incorrect nested paths like `.vibe/skills/.vibe/skills/skill-name`

**Cause**: Running `create_skill.sh` from within the `.vibe/skills/` directory causes relative path resolution issues.

**Solution**: 
1. Always run the script from project root
2. Use absolute paths when necessary
3. The script now includes validation to detect and prevent this issue

**Prevention**: Added path validation in `create_skill.sh`:
```bash
# Validate path - ensure we're not creating nested .vibe directories
if [[ "$SKILL_DIR" == *".vibe/.vibe"* ]]; then
    echo "❌ Error: Detected nested .vibe path: $SKILL_DIR"
    exit 1
fi
```

### Workaround
If you encounter this issue:
```bash
# Move the skill to correct location
mv .vibe/skills/.vibe/skills/your-skill .vibe/skills/your-skill

# Update any internal path references
find .vibe/skills/your-skill -type f -exec sed -i '' 's|.vibe/skills/.vibe/skills|.vibe/skills|g' {} +
```

## Skill Versioning and Updates

### Version Management

```markdown
## Version History

### v1.0.0 (Current)
- Initial release
- Basic skill scaffold generation
- Specification validation
- Best practices guide

### v1.1.0 (Planned)
- Skill versioning support
- Update notification system
- Deprecation warnings
- Migration guides

### v2.0.0 (Future)
- Interactive skill creation
- Visual skill editor
- AI-assisted skill generation
- Team collaboration features
```

### Versioning Strategy

**Semantic Versioning:** `MAJOR.MINOR.PATCH`
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

**Version Fields:**
```yaml
# SKILL.md
metadata:
  version: "1.0.0"
  compatibility: ">=1.0.0"
  deprecated: false
  successor: ""
```

## Skill Dependencies

### Dependency Management

```markdown
## Dependencies

### Required Skills
- `skill_creator` (this skill) v1.0.0+

### Optional Skills
- `bdd_testing` v1.0.0+ (for BDD testing)
- `documentation` v1.0.0+ (for doc generation)

### System Requirements
- Go 1.26+
- Bash 4.0+
- Git 2.0+
```

### Dependency Specification

```yaml
# SKILL.md
metadata:
  dependencies:
    required:
      - name: skill_creator
        version: ">=1.0.0"
    optional:
      - name: bdd_testing
        version: ">=1.0.0"
    system:
      - name: go
        version: ">=1.26"
      - name: bash
        version: ">=4.0"
```

## Skill Lifecycle Management

### Skill States

```mermaid
graph LR
    A[Draft] -->|Validate| B[Active]
    B -->|Deprecate| C[Deprecated]
    C -->|Remove| D[Archived]
```

**State Transitions:**

```markdown
### Skill Lifecycle

1. **Draft**: Under development, not ready for use
   - Prefix: `draft-`
   - Example: `draft-my-skill`

2. **Active**: Production-ready, actively maintained
   - No prefix
   - Example: `my-skill`

3. **Deprecated**: Replaced by newer version
   - Metadata: `deprecated: true`
   - Metadata: `successor: "new-skill"`

4. **Archived**: No longer maintained
   - Move to `archived/` directory
   - Example: `.vibe/skills/archived/old-skill/`
```

## Advanced Skill Patterns

### Composite Skills

```markdown
## Composite Skill Pattern

Combine multiple skills for complex workflows.

### Example: Full-Stack Testing

```yaml
# SKILL.md
name: fullstack-testing
description: Combines BDD, unit, and integration testing
metadata:
  composes:
    - bdd_testing
    - unit_testing
    - integration_testing
```

### Implementation

```bash
# Create composite skill
.vibe/skills/skill_creator/scripts/create_composite_skill.sh fullstack-testing \
  bdd_testing unit_testing integration_testing
```

### Workflow

```markdown
## Testing Workflow

1. **BDD Tests**: Validate external behavior
2. **Unit Tests**: Verify individual components
3. **Integration Tests**: Check component interactions
4. **Report**: Combine all test results
```
```

## Skill Testing and Validation

### Test Coverage

```markdown
## Test Coverage

### Unit Tests
- Validate individual skill components
- Test scripts, templates, and utilities

### Integration Tests
- Verify skill works with other skills
- Test dependency resolution
- Validate workflow execution

### End-to-End Tests
- Complete skill lifecycle testing
- Creation → Validation → Usage → Update → Deprecation
```

### Test Automation

```bash
#!/bin/bash
# scripts/test-skill.sh

set -e

echo "Testing skill: $1"

# Validate structure
.vibe/skills/skill_creator/scripts/validate_skill.sh "$1"

# Run unit tests if present
if [ -f "$1/tests/unit_test.sh" ]; then
    echo "Running unit tests..."
    "$1/tests/unit_test.sh"
fi

# Run integration tests if present
if [ -f "$1/tests/integration_test.sh" ]; then
    echo "Running integration tests..."
    "$1/tests/integration_test.sh"
fi

echo "✅ All tests passed for skill: $1"
```

## Skill Documentation Standards

### Documentation Levels

```markdown
## Documentation Maturity Levels

### Level 1: Basic
- SKILL.md with essential fields
- Basic README
- Simple examples

### Level 2: Standard
- Complete SKILL.md
- Comprehensive README
- Usage examples
- Troubleshooting guide

### Level 3: Advanced
- Best practices guide
- Architecture diagrams
- API reference
- Video tutorials

### Level 4: Expert
- Interactive documentation
- AI-assisted guidance
- Community contributions
- Versioned documentation
```

### Documentation Checklist

```markdown
### Documentation Completeness Checklist

- [ ] SKILL.md with all required fields
- [ ] Clear and specific description
- [ ] Usage examples with code
- [ ] Installation instructions
- [ ] Configuration options
- [ ] Troubleshooting guide
- [ ] Best practices
- [ ] API reference (if applicable)
- [ ] Architecture overview
- [ ] Contribution guidelines
- [ ] License information
- [ ] Change log
- [ ] FAQ
```

## Skill Discovery and Organization

### Skill Categorization

```markdown
## Skill Categories

### By Domain
- **Testing**: bdd_testing, unit_testing
- **Development**: code_generation, refactoring
- **Operations**: deployment, monitoring
- **Documentation**: doc_generation, wiki_management

### By Technology
- **Go**: go_best_practices, go_testing
- **Web**: api_design, frontend_testing
- **DevOps**: ci_cd, containerization

### By Purpose
- **Productivity**: skill_creator, templates
- **Quality**: testing, validation
- **Collaboration**: code_review, documentation
```

### Skill Index

```yaml
# .vibe/skills/SKILL_INDEX.md
---
title: Skill Index
description: Complete list of available skills
---

# Available Skills

## Core Skills
- [skill_creator](skill_creator/SKILL.md) - Create and manage skills
- [bdd_testing](bdd_testing/SKILL.md) - BDD testing framework

## Testing Skills
- [bdd_testing](bdd_testing/SKILL.md) - Behavior-Driven Development
- [unit_testing](unit_testing/SKILL.md) - Unit testing patterns
- [integration_testing](integration_testing/SKILL.md) - Integration testing

## Development Skills
- [api_design](api_design/SKILL.md) - REST API design patterns
- [error_handling](error_handling/SKILL.md) - Robust error handling
- [performance_optimization](performance_optimization/SKILL.md) - Performance tuning
```

## Skill Governance

### Ownership Model

```markdown
## Skill Ownership

### Roles

1. **Skill Author**: Creates the initial skill
2. **Skill Maintainer**: Responsible for updates and support
3. **Skill Reviewer**: Approves changes and updates
4. **Skill User**: Uses the skill in their work

### Responsibilities

| Role | Responsibilities |
|------|------------------|
| Author | Initial creation, documentation |
| Maintainer | Updates, bug fixes, support |
| Reviewer | Quality assurance, approvals |
| User | Feedback, issue reporting |

### Ownership Metadata

```yaml
# SKILL.md
metadata:
  author: "Jane Doe <jane@example.com>"
  maintainer: "John Smith <john@example.com>"
  reviewers:
    - "Alice Brown <alice@example.com>"
  status: "active"
  support: "https://github.com/org/repo/issues"
```

## Advanced Validation

### Validation Levels

```bash
#!/bin/bash
# scripts/validate-advanced.sh

set -e

SKILL_DIR=$1
LEVEL=${2:-standard}  # basic, standard, advanced, expert

echo "Validating skill at level: $LEVEL"

# Basic validation (always required)
.vibe/skills/skill_creator/scripts/validate_skill.sh "$SKILL_DIR"

# Standard validation
if [ "$LEVEL" != "basic" ]; then
    echo "Checking standard requirements..."
    # Check for README
    if [ ! -f "$SKILL_DIR/README.md" ]; then
        echo "⚠️  WARNING: README.md recommended for standard level"
    fi
    
    # Check for examples
    if ! grep -q "## Usage" "$SKILL_DIR/SKILL.md"; then
        echo "⚠️  WARNING: Usage examples recommended for standard level"
    fi
fi

# Advanced validation
if [ "$LEVEL" = "advanced" ] || [ "$LEVEL" = "expert" ]; then
    echo "Checking advanced requirements..."
    
    # Check for best practices
    if [ ! -f "$SKILL_DIR/references/BEST_PRACTICES.md" ]; then
        echo "⚠️  WARNING: BEST_PRACTICES.md recommended for advanced level"
    fi
    
    # Check for troubleshooting
    if ! grep -q "## Troubleshooting" "$SKILL_DIR/SKILL.md"; then
        echo "⚠️  WARNING: Troubleshooting section recommended for advanced level"
    fi
fi

# Expert validation
if [ "$LEVEL" = "expert" ]; then
    echo "Checking expert requirements..."
    
    # Check for architecture diagrams
    if [ ! -f "$SKILL_DIR/references/ARCHITECTURE.md" ]; then
        echo "⚠️  WARNING: ARCHITECTURE.md recommended for expert level"
    fi
    
    # Check for API reference
    if [ ! -f "$SKILL_DIR/references/API.md" ]; then
        echo "⚠️  WARNING: API.md recommended for expert level"
    fi
fi

echo "✅ Validation complete for level: $LEVEL"
```

## Skill Metrics and Analytics

### Usage Tracking

```markdown
## Skill Metrics

### Usage Tracking

Track skill adoption and effectiveness:

```yaml
# SKILL.md
metadata:
  analytics:
    enabled: true
    tracking_id: "skill-bdd-testing-v1"
```

### Metrics to Track

1. **Adoption Rate**: Number of teams using the skill
2. **Usage Frequency**: How often the skill is used
3. **Success Rate**: Percentage of successful executions
4. **Error Rate**: Frequency of issues encountered
5. **Time Saved**: Estimated productivity improvements
6. **User Satisfaction**: Feedback and ratings

### Analytics Implementation

```bash
#!/bin/bash
# scripts/track-usage.sh

SKILL_NAME=$1
ACTION=$2  # create, use, update, deprecate

# Log to analytics system
curl -X POST "https://analytics.example.com/skills" \
  -H "Content-Type: application/json" \
  -d "{
    \"skill\": \"$SKILL_NAME\",
    \"action\": \"$ACTION\",
    \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"version\": \"1.0.0\"
  }"

echo "Usage tracked: $SKILL_NAME - $ACTION"
```

## Skill Improvement Process

### Continuous Improvement Workflow

```mermaid
graph TD
    A[Identify Issue] --> B[Create Improvement]
    B --> C[Test Locally]
    C --> D[Submit PR]
    D --> E[Review]
    E -->|Approved| F[Merge]
    E -->|Rejected| B
    F --> G[Update Documentation]
    G --> H[Announce Changes]
    H --> I[Monitor Impact]
```

### Improvement Checklist

```markdown
### Skill Improvement Checklist

1. **Identify the issue**
   - [ ] Clear problem statement
   - [ ] Reproduction steps
   - [ ] Impact assessment

2. **Design solution**
   - [ ] Proposed changes
   - [ ] Backward compatibility
   - [ ] Test plan

3. **Implement changes**
   - [ ] Code changes
   - [ ] Documentation updates
   - [ ] Example updates

4. **Test thoroughly**
   - [ ] Unit tests pass
   - [ ] Integration tests pass
   - [ ] Manual testing complete

5. **Review and merge**
   - [ ] Peer review completed
   - [ ] All feedback addressed
   - [ ] Merge to main branch

6. **Communicate changes**
   - [ ] Release notes updated
   - [ ] Team notified
   - [ ] Documentation published

7. **Monitor impact**
   - [ ] Usage metrics tracked
   - [ ] User feedback collected
   - [ ] Issues resolved
```

## Advanced Scripting

### Script Templates

```bash
#!/bin/bash
# scripts/advanced-script-template.sh

# Advanced script template with error handling, logging, and validation

set -euo pipefail

# Configuration
SCRIPT_NAME=$(basename "$0")
LOG_LEVEL=${LOG_LEVEL:-info}
VERBOSE=${VERBOSE:-false}

# Logging functions
log_info() { echo "[INFO] $*"; }
log_warn() { echo "[WARN] $*" >&2; }
log_error() { echo "[ERROR] $*" >&2; }
log_debug() { if [ "$VERBOSE" = true ]; then echo "[DEBUG] $*"; fi }

# Error handling
handle_error() {
    local exit_code=$1
    local line_number=$2
    log_error "Error in $SCRIPT_NAME at line $line_number with exit code $exit_code"
    exit $exit_code
}
trap 'handle_error $? $LINENO' ERR

# Validation
validate_input() {
    if [ -z "${1:-}" ]; then
        log_error "Missing required argument"
        usage
        exit 1
    fi
}

# Main function
main() {
    log_info "Starting $SCRIPT_NAME"
    
    # Parse arguments
    while getopts "v" opt; do
        case $opt in
            v) VERBOSE=true ;;
            *) usage ;;
        esac
    done
    shift $((OPTIND-1))
    
    # Validate input
    validate_input "$1"
    
    # Business logic here
    log_info "Processing: $1"
    
    # Success
    log_info "Completed successfully"
}

# Usage
usage() {
    cat <<EOF
Usage: $SCRIPT_NAME [options] <argument>

Options:
  -v            Verbose output
  -h            Show this help

Arguments:
  <argument>    Required input

Examples:
  $SCRIPT_NAME input_value
  $SCRIPT_NAME -v input_value
EOF
}

# Run main function
main "$@"
```

### Script Best Practices

```markdown
## Advanced Scripting Best Practices

### 1. Error Handling
- Use `set -euo pipefail` for strict error handling
- Implement `trap` for error recovery
- Provide meaningful error messages

### 2. Logging
- Standardize log levels (INFO, WARN, ERROR, DEBUG)
- Include timestamps for production scripts
- Log to both console and files for important scripts

### 3. Input Validation
- Validate all inputs and arguments
- Provide clear error messages
- Show usage examples on error

### 4. Configuration
- Support environment variables
- Allow command-line overrides
- Provide sensible defaults

### 5. Testing
- Test edge cases and error conditions
- Validate script output
- Test performance with large inputs

### 6. Documentation
- Include usage examples
- Document all options and arguments
- Provide example output

### 7. Performance
- Minimize external dependencies
- Optimize I/O operations
- Use efficient algorithms

### 8. Security
- Validate all external inputs
- Use temporary files securely
- Avoid shell injection vulnerabilities
```

## Skill Publishing and Distribution

### Publication Workflow

```markdown
## Skill Publication Process

### 1. Development
- Create skill using skill_creator
- Implement functionality
- Write documentation
- Add tests

### 2. Validation
- Run validation scripts
- Check against best practices
- Verify examples work
- Test edge cases

### 3. Review
- Peer review by team members
- Address all feedback
- Update documentation
- Final testing

### 4. Publication
- Tag release version
- Update skill index
- Announce to team
- Add to documentation

### 5. Maintenance
- Monitor usage and issues
- Collect feedback
- Plan improvements
- Release updates
```

### Distribution Channels

```markdown
## Distribution Methods

### 1. Local Repository
- Default location: `.vibe/skills/`
- Version controlled with project
- Easy to update and maintain

### 2. Central Repository
- Organization-wide skill library
- Versioned releases
- Access control and governance

### 3. Package Manager
- Publish as packages (npm, pip, etc.)
- Version management
- Dependency resolution

### 4. Cloud Registry
- Centralized skill registry
- Discovery and search
- Ratings and reviews
```

## Future Enhancements

### Roadmap

```markdown
## Skill Creator Roadmap

### Short-Term (Next 3 Months)
- [ ] Interactive skill creation wizard
- [ ] Visual skill editor (web-based)
- [ ] Skill dependency resolver
- [ ] Automated skill testing

### Medium-Term (Next 6 Months)
- [ ] AI-assisted skill generation
- [ ] Skill marketplace integration
- [ ] Team collaboration features
- [ ] Version conflict resolution

### Long-Term (Next Year)
- [ ] Natural language skill creation
- [ ] Automated skill updates
- [ ] Skill performance analytics
- [ ] Enterprise skill management
```

### Innovation Ideas

```markdown
## Innovation Opportunities

### 1. AI-Powered Skills
- Natural language to skill conversion
- Automated skill improvement
- Intelligent skill recommendations

### 2. Visual Skill Builder
- Drag-and-drop interface
- Real-time preview
- Interactive documentation

### 3. Skill Marketplace
- Discover and share skills
- Ratings and reviews
- Usage analytics

### 4. Skill Analytics
- Usage tracking and insights
- Performance monitoring
- Impact measurement

### 5. Skill Collaboration
- Team-based skill development
- Version control integration
- Change management
```

## Conclusion

These advanced features represent the next evolution of the skill_creator, transforming it from a basic scaffolding tool to a comprehensive skill management platform. By implementing these enhancements, we can:

1. **Improve skill quality** through better validation and testing
2. **Increase adoption** with easier creation and discovery
3. **Enhance collaboration** with team features
4. **Measure impact** with analytics and metrics
5. **Scale effectively** with governance and lifecycle management

The skill_creator can become the foundation for a robust skill ecosystem that drives productivity, quality, and innovation across the organization.