Get the FREE Ultimate OpenClaw Setup Guide →

github

npx machina-cli add skill IvanCampos/agents/github --openclaw
Files (1)
SKILL.md
3.5 KB

GitHub CLI

Overview

Use gh for day-to-day GitHub operations from the terminal. Prefer read-only commands first, then run mutating commands only after clear user intent.

Quick Start

  1. Check installation and auth:
gh --version
gh auth status
  1. Establish repository context:
scripts/gh_preflight.sh --repo owner/repo
  1. If not in the target repository, pass -R owner/repo to commands.
  2. Use --json with --jq or --template for automation-friendly output.

Workflow

  1. Establish context first.
  • Determine GitHub host (github.com by default), repository, and branch.
  • Run scripts/gh_preflight.sh before multi-step operations.
  1. Read current state.
  • Use list, view, and status subcommands before changing anything.
  1. Apply requested mutation.
  • For create/edit/merge/delete actions, restate the operation and require explicit confirmation unless the user already asked clearly.
  1. Report stable identifiers.
  • Return URLs and IDs for created or changed objects (PR number, issue number, run URL, release tag).

Common Commands

  • Repository:
    • gh repo view
    • gh repo clone owner/repo
    • gh repo create
    • gh repo set-default owner/repo
  • Pull requests:
    • gh pr list
    • gh pr view <number>
    • gh pr checkout <number>
    • gh pr create
    • gh pr review <number> --approve|--request-changes|--comment
    • gh pr merge <number>
  • Issues:
    • gh issue list
    • gh issue view <number>
    • gh issue create
    • gh issue comment <number> --body "..."
    • gh issue close <number>
  • Actions:
    • gh workflow list
    • gh workflow run <workflow>
    • gh run list
    • gh run watch <run-id>
    • gh run view <run-id> --log
  • Releases:
    • gh release list
    • gh release view <tag>
    • gh release create <tag> [assets...]
    • gh release upload <tag> <file>
  • API:
    • gh api repos/{owner}/{repo}/pulls --paginate

For broader command coverage, read references/command-map.md.

Safety Defaults

  • Confirm before commands that change remote state:
    • gh pr create|merge|close|reopen|ready
    • gh issue create|edit|close|reopen|delete
    • gh repo create|edit|archive|delete
    • gh release create|edit|delete
    • gh secret set|delete
    • gh variable set|delete
    • gh workflow run
  • Avoid destructive flags (--delete-branch, force flags) unless explicitly requested.
  • Show exact command before bulk updates and prefer smallest safe scope.

Structured Output

Use JSON output when parsing or summarizing results:

gh pr list --json number,title,url --jq '.[] | "\(.number)\t\(.title)\t\(.url)"'
gh issue list --json number,title,labels --template '{{range .}}{{printf "#%v %v\n" .number .title}}{{end}}'

Troubleshooting

  • Auth errors: gh auth login or gh auth refresh.
  • Wrong account/host: gh auth status --hostname github.com, then gh auth switch.
  • Unknown command options: gh <command> <subcommand> --help.
  • Manual reference: https://cli.github.com/manual/.

Resources

scripts/

  • scripts/gh_preflight.sh: Check gh availability, auth status, and repository context.

references/

  • references/command-map.md: Command map for repo, PR, issue, actions, release, and API operations.

Source

git clone https://github.com/IvanCampos/agents/blob/main/skills/github/SKILL.mdView on GitHub

Overview

Use gh for day-to-day GitHub operations from the terminal, including repositories, pull requests, issues, workflows, releases, and API calls. Start with read-only commands to understand state, then run mutating actions only when the user has clear intent.

How This Skill Works

The skill guides you through gh commands after establishing repository context (host, repo, and branch) with a preflight script (scripts/gh_preflight.sh). It encourages reading current state with view/list/status commands before mutating, and promotes automation-friendly output using --json, --jq, or templates to surface IDs and URLs for created or updated objects.

When to Use It

  • When asked to use the GitHub CLI (gh) for repo, PR, issue, workflow, or release tasks.
  • When you need to run GitHub Actions workflows or trigger runs from the shell.
  • When you want to automate data extraction with JSON output (--json) for scripting.
  • When troubleshooting gh authentication, host, or configuration issues.
  • When you need to establish repository context and safety checks before changes (read-only first).

Quick Start

  1. Step 1: Check installation and auth: gh --version; gh auth status.
  2. Step 2: Establish repository context: scripts/gh_preflight.sh --repo owner/repo.
  3. Step 3: If not in the target repository, pass -R owner/repo to commands.

Best Practices

  • Start with read-only commands (list/view/status) before mutating actions.
  • Always establish repository context first with the preflight script (scripts/gh_preflight.sh).
  • Confirm before commands that change remote state unless explicit user intent is clear.
  • Use --json with --jq or --template to produce automation-friendly output.
  • Return stable identifiers (URLs and object numbers) for created or changed items.

Example Use Cases

  • gh repo view; gh pr list; gh issue view <num> to survey a project.
  • gh pr create to open a PR, then gh pr review <num> --approve or --comment.
  • gh workflow list and gh workflow run <workflow> to trigger CI from shell.
  • gh release list; gh release view <tag>; gh release create <tag> [assets...] to publish a release.
  • gh api repos/{owner}/{repo}/pulls --paginate to fetch open pull requests programmatically.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗