dance-lessons-coach/.vibe/skills/skill-creator/README.md

# Skill Creator

A tool for creating and managing Mistral Vibe skills that comply with the [Agent Skills specification](https://agentskills.io/specification).

## Features

- **Skill Scaffold Generation**: Quickly create new skills with proper directory structure
- **Validation**: Ensure skills follow the Agent Skills specification
- **Templates**: Pre-built templates for SKILL.md, scripts, and references
- **Best Practices**: Built-in guidance for creating high-quality skills

## Installation

The skill_creator is already included in your project at `.vibe/skills/skill_creator/`.

## Usage

### Create a New Skill

```bash
# Navigate to your project root
cd /path/to/your/project

# Create a new skill
.vibe/skills/skill_creator/scripts/create_skill.sh my_new_skill
```

This will create a new skill directory at `.vibe/skills/my_new_skill/` with:
- `SKILL.md` - Main skill file with metadata and instructions
- `scripts/` - Directory for executable scripts
- `references/` - Directory for documentation
- `assets/` - Directory for templates and resources

### Create a Composite Skill

```bash
# Create a skill that combines multiple existing skills
.vibe/skills/skill_creator/scripts/create_composite_skill.sh fullstack-testing \
  bdd_testing unit_testing integration_testing
```

This creates a composite skill that orchestrates multiple component skills:
- `SKILL.md` - With composite metadata and component list
- `scripts/main.sh` - Workflow orchestration script
- `references/INTEGRATION.md` - Integration guide
- `assets/workflow-diagram.md` - Visual workflow diagrams
- `README.md` - Comprehensive usage guide

### Validate a Skill

```bash
.vibe/skills/skill_creator/scripts/validate_skill.sh .vibe/skills/my_skill
```

The validator checks:
- ✓ SKILL.md exists
- ✓ Skill name matches directory name
- ✓ Name format is valid (lowercase alphanumeric + hyphens)
- ✓ Description length is appropriate (1-1024 characters)
- ✓ Optional directories are present

## Skill Structure

A properly structured skill follows this format:

```
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files
```

## SKILL.md Format

The `SKILL.md` file must contain YAML frontmatter followed by Markdown content:

```markdown
---
name: skill-name
description: Brief description of what this skill does and when to use it
license: MIT
metadata:
  author: Your Name
  version: "1.0.0"
---

# Skill Title

Detailed description and instructions...
```

### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Skill name (lowercase alphanumeric + hyphens, 1-64 chars) |
| `description` | Yes | What the skill does and when to use it (1-1024 chars) |
| `license` | No | License name or reference |
| `metadata` | No | Additional key-value metadata |

### Best Practices for SKILL.md

1. **Name**: Use lowercase alphanumeric characters and hyphens only
2. **Description**: Be specific about functionality and use cases
3. **Documentation**: Include clear instructions and examples
4. **Progressive Disclosure**: Keep main file concise, move details to references/

## Examples

### Creating a BDD Testing Skill

```bash
# Create the skill
.vibe/skills/skill_creator/scripts/create_skill.sh bdd-testing

# Edit the SKILL.md
# Add BDD-specific instructions, commands, and workflows

# Validate the skill
.vibe/skills/skill_creator/scripts/validate_skill.sh .vibe/skills/bdd-testing
```

### Creating a Database Migration Skill

```bash
.vibe/skills/skill_creator/scripts/create_skill.sh database-migrations

# Add migration scripts to scripts/
# Add documentation to references/
# Add SQL templates to assets/

# Validate
.vibe/skills/skill_creator/scripts/validate_skill.sh .vibe/skills/database-migrations
```

### Creating a Composite Testing Skill

```bash
# Create a composite skill combining BDD, unit, and integration testing
.vibe/skills/skill_creator/scripts/create_composite_skill.sh fullstack-testing \
  bdd_testing unit_testing integration_testing

# Customize the workflow
# Edit .vibe/skills/fullstack-testing/scripts/main.sh

# Validate the composite skill
.vibe/skills/skill_creator/scripts/validate_skill.sh .vibe/skills/fullstack-testing

# Run the complete testing workflow
.vibe/skills/fullstack-testing/scripts/main.sh
```

## Troubleshooting

### "Skill name doesn't match directory name"

The validator converts underscores to hyphens when comparing names. Ensure:
- Your skill directory name uses underscores (e.g., `my_skill`)
- The `name` field in SKILL.md uses hyphens (e.g., `my-skill`)

### "Description must be 1-1024 characters"

Update the description field in SKILL.md to be more concise or more detailed as needed.

### "Invalid characters in skill name"

Skill names can only contain:
- Lowercase letters (a-z)
- Numbers (0-9)
- Hyphens (-)
- No spaces, uppercase letters, or special characters

## Advanced Usage

### Custom Templates

You can modify the templates in the skill_creator scripts to match your team's preferences:
- Edit `create_skill.sh` to change the SKILL.md template
- Add additional directories or files as needed
- Customize the example scripts and reference files

### Integration with CI/CD

Add skill validation to your CI/CD pipeline:

```bash
# In your test script
.vibe/skills/skill_creator/scripts/validate_skill.sh .vibe/skills/my_skill || exit 1
```

## Contributing

To improve the skill_creator:

1. Fork the repository
2. Make your changes to `.vibe/skills/skill_creator/`
3. Test with existing skills
4. Submit a pull request

## License

MIT License - See the `license` field in SKILL.md for details.