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:

# 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:

# 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

## 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:

# SKILL.md
metadata:
  version: "1.0.0"
  compatibility: ">=1.0.0"
  deprecated: false
  successor: ""

Skill Dependencies

Dependency Management

## 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

# 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

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

State Transitions:

### 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

## 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

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

Workflow

## 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

#!/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

## 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

### 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

## 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

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

## 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

#!/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

## 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

#!/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

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

### 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

#!/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

## 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

## 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

## 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

## 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

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