New advertisers: 50% off your first month with code FIRSTMONTHSee slots
kylesnowschwartz avatar

claude-code-hero

kylesnowschwartz/claude-code-hero

Interactive D&D-style quests that teach Claude Code features by building real artifacts, one level at a time.

version
0.3.2
GitHub stars
119
View on GitHub

What it does

  • Adds the dungeon-master agent, 16 quest skills, and /verify, /progress, /solve, /restart, and /music commands
  • Covers thirteen chambers from basic chat and CLAUDE.md through hooks, skills, agents, plugins, MCP servers, and dynamic workflows
  • Keeps every generated artifact prefixed hero-* and limits /restart to removing only what the dungeon created
  • Designed for developers who already use Claude Code and want hands-on practice with its deeper features

Add marketplace

/plugin marketplace add kylesnowschwartz/claude-code-hero

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install claude-code-hero@claude-code-hero

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Objective

Learn the three things every Claude Code user needs: how to give an instruction, how to point Claude at a file, and how to ask Claude to create something. Then prove it by having Claude write your first artifact.

Why This Matters

Claude Code is a conversational tool. You type instructions in the prompt box at the bottom of the screen, press Enter, and Claude acts. That's the entire interaction model. But most people never learn the small things that make it work well -- like referencing specific files or giving clear, direct instructions.

This level is about building that muscle memory before you need it.

The Quest

You stand at the threshold of the dungeon. The door is sealed -- not by a lock, but by a simple test. The dungeon does not open for those who cannot speak its language.

Your trial has three parts.

Part 1: Speak

Type a message in the prompt box and press Enter. That's it. Ask Claude something about this project -- what files are here, what the project does, anything. Watch what happens.

The prompt box is at the bottom of the screen. You type, you press Enter (or Return), Claude responds. If you want to cancel a response in progress, press Escape twice.

Part 2: Point

Now try something more specific. Use the @ symbol to reference a file by name. Type @ and you'll see a list of files you can select from. Pick one -- CLAUDE.md is a good choice -- and ask Claude a question about it.

The @ reference tells Claude to read that specific file before answering. Without it, Claude might guess. With it, Claude knows.

Try it: type something like what does @CLAUDE.md say about this project?

Part 3: Create

Ask Claude to create a file for you. This is the fundamental act -- giving Claude an instruction that produces something real on disk.

Ask Claude to create .claude/hero-journal.md. The journal should contain:

  • A short entry (a few sentences) about what you've learned so far
  • Written as if it's the first page of an adventurer's journal
  • At least one ## heading

The exact content is yours to decide. The only requirements are that the file exists at .claude/hero-journal.md and has some real content in it (not just a heading with nothing under it).

Hints

Hint 1

To create the file, just ask Claude directly: "Create a file at .claude/hero-journal.md with a journal entry about what I've learned." You can be more specific about what you want in it, or let Claude decide.

Hint 2

If the file was created but verification fails, make sure it's at the exact path .claude/hero-journal.md (not hero-journal.md at the project root) and that it has at least 5 lines of real content.

Hint 3

You can ask Claude to read the file back to you to check: read @.claude/hero-journal.md and tell me what's in it.

Completion

When you're ready, run /claude-code-hero:verify to check your work.

The dungeon checks for one thing: does .claude/hero-journal.md exist with real content? If it does, the threshold opens.

Further Reading

Readme

Claude Code Hero

A pixel art dungeon with Clawd, the Claude Code mascot, standing next to a treasure chest

You know the basics. Chat, CLAUDE.md, maybe a prompt or two. But there are deeper chambers -- commands, hooks, agents, skills, plugins, MCP servers, workflows -- and most who wield Claude Code never find them.

This is the dungeon that teaches you how.

A quest per feature. Each one builds a real artifact on your machine. The artifacts connect -- the spell you forge in Level 3 gets a tripwire in Level 6, and everything binds together into a plugin in Level 9. Past the workshop the chambers get sharper: a hook that decides instead of reacting, a tool that did not exist until you wired it in, and a script that commands several agents at once. You start at the threshold learning to talk to Claude Code. You end writing programs whose workers think.

The medium is the message: you learn about plugins by using one.

Demo of Claude Code Hero gameplay

Before You Enter

You'll need three things. The install script checks for all of them and offers to fetch what's missing.

git clone https://github.com/kylesnowschwartz/claude-code-hero.git
cd claude-code-hero
bash scripts/install.sh
DependencyPurposeInstall source
RubyRuns the game engineHomebrew / apt
jqParses JSON in hook scriptsHomebrew / apt
Claude CodeThe CLI you're here to masterOfficial installer

macOS and Linux. Windows users: WSL.

Enter the Dungeon

claude --plugin-dir . --agent dungeon-master

A guide will meet you at the entrance.

The Thirteen Chambers

QuestChamberWhat You Learn
0The ThresholdBasic Claude Code interaction
1The Map RoomThe .claude/ directory
2The Tome of First InstructionsCLAUDE.md
3The Goblin Lair of CommandsSlash commands
4The Warden's KeysSettings and permissions
5The Enchanted InscriptionRules
6The Tripwire CavernHooks
7The Skill Quest of DoomSkills
8The Summoner's CircleAgents
9The Artificer's WorkshopPlugins, and publishing one to a marketplace
10The Hall of WatchersAdvanced hooks -- deciding, not just reacting
11The Oracle WellMCP servers
12The WarbandDynamic workflows

Commands at Your Belt

CommandWhat it does
/claude-code-hero:verifyTest whether your current quest is complete
/claude-code-hero:progressUnroll the quest log
/claude-code-hero:musicToggle dungeon music on or off
/claude-code-hero:solve <N>Create minimum artifacts to pass levels 0 through N (QA tool)
/claude-code-hero:restartWipe all artifacts and return to the entrance

Plugin commands carry the plugin's name, so the prefix is not optional -- but you never have to type any of it. Ask the dungeon master instead: "check my work" runs the same verification, and "where am I?" unrolls the same quest log.

How Progress Works

Your journey saves to .claude/claude-code-hero.json. The dungeon master verifies your work programmatically and advances you when you pass.

Already have a CLAUDE.md or existing hooks? Every artifact is named hero-*, so nothing of yours is overwritten and /claude-code-hero:restart removes only what the dungeon created. Most quests write inside .claude/; the later ones reach outside it, since that is where the real thing lives -- Level 9 builds a plugin directory and Level 11 writes .mcp.json at the project root.

Left mid-quest? Walk back in anytime and resume your quest: claude --plugin-dir . --agent dungeon-master

Details

Marketplace
kylesnowschwartz/claude-code-hero
Category
Community

Similar to claude-code-hero

More Development Tools