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

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 defines the environment bootstrapping command, while .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.

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 – 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 – Skill definition for environment bootstrapping, specifying the sequence of make targets to execute (lines 9-17).

• .thunderbot/thundercheck.md – Defines the code quality check command, mapping to the check Makefile target.

• .thunderbot/thunderpush.md – Configures the automated commit and push workflow.

• .thunderbot/thunderbot.md and .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. 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 or 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}