github-openapi-skill

name	github-openapi-skill
description	Operate GitHub REST API through UXC with the official OpenAPI schema, explicit gh-to-uxc auth import, and read-first guardrails for repo, issue, pull request, and event workflows.

GitHub REST API Skill

Use this skill to run GitHub REST API operations through uxc + OpenAPI.

Reuse the uxc skill for shared execution, auth, and error-handling guidance.

Prerequisites

• uxc is installed and available in PATH.
• gh is installed and already authenticated with gh auth login.
• Network access to https://api.github.com.
• Access to the official GitHub REST OpenAPI schema URL:
  • https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

Authentication

Preferred Path: Import local gh auth into uxc

Import the current GitHub CLI token into a local uxc bearer credential and create a standard GitHub API binding:

uxc auth credential import github --from gh

This creates:

• credential: github
• binding: github-api
• bound host: https://api.github.com

Verify the binding:

uxc auth binding match https://api.github.com/repos/holon-run/uxc

Optional Path: Manual bearer token

If gh is unavailable, configure a PAT manually:

uxc auth credential set github \
  --auth-type bearer \
  --secret-env GITHUB_TOKEN

uxc auth binding add \
  --id github-api \
  --host api.github.com \
  --path-prefix / \
  --scheme https \
  --credential github \
  --priority 100

Do not commit GitHub tokens or hardcode them in this skill or repository.

Core Workflow

1. Use fixed link command by default:

   • command -v github-openapi-cli
   • If missing, create it: uxc link github-openapi-cli https://api.github.com --schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
   • github-openapi-cli -h

2. Inspect operation schema first:

   • github-openapi-cli get:/user -h
   • github-openapi-cli get:/repos/{owner}/{repo} -h
   • github-openapi-cli get:/repos/{owner}/{repo}/issues -h

3. Execute reads before writes:

   • github-openapi-cli get:/user
   • github-openapi-cli get:/repos/{owner}/{repo} owner=holon-run repo=uxc
   • github-openapi-cli get:/repos/{owner}/{repo}/issues owner=holon-run repo=uxc state=open per_page=10
   • github-openapi-cli get:/repos/{owner}/{repo}/pulls owner=holon-run repo=uxc state=open per_page=10

4. Treat mutations as explicit-confirmation operations:

   • github-openapi-cli post:/repos/{owner}/{repo}/issues '{"owner":"holon-run","repo":"uxc","title":"Example issue"}'

Guardrails

• Keep automation on JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• github-openapi-cli <operation> ... is equivalent to uxc https://api.github.com --schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json <operation> ....
• Prefer read operations before write operations.
• Treat issue creation, issue edits, comments, labels, repo administration, releases, and workflow-trigger endpoints as write/high-risk operations; require explicit user confirmation before execution.

References

• Usage patterns: references/usage-patterns.md
• GitHub REST OpenAPI schema: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
• GitHub REST docs: https://docs.github.com/rest