BUCKYVERSE

Git Town Skill - Usage Guide

This skill helps you execute Git Town workflow commands for efficient branch management in the Buckyverse repository. Use xp_work for work-item tracking and add-book-to-buckyverse / pdf-to-wikijs-markdown for book-source and PDF workflows.

How to Use

Automatic Invocation

The skill is automatically invoked when you mention any of these terms in your chat:

Manual Invocation

You can also manually invoke the skill by typing:

/git-town

Use this skill only for branch lifecycle commands.

Then describe what you want to do (e.g., "create a branch called add-user-auth" or "sync my current branch").

Examples

Creating a Feature Branch

I want to hack a new branch called add-user-authentication

or

git town hack add-user-authentication

The agent will:

  1. Execute git town hack add-user-authentication
  2. Create the branch from main
  3. Switch to the new branch
  4. Confirm the branch was created

Syncing Your Branch

sync my current branch

or

git town sync

The agent will:

  1. Execute git town sync
  2. Pull latest changes from main
  3. Merge them into your current branch
  4. Push the updated branch to origin
  5. Confirm the sync completed

Note: This must be run from within a feature branch (not from main).

Shipping Your Branch

ship this branch to main

or

git town ship

The agent will:

  1. Execute git town ship
  2. Perform a squash merge (preserving all commit messages)
  3. Merge the branch into main
  4. Delete the branch locally
  5. Delete the branch on GitHub
  6. Push main to origin
  7. Confirm the branch was shipped

Note: This must be run from within the feature branch you want to ship.

Workflow Commands

1. git town hack <BRANCH_NAME>

Purpose: Create a new feature branch from main.

When to use:

Example:

git town hack fix-login-bug

What happens:

2. git town sync

Purpose: Update your current branch with the latest changes from main.

When to use:

Example:

git town sync

What happens:

Requirements: Must be run from within a feature branch (not from main).

3. git town ship

Purpose: Complete your work and merge the feature branch to main.

When to use:

Example:

git town ship

What happens:

Requirements: Must be run from within the feature branch you want to ship.

Typical Workflow

The standard development workflow follows this pattern:

  1. Start work: git town hack <BRANCH_NAME>

    git town hack add-dark-mode

  2. Make changes: Edit files, commit changes as usual

    git add .
git commit -m "feat: add dark mode toggle"

  3. Stay updated (as needed): git town sync

    git town sync

  4. Complete work: git town ship

    git town ship

Configuration

The repository's Git Town configuration is stored in .git-branches.toml (project root):

You don't need to configure anything—it's already set up for the project.

What the Skill Does

✅ Executes Git Town commands directly
✅ Creates feature branches from main
✅ Syncs branches with latest main changes
✅ Ships branches to main with squash merge
✅ Handles branch cleanup (local and remote deletion)
✅ Pushes changes to origin automatically
✅ Provides clear feedback on command execution

What the Skill Does NOT Do

❌ Make code changes
❌ Commit your changes (you still commit manually)
❌ Resolve merge conflicts automatically
❌ Review your code
❌ Run tests before shipping

The skill only executes Git Town commands. You're still responsible for:

Tips

  1. Always sync before shipping: Run git town sync before git town ship to ensure your branch is up-to-date with main

  2. Use descriptive branch names: Choose clear, descriptive branch names that indicate what you're working on

    • ✅ Good: add-user-authentication, fix-login-bug, improve-error-handling
    • ❌ Avoid: test, fix, update, changes

  3. Commit frequently: Make regular commits as you work - they'll all be preserved in the squash merge

  4. Test before shipping: Make sure your code works and tests pass before running git town ship

  5. Handle conflicts promptly: If git town sync encounters conflicts, resolve them before continuing

  6. Check your branch: Make sure you're on the correct branch before running commands (especially ship)

  7. Don't ship from main: Never run git town ship from main or perennial branches - only from feature branches

Error Handling

If a command fails, the agent will:

  1. Show you the error message
  2. Explain what went wrong
  3. Suggest how to resolve it

Common issues and solutions:

Viewing the Skill

To view this skill in Cursor:

  1. Open Cursor Settings (Cmd+Shift+J on Mac, Ctrl+Shift+J on Windows/Linux)
  2. Navigate to Rules
  3. Look for git-town in the Agent Decides section

Additional Resources