How gh-stack Supports AI Agents Through Skills Integration

gh-stack exposes a declarative skill manifest at skills/gh-stack/SKILL.md that enables AI agents to execute the CLI non-interactively using mandatory flags, typed exit codes, and safety guardrails designed for automated environments.

The gh-stack extension transforms the GitHub CLI into a powerful branch stacking tool. Through its skills integration, the repository provides a machine-readable contract that allows AI agents to discover capabilities and invoke commands without interactive prompts, making gh-stack ideal for CI pipelines, autonomous workflows, and headless automation.

What Is the gh-stack Skills Integration?

The skills integration centers on a structured definition file that acts as a contract between the CLI and automated agents.

Declarative Skill Manifest

At skills/gh-stack/SKILL.md, the repository maintains a Markdown-based skill definition following a standard schema. This file declares the command name (gh-stack), describes capabilities, and defines agent-specific rules that govern non-interactive execution. According to the source, lines 51–60 of this manifest contain the "Agent rules" block that distinguishes automated usage from interactive workflows.

Agent-Specific Rules

The skill manifest explicitly separates human-facing TUI behavior from machine requirements. It enumerates which commands require specific flags to avoid blocking prompts, creating a deterministic interface that AI systems can rely on when generating command sequences.

Key Features for AI Agent Integration

The gh-stack skills integration provides four architectural pillars that ensure reliable automation.

Non-Interactive Enforcement

All commands that would normally spawn a TUI or prompt must include explicit flags. The skill file mandates:

• --auto for commands like gh stack submit
• --json for data retrieval commands like gh stack view
• --yes for confirmation bypasses

These requirements ensure the CLI never blocks waiting for user input. As specified in the skill manifest, gh stack submit must include --auto to function in agent contexts, while gh stack view requires --json to produce machine-readable output rather than terminal graphics.

Typed Exit-Code Contracts

The CLI defines stable exit codes in cmd/utils.go that agents can use for programmatic error handling without parsing free-form strings. Key codes include:

• Exit code 3: Indicates a rebase conflict requiring manual resolution
• Exit code 5: Signals invalid arguments

The skill manifest references this contract in the "Exit codes and error recovery" section, allowing agents to implement conditional logic based on predictable numeric returns.

Command-to-Flag Mapping

For each sub-command, the skill file maps required arguments and their semantics. For example, gh stack add -Am "message" branch combines branch creation, staging, and committing into one deterministic operation. This mapping provides a concise API surface that agents can synthesize into scripts without ambiguity.

Safety Guardrails for Headless Environments

The manifest includes a "Never do any of the following" block that explicitly warns agents about commands triggering interactive prompts. This prevents automation deadlocks in CI pipelines by prohibiting TUI-dependent invocations before they execute.

Practical Examples for AI Agents

The following bash snippets demonstrate the required flags (--auto, --json, --yes) mandated by the skill file, ensuring automated agents never encounter blocking prompts:

# 1️⃣ Initialise a stack with two layers (non‑interactive)

gh stack init auth api-routes --auto --json

# 2️⃣ Add a new branch, stage everything, and commit in one step

gh stack add -Am "Add payment endpoint" payment

# 3️⃣ Push and create PRs for the whole stack (auto‑titles only)

gh stack submit --auto --yes

# 4️⃣ Get machine‑readable stack status

output=$(gh stack view --json)
echo "$output" | jq '.branches[] | select(.needsRebase)| .name'

# 5️⃣ Rebase the entire stack, handling a possible conflict

gh stack rebase || {
  # exit code 3 ⇒ conflict; parse conflicted files, fix, then continue

  conflicted=$(gh stack rebase 2>&1 | grep -E 'conflict' | cut -d' ' -f4)
  # …resolve files…

  git add "$conflicted"
  gh stack rebase --continue
}

These examples leverage the exit-code contract defined in cmd/utils.go, specifically checking for code 3 to detect rebase conflicts that require intervention.

Source Code Architecture

The skills integration relies on specific files that collectively provide the architectural foundation for AI agent support:

• skills/gh-stack/SKILL.md – The declarative skill definition containing agent rules, flag requirements, and the exit-code contract.
• cmd/utils.go – Centralized error-code definitions (ErrSilent, ErrNotInStack, etc.) that create the typed exit interface.
• cmd/*.go (e.g., cmd/init.go, cmd/add.go) – Sub-command implementations that read flags defined in the skill manifest and return typed exit codes.
• internal/stack/schema.json – JSON schema for the on-disk stack file (.git/gh-stack), ensuring consistent state that agents can read or write via gh stack view --json.
• internal/git/gitops.go and internal/github/client_interface.go – Low-level operations that provide deterministic Git and GitHub interactions.

Summary

• skills/gh-stack/SKILL.md provides the declarative contract that AI agents use to discover gh-stack capabilities.
• Non-interactive flags (--auto, --json, --yes) are mandatory for automation, preventing blocking prompts in headless environments.
• Typed exit codes defined in cmd/utils.go (e.g., 3 for conflicts, 5 for invalid arguments) enable programmatic error handling.
• Safety guardrails in the skill manifest explicitly prohibit TUI-dependent commands, protecting CI pipelines from deadlocks.

Frequently Asked Questions

What is the gh-stack skill manifest?

The skill manifest is a file at skills/gh-stack/SKILL.md that declares the CLI's capabilities, required flags, and safety constraints in a structured format. AI agents read this file to discover how to invoke gh stack commands without interactive prompts, according to the repository's skill schema.

Which flags must AI agents use with gh-stack?

Agents must append --auto, --json, or --yes to commands that would otherwise prompt for input. For example, gh stack submit requires --auto and gh stack view requires --json to ensure machine-readable, non-blocking output as specified in the skill manifest's agent rules section.

How do agents handle errors in gh-stack?

Agents rely on typed exit codes defined in cmd/utils.go rather than parsing error strings. Exit code 3 indicates a rebase conflict requiring resolution, while code 5 signals invalid arguments. The skill manifest documents these codes in the "Exit codes and error recovery" section, allowing agents to implement conditional retry or recovery logic.

Where are the exit codes defined in the source code?

Exit codes are centralized in cmd/utils.go, which defines error constants like ErrSilent and ErrNotInStack. These constants map to specific integer codes that the CLI returns to the shell, creating a stable contract that the skill manifest references for automated error handling.

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