claude-code-skills-reference/demos/README.md

# Skill Demonstrations

This directory contains automated demonstrations of each skill using [VHS (Video Home System)](https://github.com/charmbracelet/vhs) by Charmbracelet.

VHS allows you to write terminal recordings as code, making demos reproducible, version-controllable, and typo-free.

## 📁 Demo Structure

```
demos/
├── skill-creator/
│   ├── init-skill.tape          # Initialize a new skill
│   ├── validate-skill.tape       # Validate skill quality
│   └── package-skill.tape        # Package for distribution
├── github-ops/
│   └── create-pr.tape            # Create pull requests
├── doc-to-markdown/
│   └── convert-docs.tape         # Convert documents
└── generate_all_demos.sh         # Generate all GIFs
```

## 🎬 Generating Demos

### Prerequisites

Install VHS:

**macOS:**
```bash
brew install vhs
```

**Linux (with Go):**
```bash
go install github.com/charmbracelet/vhs@latest
```

**Or download from:**
https://github.com/charmbracelet/vhs/releases

### Generate All Demos

```bash
./generate_all_demos.sh
```

This will:
1. Find all `.tape` files
2. Generate corresponding `.gif` files
3. Report success/failure for each demo

### Generate a Specific Demo

```bash
vhs < skill-creator/init-skill.tape
```

This creates `demos/skill-creator/init-skill.gif`.

## 📝 Creating New Demos

### VHS Tape File Format

A `.tape` file consists of commands that VHS executes in a virtual terminal:

```tape
# Output configuration
Output demos/my-skill/my-demo.gif

# Terminal settings
Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Dracula"
Set Padding 20

# Demo script
Type "echo Hello World" Sleep 500ms
Enter
Sleep 2s
```

### Common VHS Commands

| Command | Description | Example |
|---------|-------------|---------|
| `Output` | Set output file path | `Output demos/skill/demo.gif` |
| `Set FontSize` | Set terminal font size | `Set FontSize 18` |
| `Set Width/Height` | Set terminal dimensions | `Set Width 1400` |
| `Set Theme` | Set color theme | `Set Theme "Dracula"` |
| `Type` | Type text | `Type "ls -la"` |
| `Type@<speed>` | Type with custom speed | `Type@500ms "slow typing"` |
| `Enter` | Press Enter key | `Enter` |
| `Sleep` | Pause execution | `Sleep 2s` |
| `Ctrl+C` | Send Ctrl+C | `Ctrl+C` |

### Demo Guidelines

When creating new demos:

1. **Keep demos short** - Under 30 seconds ideally
2. **Use readable font size** - 16-18pt minimum
3. **Show realistic usage** - Practical, real-world examples
4. **Add brief comments** - Explain what's happening
5. **Use consistent theme** - Dracula theme recommended
6. **Test before committing** - Generate and review the GIF

### Example: Creating a New Demo

1. **Create the tape file:**
```bash
touch demos/my-skill/my-workflow.tape
```

2. **Write the demo script:**
```tape
Output demos/my-skill/my-workflow.gif

Set FontSize 16
Set Width 1400
Set Height 700
Set Theme "Dracula"
Set Padding 20

Type "# My Skill Demo" Sleep 500ms Enter
Sleep 1s

Type "echo 'Step 1: Setup'" Sleep 500ms
Enter
Sleep 2s

Type "echo 'Step 2: Execute'" Sleep 500ms
Enter
Sleep 2s
```

3. **Generate the GIF:**
```bash
vhs < demos/my-skill/my-workflow.tape
```

4. **Review the output:**
```bash
open demos/my-skill/my-workflow.gif  # macOS
xdg-open demos/my-skill/my-workflow.gif  # Linux
```

## 🎨 Themes

VHS supports various themes. We use "Dracula" for consistency, but you can try:

- `Dracula` (default)
- `Nord`
- `Monokai`
- `Solarized Dark`
- `Tokyo Night`

## 📚 Resources

- **VHS Documentation**: https://github.com/charmbracelet/vhs
- **VHS Examples**: https://github.com/charmbracelet/vhs/tree/main/examples
- **Tape File Syntax**: https://github.com/charmbracelet/vhs/blob/main/syntax.md

## 🔧 Troubleshooting

### VHS not found

Ensure VHS is in your PATH:
```bash
which vhs
```

### Permission denied

Make the generation script executable:
```bash
chmod +x generate_all_demos.sh
```

### Demo generation fails

Check the tape file syntax:
```bash
vhs validate < demos/my-skill/my-demo.tape
```

### GIF file too large

Reduce dimensions or duration:
```tape
Set Width 1200  # Smaller width
Set Height 600  # Smaller height
Sleep 1s        # Shorter pauses
```

## 📝 Adding Demos to README

After generating demos, add them to the main README.md:

```markdown
### skill-creator - Skill Development Toolkit

<div align="center">
  <img src="./demos/skill-creator/init-skill.gif" alt="Initialize Skill Demo" width="800"/>
</div>

Guide for creating effective Claude Code skills...
```

---

**Pro Tip**: Demos are automatically regenerated by CI/CD when tape files change (coming soon!).