# dnd-dice-roller

> Roll dice using D&D notation (d20, 2d6+3, advantage/disadvantage)

- Author: Joe C
- Repository: JoeCotellese/dnd-dm-skill
- Version: 20251113162100
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/JoeCotellese/dnd-dm-skill
- Web: https://mule.run/skillshub/@@JoeCotellese/dnd-dm-skill~dnd-dice-roller:20251113162100

---

# Tutorial 1: Dice Rolling

Learn the fundamentals of Claude Code skills by building a D&D dice roller!

## Overview

This tutorial teaches you how to create a basic skill that parses user input, uses tools to generate random numbers, and formats output. You'll build a dice roller that understands standard D&D notation.

## What You'll Learn (Skill Building)

- **Basic skill structure**: YAML frontmatter with name and description
- **Writing clear prompts**: How to instruct Claude on behavior
- **Parsing user input**: Extracting dice notation from natural language
- **Using tools**: Leveraging the Bash tool for random number generation
- **Formatting output**: Presenting results clearly to users
- **Input validation**: Handling edge cases and errors gracefully

## What You'll Build (D&D Feature)

A dice roller that supports:
- Single die: `d20`, `d6`, `d100`
- Multiple dice: `2d6`, `3d8`, `4d6`
- Modifiers: `d20+5`, `2d6-2`
- Advantage/Disadvantage: `d20 adv`, `d20 dis`
- Drop lowest: `4d6 drop lowest` (for ability score generation)

## Prerequisites

- Claude Code installed and configured
- Basic understanding of D&D dice notation (or willingness to learn!)

## Installation

1. Copy the entire tutorial directory to your skills folder:
   ```bash
   cp -r tutorial-1-dice-rolling ~/.claude/skills/dnd-dice-roller
   ```

2. The skill will be automatically available (Claude reads SKILL.md from the directory)

## Usage Examples

### Basic Rolls

```
You: Roll a d20
Claude: Rolling 1d20...
        [15] = 15

You: Roll 2d6
Claude: Rolling 2d6...
        [4, 5] = 9
```

### With Modifiers

```
You: Roll d20+5
Claude: Rolling 1d20+5...
        [12] +5 = 17

You: Roll 2d6-2
Claude: Rolling 2d6-2...
        [3, 4] -2 = 5
```

### Advantage/Disadvantage

```
You: Roll d20 with advantage
Claude: Rolling d20 with advantage...
        [15] [8] (advantage) = 15

You: Roll d20 disadvantage
Claude: Rolling d20 with disadvantage...
        [15] [8] (disadvantage) = 8
```

### Character Ability Score Generation

```
You: Roll 4d6 drop lowest
Claude: Rolling 4d6, dropping lowest...
        [4, 3, 6, 2] → Dropped [2]
        [4, 3, 6] = 13
```

## Code Walkthrough

### Skill Structure

Every skill starts with YAML frontmatter:
```yaml
---
name: dnd-dice-roller
description: Roll dice using D&D notation (d20, 2d6+3, advantage/disadvantage)
---
```

The `name` is used to invoke the skill, and the `description` helps users understand what it does.

### Prompt Design

The skill prompt explains:
1. **What Claude should do**: "You are a D&D dice roller assistant"
2. **What inputs to expect**: List of supported notations
3. **How to process inputs**: Step-by-step instructions
4. **How to format outputs**: Examples of desired formatting
5. **How to handle errors**: What to do when input is invalid

### Using a Python Script for Efficiency

Instead of having Claude generate dice rolling code each time, we use a pre-written Python script (`roll_dice.py`). This approach:
- **Reduces cognitive load**: Claude just calls the script, doesn't write code
- **Ensures consistency**: Same logic every time
- **Improves performance**: No code generation needed
- **Simplifies maintenance**: Update one script instead of the skill prompt

The skill simply calls:
```bash
python3 ~/.claude/skills/dnd-dice-roller/roll_dice.py d20+5
```

And displays the output to the user.

### Output Formatting

Good output shows:
- Individual die rolls: `[4, 5]`
- Modifiers: `+3`
- Total: `= 12`
- Special conditions: `(advantage)`

This helps users verify the roll and understand what happened.

## Key Concepts

### 1. Input Parsing
The skill is instructed to be flexible with notation:
- "Roll a d20" → parse as `1d20`
- "d20+5" → parse as `1d20+5`
- "2d6 with modifier of +3" → parse as `2d6+3`

### 2. Delegating to Scripts
Rather than having Claude write dice rolling logic each time, the skill delegates to a pre-written Python script. Claude's job is simply:
1. Parse what the user wants
2. Call the script with the right notation
3. Display the result

This is a key pattern for efficient skills: **write the complex logic once in a script**, then have Claude orchestrate calling it.

### 3. Error Handling
The skill includes guidance on handling invalid input gracefully:
- Validate die sizes (must be positive)
- Provide helpful error messages
- Suggest correct notation

### 4. Clarity Over Cleverness
The prompt is explicit and detailed rather than minimal. This helps Claude understand exactly what to do, reducing errors and improving consistency.

## Testing Your Skill

Try these test cases:
- ✅ Basic: `d20`, `d6`, `d100`
- ✅ Multiple dice: `2d6`, `3d8`
- ✅ Modifiers: `d20+5`, `2d6-2`
- ✅ Advantage: `d20 adv`, `d20 advantage`
- ✅ Disadvantage: `d20 dis`
- ✅ Drop lowest: `4d6 drop lowest`
- ❌ Invalid: `d0`, `d-5`, `999d999`

## Extension Ideas

Want to expand this skill? Try adding:
- **Critical hit detection**: Announce when a d20 rolls 20 (or 1)
- **Multiple rolls**: `roll 5 d20s` to roll several dice at once
- **Named presets**: Save common rolls like "greatsword attack" as `2d6+5`
- **Roll history**: Keep track of recent rolls in a session
- **Exploding dice**: Re-roll and add when maximum is rolled
- **Dice pools**: Count successes (for systems like World of Darkness)

## Next Steps

Ready to learn more? Move on to:
- **Tutorial 2: Character Stats** - Learn about file I/O and persistent state
- **Tutorial 3: Simple Combat** - Build multi-step workflows

## Troubleshooting

**Skill not showing up?**
- Check the file is in `~/.claude/skills/`
- Verify the YAML frontmatter is valid
- Try restarting Claude Code

**Rolls seem wrong?**
- Verify the Bash tool is working: test with simple `echo` commands
- Check Python is available: `python3 --version`

**Claude isn't following instructions?**
- Make sure you're invoking the skill properly
- The prompt may need to be more explicit for complex cases
- Try adding more examples to the prompt

## Learn More

- [Claude Code Skills Documentation](https://docs.claude.com/claude-code/skills)
- [D&D 5E Basic Rules](https://www.dndbeyond.com/sources/basic-rules)
- [Dice Notation Reference](https://en.wikipedia.org/wiki/Dice_notation)