This skill should be used when the user asks to "create a feature branch", "start a new feature", "sync my branch", "sync with main", "update from main", "create a PR", "create a pull request", "ship a feature", "merge and clean up", "handle merge conflicts", "resolve conflicts in git-town", "create stacked branches", "work on dependent features", "configure git-town", "set up git-town", "use git-town offline", "manage git workflow", or mentions git-town commands (hack, sync, propose, ship, continue, undo, kill).
Autonomously executes git-town workflows for branch management, PR creation, and conflict resolution. Triggered by requests to create/sync branches, make PRs, ship features, or handle merge conflicts.
/plugin marketplace add FortiumPartners/ensemble/plugin install ensemble-git@ensembleThis skill inherits all available tools. When active, it can use any tool Claude has access to.
COMPLETION_SUMMARY.mdERROR_HANDLING.mdREADME.mdREFERENCE.mdTESTING.mdcicd/INTEGRATION.mdcicd/examples/github-actions.ymlcicd/examples/gitlab-ci.ymlguides/agent-skill-integration.mdguides/migration-git-flow.mdguides/migration-github-flow.mdguides/migration-trunk-based.mdguides/monorepo.mdguides/onboarding.mdscripts/test-validate.shscripts/validate-git-town.shtemplates/SKILL_TEMPLATE.mdtemplates/interview-branch-creation.mdtemplates/interview-completion.mdtemplates/interview-pr-creation.mdSkill Type: Technical Workflow Estimated Learning Time: 30 minutes Proficiency Levels: Beginner, Intermediate, Advanced
Provide comprehensive git-town workflow integration for Claude Code agents, enabling autonomous branch management, PR creation, and error recovery without interactive prompts. This skill empowers agents to execute complex git workflows with zero user intervention by leveraging git-town's CLI flags for non-interactive operation. Target audience includes orchestrator agents (tech-lead-orchestrator, git-workflow) and developer agents (frontend-developer, backend-developer) performing feature development, bug fixes, and release workflows. Key capabilities include validation-first execution with structured exit codes, standardized error handling patterns for merge conflicts and remote failures, stacked branch workflows for complex features, offline development mode support, and GitHub CLI integration for automated PR creation. Agents using this skill can autonomously manage the complete feature lifecycle from branch creation through PR merge without requiring user intervention for routine git operations.
Git-town skill files are located using XDG Base Directory Specification with the following search priority:
$XDG_CONFIG_HOME/ensemble/skills/git-town/ (user-specific configuration)~/.config/ensemble/skills/git-town/ (default XDG location)~/.ensemble/skills/git-town/ (backward compatibility)<plugin-root>/packages/git/skills/git-town/ (bundled with ensemble-git plugin)Agents should check paths in order and use the first match. Plugin-bundled files serve as the fallback when user configuration is absent.
Git-town skill loading is optimized for agent efficiency with the following performance characteristics:
Performance is measured across three tiers: full skill load for orchestrators requiring comprehensive git-town knowledge, section queries for developers needing specific command documentation, and template loads for one-time configuration tasks. Benchmark results show 95th percentile latency of 85ms for full loads and 28ms for section queries on standard SSD hardware.
Agents integrate this skill using two primary patterns optimized for different workflow requirements:
Full skill load: Load all three core files (SKILL, REFERENCE, ERROR_HANDLING) into agent context at session start. Recommended for orchestrator agents (tech-lead-orchestrator, git-workflow) that perform frequent git operations.
Section queries: Query specific subsections using namespaced identifiers like git-town:REFERENCE:git-town hack for targeted information retrieval. Ideal for developer agents needing occasional git-town command reference.
Example integration in agent YAML frontmatter:
---
name: git-workflow
skills:
- git-town:SKILL
- git-town:REFERENCE
- git-town:ERROR_HANDLING
---
The skill system automatically handles path resolution, caching, and version compatibility checks during load operations.
Before using git-town commands, ensure the following requirements are met:
git town config set-main-branch mainRun the validation script before executing git-town workflows to ensure all prerequisites are met:
# From the git-town skill directory
bash ./scripts/validate-git-town.sh
# Or with absolute path using skill root
bash ${ENSEMBLE_SKILL_ROOT}/scripts/validate-git-town.sh
Exit codes:
0: All checks passed, ready to use git-town1: git-town not installed (install via brew install git-town or equivalent)2: git-town not configured (run git town config set-main-branch main)3: git-town version < 14.0.0 (upgrade required)4: Not in a git repository (navigate to repository root)The core git-town workflow consists of five primary commands:
Create feature branch: git-town hack feature-name --parent main
--parent flagMake commits: Standard git commit workflow
git add .git commit -m "feat: implement feature"Sync with parent: git-town sync
Create PR: git-town propose --title "Feature Title" --body "Description"
Complete feature: git-town ship
To ensure zero-prompt execution, always use these flags:
--parent <branch>: Specify parent branch explicitly (prevents interactive parent selection)--prototype: Mark branch as prototype (won't sync with parent, useful for experiments)--draft: Create draft PR instead of ready-for-review PR--abort: Abort in-progress git-town operation and return to pre-operation state--continue: Continue git-town operation after resolving merge conflictsUse case: Create new feature branch without interactive prompts
# Explicit parent specification (recommended for agents)
git-town hack implement-user-auth --parent main
# Prototype branch (experimental work, won't sync with parent)
git-town hack experiment-new-architecture --prototype
# Check current branch configuration
git town config get-parent # Returns: main
Why this works: The --parent flag eliminates interactive prompts that would block agent execution.
Use case: Build dependent feature branches (e.g., refactor → implement → polish)
# Create parent feature branch
git checkout main
git-town hack refactor-auth-layer --parent main
# Make commits to refactor
git commit -m "refactor: extract auth service"
# Create child branch from current feature branch
git-town hack implement-oauth --parent refactor-auth-layer
# Git-town automatically tracks parent relationship
git town config get-parent # Returns: refactor-auth-layer
Why this works: Git-town maintains parent-child relationships, enabling agents to build complex feature hierarchies.
Use case: Handle merge conflicts during sync or ship operations
# Attempt sync, encounters merge conflict
git-town sync
# Exit code: 5 (EXIT_MERGE_CONFLICT)
# Resolve conflicts manually or via agent
git add src/auth.js # Mark conflict as resolved
# Continue git-town operation
git-town continue
# Exit code: 0 (success)
# Alternative: Abort if conflicts are unresolvable
git-town sync --abort
Why this works: Git-town provides explicit continue/abort commands with predictable exit codes for agent error handling.
Use case: Develop without remote access (network issues, air-gapped environments)
# Enable offline mode (disables remote operations)
git-town offline
# Work locally (hack, commit, sync local branches)
git-town hack offline-feature --parent main
git commit -m "feat: add offline capability"
git-town sync # Only local sync, no push
# Disable offline mode when network is restored
git-town offline --off
# Now sync with remote
git-town sync # Pushes to remote
Why this works: Offline mode allows agents to continue workflows during network outages.
For up-to-date git-town documentation, use Context7 MCP instead of static skill files.
✅ Always current - Fetches latest git-town documentation ✅ No maintenance - Automatically includes new features ✅ Version-aware - Matches installed git-town version ✅ Reduced skill size - No need for 2000+ lines of command docs
// Import ensemble-core utilities
const { checkContext7Available, createLibraryHelper } = require('@fortium/ensemble-core');
// Check if Context7 is available
if (checkContext7Available()) {
// Create git-town helper
const gitTown = createLibraryHelper('git-town');
// Fetch command documentation
const hackDocs = await gitTown.fetchDocs('hack command', 3000);
const configDocs = await gitTown.fetchDocs('configuration', 5000);
} else {
// Show installation instructions
const { getContext7InstallInstructions } = require('@fortium/ensemble-core');
console.log(getContext7InstallInstructions());
// Fall back to local documentation
}
Query git-town commands:
await gitTown.fetchDocs('hack command'); // Create feature branch
await gitTown.fetchDocs('sync command'); // Synchronize branch
await gitTown.fetchDocs('propose command'); // Create pull request
await gitTown.fetchDocs('ship command'); // Merge and cleanup
Query advanced topics:
await gitTown.fetchDocs('stacked branches'); // Advanced branching
await gitTown.fetchDocs('configuration'); // Config options
await gitTown.fetchDocs('troubleshooting'); // Error handling
Use withContext7Fallback for automatic fallback to local docs:
const { withContext7Fallback } = require('@fortium/ensemble-core');
const docs = await withContext7Fallback('git-town', 'hack command', async () => {
// Fallback: Use local REFERENCE.md
const fs = require('fs');
const path = require('path');
const refPath = path.join(__dirname, 'REFERENCE.md');
return fs.readFileSync(refPath, 'utf8');
});
If Context7 is not available, agents should provide these instructions:
# 1. Find Context7 in MCP catalog
mcp-find --query "context7"
# 2. Install Context7 MCP
mcp-add context7
# 3. Verify installation
# Context7 should now be available
# 4. Retry your git-town command
When Context7 is unavailable, query local skill sections:
git-town:REFERENCE:git-town hack → Returns only the git-town hack command sectiongit-town:ERROR_HANDLING:merge conflicts → Returns merge conflict resolution workflowgit-town:REFERENCE:exit-codes → Returns exit code reference tablePerformance benefit: Section queries return in ~30ms (vs ~100ms for full skill load) due to caching and indexing.
Context7 vs Local Comparison:
| Aspect | Context7 (Recommended) | Local Docs (Fallback) |
|---|---|---|
| Freshness | Always latest | May be outdated |
| Maintenance | Automatic | Manual updates needed |
| Size | Minimal local storage | ~2000 lines |
| Performance | Network-dependent (~200ms) | Fast local access (~30ms) |
| Offline | Requires network | Always available |
Optimize skill loading based on agent requirements:
Full load (~100ms): Load SKILL + REFERENCE + ERROR_HANDLING at agent initialization
Section query (~30ms): Load only required sections on-demand
Template load (~15ms): Load single template file for interview workflows
Caching strategy: Skill content is cached with file modification time (mtime) as cache key. Cache invalidation occurs when mtime changes.
Git-town's propose command requires GitHub CLI (gh) for PR creation:
# Ensure gh is installed and authenticated
gh auth status
# Create PR with git-town (delegates to gh)
git-town propose \
--title "feat: implement user authentication" \
--body "Adds OAuth 2.0 support with JWT tokens" \
--draft
# Git-town automatically links PR to current branch
Agent workflow: Always validate gh auth status (exit 0) before using git-town propose.
For complex features spanning multiple PRs:
# Create base feature branch
git-town hack auth-refactor --parent main
git commit -m "refactor: extract auth service"
git-town propose --title "Refactor: Auth Service" --draft
# Create dependent feature on top
git-town hack oauth-implementation --parent auth-refactor
git commit -m "feat: implement OAuth"
git-town propose --title "Feature: OAuth Support" --draft
# Ship child PR first (if approved independently)
git checkout oauth-implementation
git-town ship # Merges to auth-refactor (parent), not main
# Ship parent PR
git checkout auth-refactor
git-town ship # Merges to main
Why this works: Git-town's parent tracking ensures child branches merge to correct parents.
Symptom: Agent reports "git-town skill not found" or similar error.
Resolution steps:
Check XDG paths are correct:
echo $XDG_CONFIG_HOME # Should be ~/.config or custom path
ls -la $XDG_CONFIG_HOME/ensemble/skills/git-town/
Verify plugin installation:
claude plugin list | grep ensemble-git
# Should show: ensemble-git@5.0.0 (or later)
Reinstall plugin if missing:
claude plugin install ensemble-git --scope local
Check file permissions:
# From the git-town skill directory
chmod +r *.md
Symptom: validate-git-town.sh exits with non-zero code.
Resolution by exit code:
Exit 1 (git-town not installed):
# macOS
brew install git-town
# Linux
curl -L https://github.com/git-town/git-town/releases/download/v14.0.0/git-town_linux_amd64 -o /usr/local/bin/git-town
chmod +x /usr/local/bin/git-town
# Verify
git-town version # Should be >= 14.0.0
Exit 2 (git-town not configured):
# Configure main branch
git town config set-main-branch main
# Verify
git town config get-main-branch # Returns: main
Exit 3 (git-town version too old):
# Upgrade git-town
brew upgrade git-town # macOS
# Or download latest release manually
git-town version # Should be >= 14.0.0
Exit 4 (not in git repository):
# Navigate to repository root
cd /path/to/your/repository
# Or initialize new repository
git init
Symptom: Git-town command hangs waiting for user input.
Root cause: Missing non-interactive flags like --parent, --title, --body.
Resolution:
Always specify explicit flags:
# Bad (interactive)
git-town hack new-feature
# Good (non-interactive)
git-town hack new-feature --parent main
Use --prototype for experimental branches:
git-town hack experiment --prototype
Pre-configure defaults in git config:
git town config set-main-branch main
git town config set-perennial-branches "main,develop,staging"
Symptom: git-town sync exits with code 5 (EXIT_MERGE_CONFLICT).
Resolution workflow:
Identify conflicted files:
git status # Shows files with conflicts
Resolve conflicts (manually or via agent):
# Agent edits conflicted files to resolve markers
git add src/conflicted-file.js
Continue git-town operation:
git-town continue # Resumes sync operation
If conflicts are unresolvable, abort:
git-town sync --abort # Returns to pre-sync state
See also: ERROR_HANDLING.md section "Merge Conflict Resolution" for detailed workflows.
Symptom: git-town sync or git-town propose exits with code 7 (EXIT_REMOTE_ERROR).
Common causes:
Network connectivity: Check internet connection
ping github.com
Authentication failure: Verify git credentials
gh auth status # GitHub CLI authentication
git config credential.helper # Git credential manager
Remote repository not found: Verify remote URL
git remote -v # Check remote URLs
Resolution: Fix underlying issue (network, auth, remote URL) and retry operation.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.