worktrunk_skill

Overview

This skill provides practical guidance for Worktrunk, a CLI for managing Git worktrees and automating developer workflows. It focuses on configuring user and project settings, setting up LLM-based commit message generation, designing hooks, and troubleshooting common issues. Use it to configure your environment or to add team-wide automation safely and reproducibly.

How this skill works

I explain the two config scopes: user config (~/.config/worktrunk/config.toml) for personal preferences and LLM integrations, and project config (<repo>/.config/wt.toml) for team-shared hooks and automation. For each task I show how to detect tools, validate commands, propose or apply changes, and recommend tests to verify behavior. I also cover permission models, safe defaults, and patterns for spawning agent handoffs in supported multiplexers.

When to use it

• Set up LLM commit message generation for your local environment
• Add project hooks that run on worktree create, switch, pre-commit, or pre-merge
• Automate dependency install or test runs for all contributors
• Troubleshoot hook failures, LLM integration errors, or shell-integration problems
• Spawn a background agent session in tmux or Zellij for parallel work (explicit request)

Best practices

• Always validate commands exist (which npm, cargo, etc.) before adding hooks
• For user config, propose changes and get explicit consent before editing
• For project config, add explanatory comments and prefer reversible, non-destructive steps
• Avoid dangerous commands in hooks (rm -rf, DROP TABLE, sudo, uncontrolled curl)
• Test new hooks by creating a worktree (wt switch --create test-hooks) and by running dry-runs

Example use cases

• Enable LLM commit generation by detecting available tools and adding a commit.generation command to ~/.config/worktrunk/config.toml
• Add a post-create hook that runs npm install when a new worktree is created
• Add a pre-merge hook to run the test suite and block merges on failure
• Convert a single-command hook into a named table to add extra steps (install + migrate)
• Spawn a tmux session that creates a worktree and hands it to Claude for background agent work