# How gh-stack Supports AI Agents Through Skills Integration

> Learn how gh-stack integrates skills to empower AI agents. Execute CLI commands non-interactively with typed exit codes and safety guardrails for automated environments.

- Repository: [GitHub/gh-stack](https://github.com/github/gh-stack)
- Tags: deep-dive
- Published: 2026-08-03

---

**gh-stack exposes a declarative skill manifest at [`skills/gh-stack/SKILL.md`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/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:

```bash

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

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

```

```bash

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

gh stack add -Am "Add payment endpoint" payment

```

```bash

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

gh stack submit --auto --yes

```

```bash

# 4️⃣ Get machine‑readable stack status

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

```

```bash

# 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`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/skills/gh-stack/SKILL.md)** – The declarative skill definition containing agent rules, flag requirements, and the exit-code contract.
- **[`cmd/utils.go`](https://github.com/github/gh-stack/blob/main/cmd/utils.go)** – Centralized error-code definitions (`ErrSilent`, `ErrNotInStack`, etc.) that create the typed exit interface.
- **`cmd/*.go`** (e.g., [`cmd/init.go`](https://github.com/github/gh-stack/blob/main/cmd/init.go), [`cmd/add.go`](https://github.com/github/gh-stack/blob/main/cmd/add.go)) – Sub-command implementations that read flags defined in the skill manifest and return typed exit codes.
- **[`internal/stack/schema.json`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/internal/git/gitops.go)** and **[`internal/github/client_interface.go`](https://github.com/github/gh-stack/blob/main/internal/github/client_interface.go)** – Low-level operations that provide deterministic Git and GitHub interactions.

## Summary

- **[`skills/gh-stack/SKILL.md`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/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`](https://github.com/github/gh-stack/blob/main/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.