Claude-skill-registry gh-workflows

When to Use

Use this skill whenever you need to inspect, trigger, or stop GitHub Actions workflows. It wraps

gh workflow

and

gh run

commands so you can keep CI pipelines healthy without leaving the terminal.

Prerequisites

1. gh

   CLI authenticated with

   gh auth login --scopes repo,workflow

   . Confirm via

   gh auth status

   .

2. jq

   available to pretty-print JSON results.
3. Environment:

   • GITHUB_REPOSITORY

     (owner/name). Ask for it if missing.

   • GITHUB_TOKEN

     (gh uses it automatically once authenticated).

   • DEFAULT_BRANCH

     (fallback for manual dispatches; default to

     main

     ).

Common Parameters

• --repo "$GITHUB_REPOSITORY"

  is required for every command.

• --json ... --jq '.'

  returns machine-friendly payloads.
• When scripts provide

  workflow

  names, accept either filename (

  deploy.yml

  ) or workflow ID.

Procedures

List Workflows (

/workflows-list

)

1. Run:

   gh workflow list --repo "$GITHUB_REPOSITORY" --limit ${LIMIT:-20} --json id,name,path,state

   .
2. Use

   jq

   to format the response.
3. Summarize key fields: name, path, state, and id so downstream commands can use them.

List Workflow Runs (

/workflows-runs

)

1. Require a workflow identifier.
2. Optional filters:
   • Branch:

     --branch ${BRANCH}

     (omit if empty).
   • Status:

     --status ${STATUS:-all}

     .
3. Command:

   gh run list --repo "$GITHUB_REPOSITORY" \
     --workflow "$WORKFLOW" \
     ${BRANCH:+--branch "$BRANCH"} \
     --status ${STATUS:-all} \
     --limit ${LIMIT:-20} \
     --json databaseId,workflowName,displayTitle,headBranch,status,conclusion,createdAt
   

4. Pipe to

   jq '.'

   and surface the most recent run id for convenience.

View a Workflow Run (

/workflows-view

)

1. Accept a

   run_id

   (numeric or URL) and optional

   --log

   flag.
2. Command:

   gh run view "$RUN_ID" --repo "$GITHUB_REPOSITORY" \
     --json databaseId,workflowName,displayTitle,event,headBranch,status,conclusion,logsUrl,htmlUrl
   

3. Share the JSON and hyperlink to

   logsUrl

   /

   htmlUrl

   for quick navigation.

Cancel a Run (

/workflows-cancel

)

1. Confirm the run is in

   in_progress

   or

   queued

   state (use

   gh run view

   ).
2. Command sequence:

   gh run cancel "$RUN_ID" --repo "$GITHUB_REPOSITORY"
   gh run watch "$RUN_ID" --repo "$GITHUB_REPOSITORY" --exit-status || true
   

3. Report the final status (cancelled/completed). If already finished, note that cancellation was skipped.

Trigger a Workflow (

/workflows-trigger

)

1. Require workflow file/ID plus ref/branch.
2. Compose inputs:

   EXTRA_INPUTS=${INPUTS_JSON:+--inputs "$INPUTS_JSON"}
   gh workflow run "$WORKFLOW" --repo "$GITHUB_REPOSITORY" --ref "${REF:-${BRANCH:-$DEFAULT_BRANCH}}" $EXTRA_INPUTS
   

3. Capture the run id from gh output and share it for monitoring.

Monitor a Run (

/workflows-monitor

)

1. Command:

   gh run watch "$RUN_ID" --repo "$GITHUB_REPOSITORY" --exit-status

   .
2. Stream output back. At completion, annotate whether the run concluded with success, failure, or cancellation.

Safety Checks

• Never cancel or rerun workflows outside the configured repo.
• If a command fails due to missing repo/ref, prompt the user for the missing data before retrying.
• Treat manual dispatch inputs carefully—validate JSON before passing

  --inputs

  .