github-agent-runner

A Claude Code plugin for conversational discovery and installation of GitHub agentic workflows (gh-aw), with subscription-aware auth setup.

Status: v0.2.0 — agent-team pattern validated end-to-end on the playground dogfood.

What's new in v0.2.0

• agent-team pattern — four workflows (spec → plan → impl → review) that collaborate on a single issue via workflow_dispatch handoffs. Dispatch one label, get a reviewed draft PR. See catalog/agent-team/.
• /install-agent-team skill — one command installs all four roles, applies the OAuth tweak to every lockfile, and creates the label set. See skills/install-agent-team/SKILL.md.

What is this?

github-agent-runner is a Claude Code plugin that helps you add AI-powered automation to any GitHub repository. It does two things:

1. Discover — recommends 1–3 agentic workflows from a curated catalog that match your repo's shape (language, CI setup, activity level, etc.).
2. Install — walks you through fetching, authenticating, and wiring up each workflow end-to-end, including the OAuth token tweak that makes your Claude subscription work inside GitHub Actions.

Quick start

Open your repo in Claude Code (or any coding agent) and paste:

Install the github-agent-runner plugin from https://raw.githubusercontent.com/verkyyi/github-agent-runner/main/.claude-plugin/marketplace.json and recommend workflows for this repo.

The agent will add the marketplace, install the plugin, and run /discover-workflows — pick a recommendation and it hands off to /install-workflow for the full auth + setup walkthrough.

First time? Skip discovery and try the starter. Running /install-workflow with no arguments pitches daily-repo-status — a zero-risk workflow that creates a daily GitHub issue summarizing your repo activity. It only needs read + issue-create permissions and gives you something visible on your first run before committing to anything broader.

Prefer the explicit slash-command form?

/plugin marketplace add https://raw.githubusercontent.com/verkyyi/github-agent-runner/main/.claude-plugin/marketplace.json
/plugin install github-agent-runner
/discover-workflows

Both skill names are unique, so the short form works out-of-the-box. If another installed plugin ever ships the same skill name, prefix with the plugin name: /github-agent-runner:discover-workflows.

Want to hack on the plugin itself? See Local development below for the claude --plugin-dir . workflow.

How the skills work

/discover-workflows

Inspects your repo's shape (language, test presence, CI configuration, recent activity) using only local git and filesystem tools. Then fetches the current list of workflows from the upstream githubnext/agentics catalog at runtime — no local catalog to drift — reads frontmatter from the most promising candidates, and recommends up to 3 that fit, each with a one-sentence reason specific to your repo and an estimated setup friction level. Hands off directly to /install-workflow once you pick one.

All agentics workflows require Claude auth (OAuth or API-key). See skills/install-workflow/auth.md for the decision tree.

/install-workflow

Takes a workflow name (or prompts you to run /discover-workflows first) and:

1. Checks that gh CLI and gh aw extension are available, and that you have write access
2. Asks once whether you have a Claude subscription or prefer the API-key path
3. Guides you through setting the appropriate repo secret — never echoes or stores your token
4. Runs gh aw add <workflow> to compile the .lock.yml
5. For the OAuth path: applies the required two-pass post-compile tweak and verifies the grep counts
6. Runs gh aw validate and summarizes every file changed

Prerequisites

To use the plugin:

• Claude Code CLI installed and authenticated
• gh CLI authenticated (gh auth login)
• gh aw extension installed (gh extension install githubnext/gh-aw)

To run the installed workflows on your own repo:

• A Claude Pro, Max ($100), or Max ($200) subscription or an Anthropic API key
• The appropriate secret set on the repository:
  • OAuth path: CLAUDE_CODE_OAUTH_TOKEN
  • API-key path: ANTHROPIC_API_KEY
• GitHub Discussions enabled if you install weekly-research (uses the "ideas" category)

See skills/install-workflow/auth.md for the complete auth decision tree.

Authentication

Two paths are supported:

	OAuth path (preferred)	API-key path (fallback)
Who	Claude Pro / Max subscribers	Non-subscribers
Secret	CLAUDE_CODE_OAUTH_TOKEN	ANTHROPIC_API_KEY
Cost	Free (included in subscription)	Pay-per-token
Post-compile tweak	Required (two-pass sed)	Not needed

Full details — including the two-pass tweak rationale, verification grep counts, failure modes, and the ToS boundary explanation — are in skills/install-workflow/auth.md.

Important: gh aw compile reverts the OAuth tweak in .lock.yml files. Re-apply Steps 3–4 from auth.md after any recompile event (gh aw compile, gh aw upgrade, gh aw fix, or editing the .md source).

Running on this repo

This repo dogfoods three workflows on itself, chosen as genuinely useful for a small plugin project (not as a showcase of everything in the catalog):

Workflow	Trigger	Purpose
daily-repo-status	Daily	Opens a [repo-status] issue summarizing recent activity — the recommended first-run starter
update-docs	Every push to main	Detects documentation drift and opens draft PRs to keep docs in sync with code changes
weekly-research	Weekly (Monday)	Strategic research across Anthropic policy, plugin ecosystem, gh-aw upstream, competitors, and solo-founder hiring signal

All three use engine: claude and are pre-configured with the OAuth token tweak. The agent-team pattern under catalog/agent-team/ is not installed here — it lives in a separate playground repo, since running it here would aim the implementer agent at this repo's own code.

Other workflows from the catalog — repo-assist, q, pr-nitpick-reviewer, daily-plan, markdown-linter — are valuable on the right repo but were dropped here as too heavy or low-signal for a small solo-maintained plugin. All remain a /install-workflow away.

Multi-workflow patterns

Beyond the one-workflow-per-job templates above, this repo ships reference patterns for multiple workflows collaborating via the GitHub issue thread as an event bus:

• agent-team — four roles (spec → plan → impl → review) coordinating through structured comment blocks and a small internal label state machine. Install all four in one pass with /install-agent-team; dispatch tasks by opening an issue and adding a single agent-team label. Use when you want visible handoffs, human override between steps, and an audit trail per task.

Repository layout

.claude-plugin/
  plugin.json                      # plugin manifest (name, version, license)
  marketplace.json                 # self-hosted marketplace listing (enables /plugin marketplace add)

skills/
  discover-workflows/
    SKILL.md                       # /discover-workflows logic and hard rules
  install-workflow/
    SKILL.md                       # /install-workflow logic and hard rules
    auth.md                        # OAuth vs. API-key decision tree
  install-agent-team/
    SKILL.md                       # /install-agent-team unified installer (all 4 roles + labels + auth)

catalog/
  agent-team/                      # multi-workflow pattern: spec → plan → impl → review
    README.md                      # label/comment contract + install steps
    spec-agent.md
    planner-agent.md
    implementer-agent.md
    reviewer-agent.md

.github/
  agents/
    agentic-workflows.agent.md     # dispatcher agent for workflow operations
  aw/
    actions-lock.json              # gh-aw extension version lock
  workflows/
    agentics-maintenance.yml       # standard GHA workflow: gh-aw version maintenance
    copilot-setup-steps.yml        # standard GHA workflow: Copilot coding agent environment setup
    daily-repo-status.{md,lock.yml}
    update-docs.{md,lock.yml}
    weekly-research.{md,lock.yml}
    shared/
      reporting.md                 # shared reporting component (run-link formatting)

.lock.yml files are marked as linguist-generated and merge=ours in .gitattributes to prevent spurious merge conflicts.

Local development

claude --plugin-dir .

Changes to skills/*/SKILL.md take effect on the next Claude Code session reload. Changes to .lock.yml files can be validated at any time with gh aw validate (safe — does not recompile).

Publishing

Once v0.1 is scope-locked, submit via claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit.