github

Access GitHub repositories via the GitHub REST API. Use this skill when the user wants to interact with GitHub including reading files, creating/updating files, listing repos, managing branches, viewing commits, working with issues, or managing pull requests. All scripts use PEP 723 inline metadata for dependencies and run via `uv run`. Requires GITHUB_TOKEN environment variable (a Personal Access Token with appropriate scopes).

16 stars

bydiegosouzapw

View on GitHub Installation ↓

Best use case

github is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using github should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/github/SKILL.md --create-dirs "https://raw.githubusercontent.com/diegosouzapw/awesome-omni-skill/main/skills/cli-automation/github/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/github/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How github Compares

Feature / Agent	github	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Skill Overview

This skill provides access to GitHub repositories via a set of Python scripts that wrap the GitHub REST API.

## Prerequisites

**Tool Dependency**:
- `uv` - The scripts in this skill require the [uv](https://docs.astral.sh/uv/) package manager/runner. Most cloud-based AI agents have `uv` pre-installed (or they can install it). Local agents should install it via `curl -LsSf https://astral.sh/uv/install.sh | sh` or see the [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).

**Environment Variables** (must be set before running any script):
- `GITHUB_TOKEN` - A GitHub Personal Access Token (classic or fine-grained) with appropriate scopes

**Recommended Token Scopes** (for classic PAT):
- `repo` - Full control of private repositories (or `public_repo` for public only)
- `read:org` - Read organization membership (optional, for org repos)

**Important**: Use a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) when possible for better security. Configure only the repositories and permissions you need.

## Network Access

**Important**: The scripts in this skill require network access to the following domain:

- `api.github.com`

If you (the AI agent) have network restrictions, the user may need to whitelist this domain in the agent's settings for this skill to function.

## Common Code Used by All Scripts

This skill uses a shared common module (`github_common.py`) to centralize authentication, token management, HTTP header construction, repository string parsing, error handling, and retry logic with exponential backoff.

All scripts import from `github_common.py`, which makes maintenance easier and ensures consistent behavior across all operations.

## API Versioning

This skill uses explicit GitHub API versioning for long-term stability:
- API Version: `2022-11-28`
- Header: `X-GitHub-Api-Version: 2022-11-28`

This ensures consistent behavior even if GitHub releases new API versions with breaking changes.

## Available Scripts

All scripts include PEP 723 inline metadata declaring their dependencies. Just run with `uv run` — no manual dependency installation needed.

---

## Repository Operations

### List Repositories (`scripts/repo_list.py`)

```bash
uv run scripts/repo_list.py                          # List your repos
uv run scripts/repo_list.py --user octocat           # List user's repos
uv run scripts/repo_list.py --org github             # List org's repos
uv run scripts/repo_list.py --type public --sort updated --json
```

| Argument | Description |
|----------|-------------|
| `--user` | List repos for this user |
| `--org` | List repos for this organization |
| `--type` | Filter: all, public, private, forks, sources, member |
| `--sort` | Sort by: created, updated, pushed, full_name |
| `--per-page` | Results per page (max 100, default: 30) |
| `--page` | Page number (default: 1) |
| `--json`, `-j` | Output as JSON |

---

### Get Repository Contents (`scripts/repo_contents.py`)

```bash
uv run scripts/repo_contents.py owner/repo                    # Root listing
uv run scripts/repo_contents.py owner/repo --path README.md   # Get file
uv run scripts/repo_contents.py owner/repo --path src/        # List directory
uv run scripts/repo_contents.py owner/repo --path config.json --ref develop --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--path`, `-p` | Path to file or directory (default: root) |
| `--ref`, `-r` | Git ref (branch, tag, or commit SHA) |
| `--json`, `-j` | Output as JSON with full metadata |

---

### Get Repository Tree (`scripts/repo_tree.py`)

```bash
uv run scripts/repo_tree.py owner/repo               # Full tree
uv run scripts/repo_tree.py owner/repo --ref develop # Specific branch
uv run scripts/repo_tree.py owner/repo --path src/   # Filter by path
uv run scripts/repo_tree.py owner/repo --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--ref`, `-r` | Git ref (branch, tag, or commit SHA) |
| `--path`, `-p` | Filter to paths starting with this prefix |
| `--json`, `-j` | Output as JSON |

---

## File Operations

### Create or Update File (`scripts/file_write.py`)

```bash
# Create new file
uv run scripts/file_write.py owner/repo \
    --path docs/README.md \
    --content "# Documentation" \
    --message "Add docs"

# Update existing file (SHA required)
uv run scripts/file_write.py owner/repo \
    --path README.md \
    --content "# Updated" \
    --message "Update README" \
    --sha abc123...

# From local file
uv run scripts/file_write.py owner/repo \
    --path remote/script.py \
    --from-file local/script.py \
    --message "Upload script"

# Create an executable script (with --mode)
uv run scripts/file_write.py owner/repo \
    --path scripts/build.sh \
    --from-file build.sh \
    --message "Add build script" \
    --mode 755
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--path`, `-p` | Path for the file in the repo (required) |
| `--content`, `-c` | File content as string |
| `--from-file`, `-f` | Read content from this local file |
| `--message`, `-m` | Commit message (required) |
| `--sha` | SHA of file being replaced (required for updates) |
| `--branch`, `-b` | Branch to commit to |
| `--mode` | File mode (e.g., 755 for executable). Creates a second commit to set mode. |
| `--json`, `-j` | Output as JSON |

**Note on `--mode`:** The GitHub Contents API doesn't support setting file modes directly. When `--mode` is specified, the script first creates/updates the file, then makes a second commit to set the mode using the Git Data API. Common modes: `755` (executable), `644` (regular file).

---

### Change File Mode (`scripts/file_chmod.py`)

Change file permissions (mode) for existing files. Useful for making scripts executable or reverting to regular file mode.

```bash
# Make a single file executable
uv run scripts/file_chmod.py owner/repo --path script.py --mode 755

# Make multiple files executable in one commit
uv run scripts/file_chmod.py owner/repo \
    --path scripts/build.sh \
    --path scripts/deploy.sh \
    --path scripts/test.py \
    --mode 755

# Remove executable bit
uv run scripts/file_chmod.py owner/repo --path script.py --mode 644

# On a specific branch with custom message
uv run scripts/file_chmod.py owner/repo \
    --path scripts/run.py \
    --mode 755 \
    --branch develop \
    --message "Make run.py executable"
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--path`, `-p` | Path to file (required, can be repeated for multiple files) |
| `--mode`, `-m` | Target mode (required, e.g., 755 or 644) |
| `--branch`, `-b` | Branch to commit to (default: main) |
| `--message` | Commit message (auto-generated if not provided) |
| `--json`, `-j` | Output as JSON |

**Common modes:**
- `755` - Executable file (rwxr-xr-x)
- `644` - Regular file (rw-r--r--)

**How it works:** This script uses the Git Data API to modify file modes, which requires creating a new tree object and commit. Multiple files can be changed in a single commit for efficiency. Files that already have the target mode are skipped with a warning.

---

### Delete File (`scripts/file_delete.py`)

```bash
uv run scripts/file_delete.py owner/repo \
    --path docs/old.md \
    --sha abc123... \
    --message "Remove old doc"
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--path`, `-p` | Path to the file to delete (required) |
| `--sha` | SHA of the file to delete (required) |
| `--message`, `-m` | Commit message (required) |
| `--branch`, `-b` | Branch to delete from |
| `--json`, `-j` | Output as JSON |

---

## Branch Operations

### List Branches (`scripts/branch_list.py`)

```bash
uv run scripts/branch_list.py owner/repo
uv run scripts/branch_list.py owner/repo --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--per-page` | Results per page (max 100, default: 30) |
| `--page` | Page number (default: 1) |
| `--json`, `-j` | Output as JSON |

---

### Create Branch (`scripts/branch_create.py`)

```bash
uv run scripts/branch_create.py owner/repo --name feature/new-feature
uv run scripts/branch_create.py owner/repo --name hotfix/123 --from develop
uv run scripts/branch_create.py owner/repo --name release/v1.0 --from abc123...
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--name`, `-n` | Name for the new branch (required) |
| `--from`, `-f` | Source branch or commit SHA |
| `--json`, `-j` | Output as JSON |

---

### Delete Branch (`scripts/branch_delete.py`)

```bash
uv run scripts/branch_delete.py owner/repo --name feature/old-branch
uv run scripts/branch_delete.py owner/repo --name merged-branch --force
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--name`, `-n` | Branch name to delete (required) |
| `--force`, `-f` | Skip confirmation prompt |
| `--json`, `-j` | Output as JSON |

---

## Commit Operations

### List Commits (`scripts/commit_list.py`)

```bash
uv run scripts/commit_list.py owner/repo
uv run scripts/commit_list.py owner/repo --branch develop
uv run scripts/commit_list.py owner/repo --path src/main.py
uv run scripts/commit_list.py owner/repo --author octocat
uv run scripts/commit_list.py owner/repo --since 2024-01-01 --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--branch`, `-b` | Branch name |
| `--path`, `-p` | Filter to commits affecting this path |
| `--author`, `-a` | Filter by author username or email |
| `--since` | Only commits after this date (ISO 8601) |
| `--until` | Only commits before this date (ISO 8601) |
| `--per-page` | Results per page (max 100, default: 30) |
| `--page` | Page number (default: 1) |
| `--json`, `-j` | Output as JSON |

---

### Get Commit Details (`scripts/commit_get.py`)

```bash
uv run scripts/commit_get.py owner/repo abc123def456
uv run scripts/commit_get.py owner/repo abc123def456 --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `sha` | Commit SHA (required) |
| `--json`, `-j` | Output as JSON |

---

## Issue Operations

### List Issues (`scripts/issue_list.py`)

```bash
uv run scripts/issue_list.py owner/repo
uv run scripts/issue_list.py owner/repo --state all
uv run scripts/issue_list.py owner/repo --labels "bug,urgent"
uv run scripts/issue_list.py owner/repo --assignee octocat --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--state` | Filter: open, closed, all (default: open) |
| `--labels` | Comma-separated list of label names |
| `--assignee` | Filter by assignee username |
| `--sort` | Sort by: created, updated, comments |
| `--direction` | Sort direction: asc, desc |
| `--per-page` | Results per page (max 100) |
| `--page` | Page number |
| `--json`, `-j` | Output as JSON |

---

### Create Issue (`scripts/issue_create.py`)

```bash
uv run scripts/issue_create.py owner/repo --title "Bug report" --body "Description..."
uv run scripts/issue_create.py owner/repo --title "Feature" --labels "enhancement"
uv run scripts/issue_create.py owner/repo --title "Task" --assignees "user1,user2"
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--title`, `-t` | Issue title (required) |
| `--body`, `-b` | Issue body/description |
| `--labels` | Comma-separated list of label names |
| `--assignees` | Comma-separated list of usernames |
| `--milestone` | Milestone number |
| `--json`, `-j` | Output as JSON |

---

### Update Issue (`scripts/issue_update.py`)

```bash
uv run scripts/issue_update.py owner/repo 123 --title "New title"
uv run scripts/issue_update.py owner/repo 123 --state closed
uv run scripts/issue_update.py owner/repo 123 --state closed --reason not_planned
uv run scripts/issue_update.py owner/repo 123 --labels "bug,urgent"
uv run scripts/issue_update.py owner/repo 123 --assignees "user1,user2"
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `issue_number` | Issue number to update (required) |
| `--title`, `-t` | New title |
| `--body`, `-b` | New body/description |
| `--state`, `-s` | New state: open, closed |
| `--reason` | Close reason: completed, not_planned |
| `--labels` | Comma-separated labels (replaces existing) |
| `--assignees` | Comma-separated usernames (replaces existing) |
| `--milestone` | Milestone number (0 to clear) |
| `--json`, `-j` | Output as JSON |

---

## Pull Request Operations

### List Pull Requests (`scripts/pr_list.py`)

```bash
uv run scripts/pr_list.py owner/repo
uv run scripts/pr_list.py owner/repo --state all
uv run scripts/pr_list.py owner/repo --base main
uv run scripts/pr_list.py owner/repo --sort updated --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--state` | Filter: open, closed, all (default: open) |
| `--base` | Filter by base branch |
| `--head` | Filter by head branch |
| `--sort` | Sort by: created, updated, popularity, long-running |
| `--direction` | Sort direction: asc, desc |
| `--per-page` | Results per page (max 100) |
| `--page` | Page number |
| `--json`, `-j` | Output as JSON |

---

### Create Pull Request (`scripts/pr_create.py`)

```bash
uv run scripts/pr_create.py owner/repo --title "Add feature" --head feature-branch
uv run scripts/pr_create.py owner/repo --title "Fix bug" --head fix-123 --base develop
uv run scripts/pr_create.py owner/repo --title "WIP" --head wip-branch --draft
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `--title`, `-t` | PR title (required) |
| `--head`, `-h` | Branch containing changes (required) |
| `--base`, `-b` | Branch to merge into (default: default branch) |
| `--body` | PR description |
| `--draft`, `-d` | Create as draft PR |
| `--json`, `-j` | Output as JSON |

---

### Get Pull Request Details (`scripts/pr_get.py`)

```bash
uv run scripts/pr_get.py owner/repo 123
uv run scripts/pr_get.py owner/repo 123 --json
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `pr_number` | Pull request number (required) |
| `--json`, `-j` | Output as JSON |

---

### Merge Pull Request (`scripts/pr_merge.py`)

```bash
uv run scripts/pr_merge.py owner/repo 123
uv run scripts/pr_merge.py owner/repo 123 --method squash
uv run scripts/pr_merge.py owner/repo 123 --method rebase
uv run scripts/pr_merge.py owner/repo 123 --method squash --title "Feature (#123)"
```

| Argument | Description |
|----------|-------------|
| `repo` | Repository in owner/repo format (required) |
| `pr_number` | Pull request number (required) |
| `--method`, `-m` | Merge method: merge, squash, rebase |
| `--title`, `-t` | Custom commit title |
| `--message` | Custom commit message body |
| `--sha` | Expected head SHA (for safety) |
| `--json`, `-j` | Output as JSON |

---

## Common Patterns

### Setting Credentials

```bash
# Set for current session
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# Or inline with command
GITHUB_TOKEN="ghp_xxx" uv run scripts/repo_list.py
```

### Updating a File (Full Workflow)

To update a file, you need its current SHA:

```bash
# 1. Get the current file with its SHA
uv run scripts/repo_contents.py owner/repo --path README.md --json > file_info.json

# 2. Extract the SHA
SHA=$(jq -r '.sha' file_info.json)

# 3. Update the file with the SHA
uv run scripts/file_write.py owner/repo \
    --path README.md \
    --content "New content here" \
    --message "Update README" \
    --sha "$SHA"
```

### Creating and Merging a PR (Full Workflow)

```bash
# 1. Create a branch
uv run scripts/branch_create.py owner/repo --name feature/my-feature

# 2. Make changes (push commits via git or file_write.py)
uv run scripts/file_write.py owner/repo \
    --path feature.py \
    --content "# New feature" \
    --message "Add feature" \
    --branch feature/my-feature

# 3. Create a PR
uv run scripts/pr_create.py owner/repo \
    --title "Add my feature" \
    --head feature/my-feature \
    --body "This PR adds..."

# 4. Merge the PR
uv run scripts/pr_merge.py owner/repo 123 --method squash

# 5. Delete the branch
uv run scripts/branch_delete.py owner/repo --name feature/my-feature --force
```

### JSON Output for Processing

All scripts support `--json` for machine-readable output:

```bash
# List repos and filter with jq
uv run scripts/repo_list.py --json | jq '.[] | select(.language == "Python")'

# Get commit count
uv run scripts/commit_list.py owner/repo --json | jq 'length'

# Get all open PR numbers
uv run scripts/pr_list.py owner/repo --json | jq '.[].number'
```

## Error Handling

Scripts exit with non-zero status on errors. Common issues:

- **401 Unauthorized**: Check that `GITHUB_TOKEN` is set and valid
- **403 Forbidden**: Token lacks required scopes, or rate limit exceeded
- **404 Not Found**: Repository, file, or branch doesn't exist (or token lacks access)
- **409 Conflict**: SHA mismatch when updating (file was modified since you read it)
- **422 Validation Failed**: Invalid input (check branch name format, file path, etc.)

## Rate Limits

The GitHub API has rate limits:
- Authenticated requests: 5,000 per hour
- Search API: 30 per minute

The skill includes automatic retry logic with exponential backoff for rate limit errors.

Check your current limits as follows:

```bash
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit
```

Related Skills

python-github-actions

from diegosouzapw/awesome-omni-skill

Complete Python GitHub Actions system. PROACTIVELY activate for: (1) uv-based CI workflows (10-100x faster), (2) Matrix testing across Python versions, (3) Dependency caching with setup-uv, (4) Parallel test execution, (5) Reusable workflows, (6) Publishing to PyPI with trusted publishing, (7) Code coverage with codecov, (8) Security scanning. Provides: Workflow templates, caching config, matrix strategies, composite actions. Ensures fast, reliable CI/CD pipelines.

phoenix-github

from diegosouzapw/awesome-omni-skill

Manage GitHub issues, labels, and project boards for the Arize-ai/phoenix repository. Use when filing roadmap issues, triaging bugs, applying labels, managing the Phoenix roadmap project board, or querying issue/project state via the GitHub CLI.

github-workflow-automation

from diegosouzapw/awesome-omni-skill

Advanced GitHub Actions workflow automation with AI swarm coordination, intelligent CI/CD pipelines, and comprehensive repository management

github-search

from diegosouzapw/awesome-omni-skill

Search GitHub for repos, code, and usage examples using gh CLI. Capabilities: repo discovery, code search, finding library usage patterns, issue/PR search. Actions: search, find, discover repos/code/examples. Keywords: gh, github, search repos, search code, find examples, how to use library, stars, language filter. Use when: finding repositories, searching code patterns, discovering how libraries are used, exploring open source.

github-release-management

from diegosouzapw/awesome-omni-skill

Comprehensive GitHub release orchestration with AI swarm coordination for automated versioning, testing, deployment, and rollback management

github-ops

from diegosouzapw/awesome-omni-skill

Workflow for repository reconnaissance and operations using GitHub CLI (gh). Optimizes token usage by using structured API queries instead of blind file fetching.

github-multi-repo

from diegosouzapw/awesome-omni-skill

Multi-repository coordination, synchronization, and architecture management with AI swarm orchestration

github-issues

from diegosouzapw/awesome-omni-skill

Create, manage, triage, and close GitHub issues. Search existing issues, add labels, assign people, and link to PRs. Works with gh CLI or falls back to git + GitHub REST API via curl.

github-issue

from diegosouzapw/awesome-omni-skill

Work on a GitHub issue end-to-end: checkout main, create branch, research best practices, plan implementation, write tests first (TDD), implement, run code review, QA validation, then create PR. Use when given a GitHub issue URL or number to implement.

github-issue-creator

from diegosouzapw/awesome-omni-skill

Convert raw notes, error logs, voice dictation, or screenshots into crisp GitHub-flavored markdown issue reports. Use when the user pastes bug info, error messages, or informal descriptions and wan...

github-expert

from diegosouzapw/awesome-omni-skill

Complete GitHub expertise covering GitHub Actions, CI/CD workflows, automation, repository management, and best practices. Use when setting up GitHub Actions, creating workflows, managing pull requests, configuring automation (Dependabot, CodeQL), or implementing GitHub best practices. Includes workflow generators, templates, and production-ready configurations.

github-copilot-cli-expert

from diegosouzapw/awesome-omni-skill

Expert knowledge of GitHub Copilot CLI - installation, configuration, usage, custom agents, MCP servers, and version management. Use when asking about copilot cli, copilot commands, installing copilot, updating copilot, copilot features.