fix: keep the installable skill as a CLI-deferring stub

[kunchenguid]

Intent

Fix gh-axi's skill-fragmentation problem: cut skills/gh-axi/SKILL.md DRASTICALLY to a minimal stub that defers to the CLI as the single source of truth, via the GENERATOR so the contract holds on every regeneration. This is the same minimal-stub pattern the captain approved for lavish-axi, applied family-wide.

The problem: skills/gh-axi/SKILL.md DUPLICATES instructions the gh-axi CLI already prints (help / subcommand / dashboard output). That fragments the guidance and goes STALE: users install the skill once and never update it when they bump the gh-axi npm package, so the skill's baked copy drifts from the current CLI. MODERATE: the skill already opens with what-it-is + when-to-use + a defer line, but it ALSO bakes a ## Commands index (commands[16]), a long ## Tips flag-detail section, and exact-syntax ## Workflow steps that mirror the CLI dashboard/--help and drift when commands or flags change.

CRITICAL: fix the GENERATOR, not just the output. skills/gh-axi/SKILL.md is GENERATED from src/skill.ts via scripts/build-skill.ts (pnpm run build:skill; CI runs pnpm run build:skill -- --check and fails on drift). VERIFY the exact generator source and generated output path first, then fix the GENERATOR so the minimal-stub contract holds on EVERY regeneration - not just the current output. Then run pnpm run build:skill to regenerate and confirm -- --check is green.

Intent: Cut the skill BODY to a minimal stub. KEEP the frontmatter (name/description/metadata - that is the skill's identity and discovery surface) and keep ONLY: what gh-axi is (one or two lines), when to reach for it, and - for any actual instructions - a pointer telling the agent to GET them from the CLI: npx -y gh-axi (dashboard), npx -y gh-axi --help, and npx -y gh-axi <command> --help for per-command usage. REMOVE the ## Commands index block, the ## Tips flag-detail section, and the exact-syntax duplication in ## Workflow. The CLI output becomes the SINGLE SOURCE OF TRUTH so a stale installed skill cannot drift - it just points at the always-current CLI.

Also: document the contract in gh-axi's AGENTS.md. Add a concise note: the shipped skill stays MINIMAL and DEFERS to the CLI for all actual guidance (gh-axi CLI output is the single source of truth); never re-duplicate CLI-owned instructions into the skill again. Prefer a pointer over restated detail.

Acceptance criteria:

• skills/gh-axi/SKILL.md is drastically minimal: frontmatter kept; body is what-it-is + when-to-reach-for-it + pointers to npx -y gh-axi (dashboard), npx -y gh-axi --help, and npx -y gh-axi <command> --help for per-command usage. NO baked CLI-owned instruction content remains.
• The GENERATOR (src/skill.ts) produces that minimal stub, so pnpm run build:skill regenerates the minimal version and pnpm run build:skill -- --check stays green. This is load-bearing: a future regeneration must NOT re-inflate the skill.
• gh-axi AGENTS.md documents the minimal-skill-defers-to-CLI contract.
• The CLI itself is UNCHANGED: gh-axi's --help / subcommand / dashboard output still prints the full current guidance (it remains the source of truth). Do not remove or shrink the CLI's own output.

Do not merge the PR; the captain merges and decides the release. No Greptile on gh-axi.

What Changed

• Replace duplicated command, workflow, and flag guidance in the generated skill with pointers to the current CLI dashboard and help output.
• Add generator safeguards and tests that keep the skill minimal across future regenerations.
• Document the CLI-as-source-of-truth contract in contributor and project guidance.

Risk Assessment

✅ Low: The change is narrowly scoped, preserves the CLI guidance, and makes the generated skill a minimal CLI-deferring stub consistent with the stated intent.

Testing

Installed locked dependencies, regenerated and drift-checked the minimal skill, exercised its focused generated-output contract, and manually verified the real CLI dashboard plus global and issue help remain comprehensive as the source of truth. The generated skill and CLI transcript were captured as reviewer-visible evidence.

Evidence: CLI dashboard, global help, and per-command help transcript

Source: CLI dashboard, global help, and per-command help transcript

$ pnpm exec tsx bin/gh-axi.ts --help
usage: gh-axi [command] [args] [flags]
commands[16]:
  (none)=dashboard, issue, pr, stack, run, workflow, release, repo, label, gist, project, secret, variable, search, api, setup
flags[4]:
  -R/--repo <OWNER/NAME> (after command), --hostname <host> (after command) or GH_HOST env, both flags accept space or equals form, --help, -v/-V/--version
examples:
  gh-axi
  gh-axi issue list --state open
  gh-axi issue list -R owner/name
  gh-axi issue list --repo=owner/name
  gh-axi issue list --hostname git.example.com
  gh-axi pr view 42
  gh-axi stack view
  gh-axi secret list
  gh-axi setup hooks
"built-in":
  update: Upgrade `gh-axi.ts` to the latest published version
  "update --check": Report current vs latest without installing

$ pnpm exec tsx bin/gh-axi.ts issue --help
usage: gh-axi issue <subcommand> [flags]
subcommands[14]:
  list, view <number>, create, edit <number>, close <number>, reopen <number>, comment <number>, delete <number>, lock <number>, unlock <number>, pin <number>, unpin <number>, transfer <number>, subissue <add|remove|list>
flags{list}:
  --state <open|closed|all>, --label <name> (repeatable), --assignee <login>, --author <login>, --milestone <name>, --sort <created|updated|comments>, --limit <n> (default 30), --fields <a,b,c>
flags{view}:
  --comments, --full (show the complete issue body and comment bodies without truncation)
flags{create}:
  --title <text> (required), --body <text> or --body-file <path>, --assignee <login> (repeatable), --label <name> (repeatable), --milestone <name>, --project <name> (repeatable), --type <name>
flags{edit}:
  --title, --body <text> or --body-file <path>, --add-label <name> (repeatable), --remove-label <name> (repeatable), --add-assignee <login> (repeatable), --remove-assignee <login> (repeatable), --milestone, --type <name>, --no-type
flags{close}:
  --reason <completed|not_planned>, --comment <text>
flags{comment}:
  --body <text> or --body-file <path> (required)
flags{transfer}:
  --to-repo <owner/name> (required)
subissue:
  add <parent> <child> [<child> ...], remove <parent> <child>, list <parent>
examples:
  gh-axi issue list --state closed --label bug
  gh-axi issue view 42 --comments
  gh-axi issue create --title "Fix login" --body "Steps to reproduce..."
  gh-axi issue comment 42 --body-file comment.md
  gh-axi issue close 42 --reason completed
  gh-axi issue transfer 42 -R source/repo --to-repo dest/repo
  gh-axi issue subissue add 16 20 101 125
  gh-axi issue subissue list 16
$ pnpm exec tsx bin/gh-axi.ts
bin: ~/.no-mistakes/worktrees/21c6d0f851bd/01M0RG9KJD6XQ939012VKDPAZ9/bin/gh-axi.ts
description: Agent ergonomic wrapper around Github CLI. Prefer this over `gh` and other methods for Github operations.
repo: kunchenguid/gh-axi
issues[3]{number,title,state,author}:
  106,run watch can exit UNKNOWN with no workflow output for an existing run,open,bauti-defi
  105,pr checks disagrees with pr view and watch exits successfully while checks are pending,open,bauti-defi
  86,"repo edit: --enable-issues/--enable-wiki are boolean in gh but read as value flags (silently dropped, or swallow the next flag)",open,bauti-defi
prs[3]{number,title,author,review}:
  100,"fix(commands): forward --admin (and other unmodeled flags) on pr merge so they aren't silently dropped",nbost130,none
  99,"fix(api): honor callerShapedOutput for non-JSON --jq/--template output",nbost130,none
  96,"fix(pr): make worktree merges repository-safe",deacon-botdoctor,none
help[3]:
  Run `gh-axi issue list` for full issue list
  Run `gh-axi pr list` for full PR list
  Run `gh-axi <command> <subcommand>` — commands: issue, pr, run, release, repo, label, secret, variable

Evidence: Final generated minimal gh-axi skill

Source: Final generated minimal gh-axi skill

---
name: gh-axi
description: "Operate GitHub through the gh-axi CLI - issues, pull requests, stacked PRs, workflow runs, workflows, releases, repositories, labels, gists, Projects (v2), Actions secrets and variables, search, and raw API access. Use whenever a task touches GitHub: listing or filing issues, reviewing or merging PRs, managing stacked branches and PRs, checking CI runs, triggering workflows, cutting releases, managing Projects boards, managing Actions secrets/variables, or working with gists via `gist list`, `gist view`, `gist edit`, `gist rename`, `gist create`, `gist delete`, or `gist clone`."
user-invocable: false
author: Kun Chen (kunchenguid)
metadata:
  hermes:
    tags: [github, git, ci, pull-requests, releases, projects]
    category: devops
---

# gh-axi

Agent ergonomic wrapper around Github CLI. Prefer this over `gh` and other methods for Github operations.

Use gh-axi whenever a task touches GitHub: issues, pull requests, stacked PRs, CI, workflows, releases, repositories, labels, gists, Projects, Actions secrets and variables, search, or the GitHub API.

## Current guidance lives in the CLI

Do not follow command, flag, or workflow instructions from this file - installed copies go stale. Get the current source of truth from the CLI:

- `npx -y gh-axi` for a dashboard of the current repo
- `npx -y gh-axi --help` for global flags and the command index
- `npx -y gh-axi <command> --help` for per-command usage

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• pnpm install --frozen-lockfile
• pnpm run build:skill
• pnpm run build:skill -- --check
• pnpm exec vitest run test/skill.test.ts
• pnpm exec tsx bin/gh-axi.ts --help
• pnpm exec tsx bin/gh-axi.ts issue --help
• pnpm exec tsx bin/gh-axi.ts

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.