Official agent skill

Squad Git Branching Workflow

Dev-first branching model for the Squad project: feature work branches from dev, issue branches follow a naming rule and parallel issues use git worktrees.

OfficialMITAuto-check passedDevelopment

Install Squad Git Branching Workflow

skills CLI

$ npx skills add microsoft/waza --skill git-workflow -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install microsoft/waza git-workflow --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/microsoft/waza.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.copilot/skills/git-workflow .claude/skills/git-workflow && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "git-workflow" agent skill from https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow into .claude/skills/git-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "git-workflow", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add microsoft/waza --skill git-workflow -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install microsoft/waza git-workflow --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft/waza.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.copilot/skills/git-workflow .agents/skills/git-workflow && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "git-workflow" agent skill from https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow into .agents/skills/git-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "git-workflow", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add microsoft/waza --skill git-workflow -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install microsoft/waza git-workflow --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft/waza.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.copilot/skills/git-workflow .cursor/skills/git-workflow && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "git-workflow" agent skill from https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow into .cursor/skills/git-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "git-workflow", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/microsoft/waza.git --path .copilot/skills/git-workflow

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add microsoft/waza --skill git-workflow -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install microsoft/waza git-workflow --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft/waza.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.copilot/skills/git-workflow .gemini/skills/git-workflow && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "git-workflow" agent skill from https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow into .gemini/skills/git-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "git-workflow", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install microsoft/waza git-workflow

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add microsoft/waza --skill git-workflow -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/microsoft/waza.git skills-src && mkdir -p .github/skills && cp -r skills-src/.copilot/skills/git-workflow .github/skills/git-workflow && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "git-workflow" agent skill from https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow into .github/skills/git-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "git-workflow", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add microsoft/waza --skill git-workflow -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install microsoft/waza git-workflow --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/microsoft/waza.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.copilot/skills/git-workflow .opencode/skills/git-workflow && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "git-workflow" agent skill from https://github.com/microsoft/waza/tree/main/.copilot/skills/git-workflow into .opencode/skills/git-workflow/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "git-workflow", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: git-workflow
GitHub stars: 1.4k
Used in: 4 other repos
Token cost: ~1.5k tokens
SKILL.md length: 547 words
Files: 1
Skills in repo: 16
Repo updated: Oct 6, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Dev-first branching model for the Squad project: feature work branches from dev, issue branches follow a naming rule and parallel issues use git worktrees.

Works in 6 steps: Branch from dev → Mark issue in-progress → Create draft PR targeting dev → …
Starting work on a Squad issue and choosing the right base branch
SKILL.md covers Context, Branch Naming Convention, Workflow for Issue Work and Parallel Multi-Issue Work…, plus 3 more sections
Calls git, npm and gh

What it does

The skill documents a three-branch model. The main branch holds released, tagged code that is published to npm on a tag, dev is the integration branch where all feature work lands and publishes a preview tag on merge, and insiders is an early-access channel synced from dev. Issue branches must be named squad, then the issue number and a kebab-case slug, such as squad/195-fix-version-stamp-bug.

The issue workflow runs in steps: branch from dev after pulling it, mark the issue in progress with a gh label, open a draft pull request against dev that closes the issue, do the work with commits referencing the issue, push and mark the PR ready, then update dev and delete the local branch after the merge. For several simultaneous issues in one repo it uses git worktrees, one per issue in a sibling directory named after the repo and issue number, each with its own working directory and index but a shared object store. Work across multiple repos uses separate sibling clones.

When your agent uses it

Starting work on a Squad issue and choosing the right base branch
Opening a draft pull request that targets dev
Running several issues at once with one git worktree per issue

Example prompts

“Start work on issue 42 following the Squad branching rules.”
“Set up separate worktrees so two agents can fix issues 195 and 42 in parallel.”
“The branch for issue 195 is merged, so clean up and sync dev.”

Requirements

Git and the GitHub CLI

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

Branch from dev
Mark issue in-progress
Create draft PR targeting dev
Do the work. Make changes, write tests, commit with issue reference.
Push and mark ready
After merge to dev

What it can do on your machine

Read from SKILL.md and the folder at commit 774df00. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- git
- npm
- gh
- pip
- go
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, npm, gh and pip, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Squad Git Branching Workflow loads about 1.5k tokens when it runs. Until then it costs about 21 tokens; SKILL.md has 547 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~21
When it runs · the whole SKILL.md, loaded when a task matches: ~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from microsoft/waza at commit 774df00, republished under its MIT licence (© microsoft). 547 words, ~1,529 tokens.

Download SKILL.mdSave it as .claude/skills/git-workflow/SKILL.md (or your agent's skills folder).

name: git-workflow
description: Squad branching model: dev-first workflow with insiders preview channel
domain: version-control
confidence: high
source: team-decision

Context

Squad uses a three-branch model. All feature work starts from dev, not main.

Branch	Purpose	Publishes
`main`	Released, tagged, in-npm code only	`npm publish` on tag
`dev`	Integration branch — all feature work lands here	`npm publish --tag preview` on merge
`insiders`	Early-access channel — synced from dev	`npm publish --tag insiders` on sync

Branch Naming Convention

Issue branches MUST use: squad/{issue-number}-{kebab-case-slug}

Examples:

squad/195-fix-version-stamp-bug
squad/42-add-profile-api

Workflow for Issue Work

Branch from dev:

bash

git checkout dev
git pull origin dev
git checkout -b squad/{issue-number}-{slug}

Mark issue in-progress:

bash

gh issue edit {number} --add-label "status:in-progress"

Create draft PR targeting dev:

bash

gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft

Do the work. Make changes, write tests, commit with issue reference.

Push and mark ready:

bash

git push -u origin squad/{issue-number}-{slug}
gh pr ready

After merge to dev:

bash

git checkout dev
git pull origin dev
git branch -d squad/{issue-number}-{slug}
git push origin --delete squad/{issue-number}-{slug}

Parallel Multi-Issue Work (Worktrees)

When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use git worktree to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead.

When to Use Worktrees vs Sequential

Scenario	Strategy
Single issue	Standard workflow above — no worktree needed
2+ simultaneous issues in same repo	Worktrees — one per issue
Work spanning multiple repos	Separate clones as siblings (see Multi-Repo below)

Setup

From the main clone (must be on dev or any branch):

bash

# Ensure dev is current
git fetch origin dev

# Create a worktree per issue — siblings to the main clone
git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev
git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev

Naming convention: ../{repo-name}-{issue-number} (e.g., ../squad-195, ../squad-pr-42).

Each worktree:

Has its own working directory and index
Is on its own squad/{issue-number}-{slug} branch from dev
Shares the same .git object store (disk-efficient)

Per-Worktree Agent Workflow

Each agent operates inside its worktree exactly like the single-issue workflow:

bash

cd ../squad-195

# Work normally — commits, tests, pushes
git add -A && git commit -m "fix: stamp bug (#195)"
git push -u origin squad/195-fix-stamp-bug

# Create PR targeting dev
gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft

All PRs target dev independently. Agents never interfere with each other's filesystem.

.squad/ State in Worktrees

The .squad/ directory exists in each worktree as a copy. This is safe because:

.gitattributes declares merge=union on append-only files (history.md, decisions.md, logs)
Each agent appends to its own section; union merge reconciles on PR merge to dev
Rule: Never rewrite or reorder .squad/ files in a worktree — append only

Cleanup After Merge

After a worktree's PR is merged to dev:

bash

# From the main clone
git worktree remove ../squad-195
git worktree prune          # clean stale metadata
git branch -d squad/195-fix-stamp-bug
git push origin --delete squad/195-fix-stamp-bug

If a worktree was deleted manually (rm -rf), git worktree prune recovers the state.

Show full SKILL.md (237 more words)Show less

Multi-Repo Downstream Scenarios

When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad):

Setup

Clone downstream repos as siblings to the main repo:

~/work/
  squad-pr/          # main repo
  squad-sdk/         # downstream dependency
  user-app/          # consumer project

Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use squad/{issue-number}-{slug}.

Coordinated PRs

Create PRs in each repo independently

Link them in PR descriptions:

Closes #42

**Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature)

Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli)

Local Linking for Testing

Before pushing, verify cross-repo changes work together:

bash

# Node.js / npm
cd ../squad-sdk && npm link
cd ../squad-pr && npm link squad-sdk

# Go
# Use replace directive in go.mod:
# replace github.com/org/squad-sdk => ../squad-sdk

# Python
cd ../squad-sdk && pip install -e .

Important: Remove local links before committing. npm link and go replace are dev-only — CI must use published packages or PR-specific refs.

Worktrees + Multi-Repo

These compose naturally. You can have:

Multiple worktrees in the main repo (parallel issues)
Separate clones for downstream repos
Each combination operates independently

Anti-Patterns

❌ Branching from main (branch from dev)
❌ PR targeting main directly (target dev)
❌ Non-conforming branch names (must be squad/{number}-{slug})
❌ Committing directly to main or dev (use PRs)
❌ Switching branches in the main clone while worktrees are active (use worktrees instead)
❌ Using worktrees for cross-repo work (use separate clones)
❌ Leaving stale worktrees after PR merge (clean up immediately)

Promotion Pipeline

dev → insiders: Automated sync on green build
dev → main: Manual merge when ready for stable release, then tag
Hotfixes: Branch from main as hotfix/{slug}, PR to dev, cherry-pick to main if urgent

Files

Just SKILL.md in .copilot/skills/git-workflow of microsoft/waza.

Open the folder on GitHubat commit 774df00

Used in 4 other repositories

We found 5 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 4 other GitHub owners. This page covers the copy in microsoft/waza, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Squad Git Branching Workflow next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Squad Git Branching Workflow compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Squad Git Branching Workflow this skillmicrosoft/waza	1.4k	4 repos	~1.5k	Automated safety check: Pass	MIT	yesterday
Finishing a Development Branchobra/superpowers	296k	5 repos	~1.9k	Automated safety check: Pass	MIT	yesterday
AionUi Version BumpiOfficeAI/AionUi	33k	—	~2.1k	Automated safety check: Pass	Apache-2.0	28 days ago
Clean Complete Branchesjtenniswood/espcontrol	1.1k	—	~820	Automated safety check: Pass	Custom licence	today
ZCF Release AutomationUfoMiao/zcf	6.1k	—	~3.4k	Automated safety check: Pass	MIT	1 mo ago
Markbind Typescript MigrationMarkBind/markbind	158	—	~2k	Automated safety check: Pass	MIT	1 mo ago

Similar skills

Finishing a Development Branch
obra/superpowers
Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.
296k GitHub starsUsed in 5 repos~1.9k tokens
DevelopmentAuto-check passed
AionUi Version Bump
iOfficeAI/AionUi
Automates an AionUi release: checks the latest AionCore release and its artifacts, updates package.json, writes the changelog, opens a PR and tags the release.
33k GitHub stars~2.1k tokensUpdated 28 days ago
DevelopmentAuto-check passed
Clean Complete Branches
jtenniswood/espcontrol
Clean up completed Git branches and worktrees for this repository both locally and on GitHub.
1.1k GitHub stars~820 tokensUpdated today
DevelopmentAuto-check passed
ZCF Release Automation
UfoMiao/zcf
Automates a version release with changesets: analyzes code changes, writes a bilingual CHANGELOG, bumps the version and commits through a release branch and pull request.
6.1k GitHub stars~3.4k tokensUpdated 1 mo ago
DevelopmentAuto-check passed
Markbind Typescript Migration
MarkBind/markbind
Complete guide for migrating JavaScript files to TypeScript in the MarkBind project, including the two-commit strategy, import/export syntax conversion, and best practices.
158 GitHub stars~2k tokensUpdated 1 mo ago
DevelopmentAuto-check passed
Git PR Workflow
andymai/brepjs
This skill should be used when committing, pushing, branching, or merging in the brepjs repository — when a task involves "pre-commit hook failed" (which tier ran, how to bypass), "commit rejected…
114 GitHub stars~2.9k tokensUpdated yesterday
DevelopmentAuto-check passed

Questions about Squad Git Branching Workflow

What does Squad Git Branching Workflow do?

Dev-first branching model for the Squad project: feature work branches from dev, issue branches follow a naming rule and parallel issues use git worktrees. The skill documents a three-branch model. The main branch holds released, tagged code that is published to npm on a tag, dev is the integration branch where all feature work lands and publishes a preview tag on merge, and insiders is an early-access channel synced from dev.

When should I use Squad Git Branching Workflow?

Squad Git Branching Workflow fits situations like: starting work on a Squad issue and choosing the right base branch; opening a draft pull request that targets dev; running several issues at once with one git worktree per issue.

How do I install Squad Git Branching Workflow in Claude Code?

Run `npx skills add microsoft/waza --skill git-workflow -a claude-code`. Or copy the skill folder (.copilot/skills/git-workflow in microsoft/waza) into .claude/skills/git-workflow in your project. Claude Code loads it when a task matches its description.

How do I install Squad Git Branching Workflow in Codex?

Run `npx skills add microsoft/waza --skill git-workflow -a codex`. Or copy the skill folder (.copilot/skills/git-workflow in microsoft/waza) into .agents/skills/git-workflow in your project. Codex loads it when a task matches its description.

Can I use Squad Git Branching Workflow in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add microsoft/waza --skill git-workflow -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/git-workflow, .gemini/skills/git-workflow, .github/skills/git-workflow and .opencode/skills/git-workflow in your project.

What does Squad Git Branching Workflow need to run?

Going by SKILL.md and its folder, Squad Git Branching Workflow needs the command-line tools its instructions call (git, npm, gh, pip and go). Our summary lists: Git and the GitHub CLI.

Does Squad Git Branching Workflow access the network?

SKILL.md contains no URLs. Its commands use git, npm, gh and pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Squad Git Branching Workflow safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Squad Git Branching Workflow use?

Squad Git Branching Workflow is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Squad Git Branching Workflow use?

About 1.5k tokens (SKILL.md is roughly 6.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Squad Git Branching Workflow?

Skills that share tags, products or a category with Squad Git Branching Workflow: Finishing a Development Branch (obra/superpowers, 296k stars), AionUi Version Bump (iOfficeAI/AionUi, 33k stars), Clean Complete Branches (jtenniswood/espcontrol, 1.1k stars) and ZCF Release Automation (UfoMiao/zcf, 6.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Squad Git Branching Workflow?

microsoft (a GitHub organization, an official publisher) maintains it in microsoft/waza, which has 1,400 GitHub stars. The repository holds 16 skills in this directory. The repository was last updated on October 6, 2026.

Source: microsoft/waza on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Squad Git Branching Workflow

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Context

Branch Naming Convention

Workflow for Issue Work

Parallel Multi-Issue Work (Worktrees)

When to Use Worktrees vs Sequential

Setup

Per-Worktree Agent Workflow

.squad/ State in Worktrees

Cleanup After Merge

Multi-Repo Downstream Scenarios

Setup

Coordinated PRs

Local Linking for Testing

Worktrees + Multi-Repo

Anti-Patterns

Promotion Pipeline

Files

Used in 4 other repositories

Compare with similar skills

Similar skills

More from microsoft/waza

Related

Questions about Squad Git Branching Workflow