First-party coding-agent skills wrapping the gh aw CLI

[verkyyi]

Use case

Users driving agentic workflows from inside a coding agent (Claude Code, Copilot CLI, Codex) currently have two options:

1. Exit the agent, run gh aw commands manually, come back.
2. Ask the agent to run gh aw for them — at which point the agent shells out, scrapes human-formatted CLI output, and hopes nothing parses wrong.

Both are friction. A first-party skills wrapper around the existing CLI gives those users an agent-native surface for the same verbs — the CLI stays canonical, skills are one more way to drive it.

gh-aw already has .github/skills/ (debugging-workflows, documentation) for internal agentic workflows, so the skill format is already part of the project's vocabulary. This proposal extends the pattern outward — skills for the end user's coding agent, shipped from this repo.

Proposal

Ship a set of official skills that wrap gh aw CLI verbs. Each skill is a thin conversational adapter — no duplicated logic, no new data model, just agent-native framing over subprocess calls.

Minimum v1 surface (maps 1:1 to CLI verbs):

Skill	Wraps	Responsibility
discover-workflows	gh aw list (+ catalog README)	Inspect repo, propose N workflows from the agentics catalog
install-workflow	gh aw add <name>	Install chosen workflow, walk user through required gh secret set calls
compile-workflows	gh aw compile	Compile .md → .lock.yml, surface errors conversationally
audit-workflows	gh aw audit	Run audit, summarize findings with fix suggestions
debug-workflow-run	gh aw logs --run <id>	Fetch logs for a failed run, diagnose, propose fix

Per-skill shape:

• YAML frontmatter with name and description (description drives agent auto-invocation — must be specific)
• Shell out to gh aw via subprocess; parse stdout/stderr
• Handle clarifying questions, output interpretation, error recovery
• Hand back to the user for interactive prompts (gh secret set, auth flows)

Proposed packaging

Two options; I'd suggest (A):

A. Ship inside this repo. New directory skills/ or .github/user-skills/. A new CLI verb (gh aw skills install) copies the bundle into the user's ~/.claude/skills/ or equivalent. Users who already have gh-aw get the skills with one command.

B. Separate repo github/gh-aw-skills. Keeps the core repo lean but adds a discovery step for users.

Example skill: install-workflow

---
name: install-workflow
description: Use when the user wants to install an agentics workflow from the gh-aw catalog into the current repo. Handles workflow selection, secret wiring (including CLAUDE_CODE_OAUTH_TOKEN for Claude Pro/Max subscribers), and initial compile verification.
---

# Install an agentics workflow

## Steps

1. If the user hasn't named a workflow, run `gh aw list` and propose 3 candidates based on repo language/framework signals.
2. Confirm choice with the user.
3. Run `gh aw add <name>`.
4. Parse required secrets from the installed workflow's frontmatter (or from compile-stage errors if any).
5. For each required secret, run `gh secret list` to check presence; for missing ones, instruct the user to run `gh secret set <NAME>`.
6. Run `gh aw compile` to verify `.lock.yml` generates cleanly.
7. Summarize: workflow installed, secrets set, recommended next step (push or trigger first run).

## Hand back to the user for

- Interactive secret entry (`gh secret set` prompts for value)
- Ambiguous workflow choices — always confirm, never guess
- Auth flows (`claude setup-token`, etc.)

Other v1 skills follow the same shape.

Implementation sketch

• Location: skills/ at repo root (suggested), one subdirectory per skill.
• Installer verb: cmd/gh-aw/skills.go — a new skills subcommand with install / list / path actions. skills install resolves the target directory (~/.claude/skills/ for Claude Code; overridable via flag) and copies files.
• Agent-target flag: gh aw skills install --agent claude-code|copilot|codex — for v1, Claude Code only; other agents are stubs that map the same skills to each platform's plugin format in later iterations.
• Tests: integration tests that invoke each skill's underlying gh aw call against a fixture repo and assert the expected CLI call happened (skills themselves are declarative markdown; the test surface is the CLI contract they rely on).

Scope questions for maintainers

1. Agent targets. Start with Claude Code (most mature skill format)? Or try to cover Copilot CLI + Codex in v1?
2. Packaging preference. (A) in-repo with gh aw skills install, or (B) separate gh-aw-skills repo?
3. OAuth tweak absorption. install-workflow currently has to apply a post-compile .lock.yml patch for Claude Pro/Max users (CLAUDE_CODE_OAUTH_TOKEN vs ANTHROPIC_API_KEY). Should that become a documented step in the skill, or is there a path to supporting it natively in gh aw compile frontmatter?

Prior art

I've prototyped this externally at https://github.com/verkyyi/github-agent-runner — Claude Code plugin with discover and install skills wrapping gh aw. Works end-to-end but reinvents the wheel; the skills layer naturally belongs next to the CLI rather than downstream of it.

Happy to turn any single skill (starting with install-workflow or discover-workflows) into a full implementation-ready plan if the direction resonates.