# How Claude Code Skills and Slash Commands Work in Thunderbolt: A Complete Guide

> Learn how Claude Code skills and slash commands function in Thunderbolt. Discover how Markdown definitions in .thunderbot enable CLI execution of Makefile targets for streamlined workflows.

- Repository: [Thunderbird/thunderbolt](https://github.com/thunderbird/thunderbolt)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Claude Code skills in Thunderbolt are Markdown-based definitions stored in `.thunderbot/` that get symlinked to `.claude/commands/`, enabling slash commands like `/thunderup` and `/thundercheck` to execute Makefile targets directly within the Claude Code CLI.**

Thunderbolt, the development framework maintained by Thunderbird, ships with a comprehensive set of Claude Code skills that automate common development workflows. These skills transform standard Markdown files into executable slash commands, allowing developers to bootstrap environments, run checks, and manage deployments without leaving the conversational AI interface.

## What Are Claude Code Skills in Thunderbolt?

Claude Code skills are **Markdown files with YAML front-matter** that define slash commands for the Claude Code CLI. In the Thunderbolt repository, these skills live in the hidden `.thunderbot/` directory and describe everything from environment setup to autonomous coding agents.

Each skill file contains:
- A `description` field in the front-matter explaining the command's purpose
- Instructions specifying which shell commands or Makefile targets to execute
- Optional argument handling for parameterized commands (e.g., `/thunderup THU-123`)

When you run the Claude Code CLI inside Thunderbolt, it scans the `.claude/commands/` directory for these skill files and exposes them as typed slash commands.

## The Architecture Behind Thunderbolt Slash Commands

The integration between Thunderbolt and Claude Code relies on a **symlink bridge** that connects version-controlled skill definitions to the Claude Code discovery mechanism.

### Skill Markdown Files

The source of truth for each command resides in `.thunderbot/*.md`. For example, [`.thunderbot/thunderup.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thunderup.md) defines the environment bootstrapping command, while [`.thunderbot/thundercheck.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thundercheck.md) specifies the linting and type-checking workflow.

These files follow a standard format where the front-matter provides metadata and the body contains the execution logic or references to Makefile targets like `doctor-q`, `setup`, and `docker-up`.

### The Symlink Bridge

Claude Code expects to find commands in `.claude/commands/`, but Thunderbolt stores them in `.thunderbot/`. The `Makefile` resolves this through the `setup-symlinks` target (lines 33-39), which creates symbolic links from `.thunderbot/*.md` into `.claude/commands/`.

This architectural separation allows the skills to be managed via a **git subtree** from the separate `thunderbot` repository while maintaining compatibility with Claude Code's discovery mechanism.

### Claude Code CLI Integration

When you type a slash command in the Claude Code interface, the CLI:
1. Parses the command name (e.g., `/thunderup`)
2. Locates the corresponding Markdown file in `.claude/commands/`
3. Reads the execution instructions from the skill definition
4. Runs the specified shell commands or Makefile targets in the repository root
5. Streams stdout and stderr back to the chat interface

### Subtree Synchronization

The `.thunderbot/` directory is actually a **git subtree** pointing to the standalone `thunderbot` repository. The `Makefile` provides `thunderbot-pull` and `thunderbot-push` targets to synchronize changes between the central skill repository and the Thunderbolt project, ensuring all Thunderbolt-based projects share the same command definitions.

## How Slash Commands Are Processed

When you invoke `/thunderup` with an argument like `THU-123`, the execution flow follows these steps:

1. **Command Recognition**: Claude Code identifies `/thunderup` as a registered skill and passes the argument `THU-123` to the handler defined in [`.thunderbot/thunderup.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thunderup.md).

2. **Worktree Creation**: For ticket-specific invocations, the skill executes git commands to create a new worktree for the Linear ticket **THU-123**.

3. **Environment Bootstrap**: The skill runs the underlying `make` targets sequentially:
   - `doctor-q` – validates system dependencies
   - `setup` – installs project dependencies
   - `docker-up` – starts required containers

4. **Output Streaming**: Claude Code captures the shell output from these Makefile targets and displays it in the chat interface, allowing you to monitor the bootstrap process in real-time.

This pattern repeats across all Thunderbolt skills, with each Markdown file acting as a declarative interface to the project's `Makefile` targets.

## Available Claude Code Skills in Thunderbolt

Thunderbolt includes a comprehensive suite of slash commands covering the full development lifecycle:

| Command | Description | Triggered Makefile Targets |
|---------|-------------|---------------------------|
| **`/thunderup`** | Bootstraps the development environment | `doctor-q`, `setup`, `docker-up` |
| **`/thunderup all`** | Boots environment plus starts backend (`:8000`) and frontend (`:5173`) | `doctor-q`, `setup`, `docker-up`, plus server targets |
| **`/thunderup <ticket>`** | Creates a git worktree for a Linear ticket (e.g., `THU-123`), then bootstraps | Worktree creation + standard bootstrap |
| **`/thundercheck`** | Runs type-checking, linting, and formatting | `check` |
| **`/thunderpush <message>`** | Auto-generates a conventional commit, stages relevant files, and pushes | `thunderpush` |
| **`/thunderdown`** | Stops all Docker containers used by the project | `docker-down` |
| **`/thunderbot <ticket>`** | Starts the autonomous coding agent that implements a Linear task and opens a PR | `thunderbot` |
| **`/thunderfeedback <text>`** | Opens a GitHub issue with the supplied feedback | `thunderfeedback` |

These commands are defined in the respective `.thunderbot/*.md` files and become available immediately after running `make setup-symlinks` and installing the Claude Code CLI.

## Core Files and Implementation Details

To understand or modify how Claude Code skills function in Thunderbolt, examine these specific files:

- **[`docs/claude-code.md`](https://github.com/thunderbird/thunderbolt/blob/main/docs/claude-code.md)** – Comprehensive documentation covering installation, available commands, and the high-level workflow for using Claude Code with Thunderbolt.

- **`Makefile`** – Contains the `setup-symlinks` target (lines 33-39) that bridges `.thunderbot/` to `.claude/commands/`, plus all the `thunder*` targets that implement the actual command logic.

- **[`.thunderbot/thunderup.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thunderup.md)** – Skill definition for environment bootstrapping, specifying the sequence of `make` targets to execute (lines 9-17).

- **[`.thunderbot/thundercheck.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thundercheck.md)** – Defines the code quality check command, mapping to the `check` Makefile target.

- **[`.thunderbot/thunderpush.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thunderpush.md)** – Configures the automated commit and push workflow.

- **[`.thunderbot/thunderbot.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thunderbot.md)** and **[`.thunderbot/thunderbot-daemon.md`](https://github.com/thunderbird/thunderbolt/blob/main/.thunderbot/thunderbot-daemon.md)** – Documentation and skill definitions for the autonomous coding agent.

## Summary

- **Claude Code skills in Thunderbolt** are Markdown files stored in `.thunderbot/` that define slash commands for automating development workflows.
- A **symlink bridge** created by `make setup-symlinks` connects these skills to `.claude/commands/`, enabling Claude Code CLI discovery.
- Commands like `/thunderup`, `/thundercheck`, and `/thunderpush` execute underlying **Makefile targets** that handle environment setup, code validation, and version control.
- Skills are synchronized across projects via a **git subtree** from the central `thunderbot` repository, ensuring consistent command definitions.
- The autonomous agent functionality (`/thunderbot`) extends these capabilities to fully automated task implementation and pull request creation.

## Frequently Asked Questions

### How do I install Claude Code skills in a Thunderbolt project?

First, ensure you have the Claude Code CLI installed according to the "Getting Started" section in [`docs/claude-code.md`](https://github.com/thunderbird/thunderbolt/blob/main/docs/claude-code.md). Then run `make setup-symlinks` from the repository root. This Makefile target creates symbolic links from `.thunderbot/*.md` into `.claude/commands/`, allowing the Claude Code CLI to discover and register the Thunderbolt slash commands.

### Can I modify the slash commands or create custom ones?

Yes, you can modify existing skills by editing the Markdown files in `.thunderbot/`, such as [`thunderup.md`](https://github.com/thunderbird/thunderbolt/blob/main/thunderup.md) or [`thundercheck.md`](https://github.com/thunderbird/thunderbolt/blob/main/thundercheck.md). To create custom commands, add new `.md` files to `.thunderbot/` with the required front-matter and execution instructions, then run `make setup-symlinks` to register them. If you want to share these changes across projects, use `make thunderbot-push` to sync them to the central `thunderbot` repository via the git subtree.

### What is the difference between `/thunderup` and `/thunderbot`?

`/thunderup` is a developmental utility command that bootstraps your local environment by running `make` targets like `doctor-q`, `setup`, and `docker-up`. In contrast, `/thunderbot` launches an autonomous coding agent that connects to Linear, picks up a ticket (e.g., `THU-123`), implements the required changes automatically, and opens a pull request without manual intervention.

### How does the git subtree synchronization work for skills?

The `.thunderbot/` directory is actually a git subtree pointing to a separate `thunderbot` repository. The `Makefile` provides `thunderbot-pull` and `thunderbot-push` targets that manage this synchronization. When you run `make thunderbot-push`, changes to your local `.thunderbot/` files are pushed to the central repository, while `make thunderbot-pull` fetches the latest skill definitions from the central repo into your local project.