github-navigator

One pattern for everything:

1. Verify gh CLI is installed and authenticated (first use only)
2. Identify command domain (files, issues, PRs, releases, etc.)
3. Discover usage via gh --help or gh api --help
4. Apply pattern to user's specific request
5. Execute with max 2 attempts, then STOP

ALWAYS use this skill when:

• User provides a GitHub URL (any github.com/ link)
• User asks about GitHub repositories, issues, PRs, releases
• User mentions repo paths like "facebook/react"
• User wants GitHub information or operations

Common triggers:

• "Show me the README from facebook/react"
• "List open issues in vercel/next.js"
• "What's in the packages/ directory?"
• "Check latest release for react"
• "View PR #123 in cli/cli"

When user wants to understand a codebase deeply (not just fetch a single file), clone the repository locally for comprehensive analysis.

Trigger phrases:

• "analyze this repo"
• "understand the architecture"
• "how is X structured"
• "explore the codebase"
• "give me an overview of"
• "what patterns does X use"
• "how does this project work"

Workflow:

1. Clone to /tmp/github-navigator/-/

```bash

git clone --depth 1 https://github.com/OWNER/REPO.git /tmp/github-navigator/OWNER-REPO

```

1. Analyze the codebase:

- Tech stack detection: Look for package.json, go.mod, Cargo.toml, pom.xml, requirements.txt, etc.

- Directory structure: Map out the main directories and their purposes

- Entry points: Find main files, index files, app entry points

- Patterns: Identify architectural patterns (MVC, microservices, monorepo, etc.)

- Key files: README, CONTRIBUTING, docs/, examples/

1. Provide comprehensive summary with:

- Tech stack overview

- Project structure explanation

- Key files and their purposes

- Architectural patterns observed

1. Keep cloned for follow-up questions (user can explore further)

Cleanup:

Repos in /tmp/github-navigator/ are cleaned on system restart. For manual cleanup:

```bash

rm -rf /tmp/github-navigator/

```

Note: Use --depth 1 for faster cloning when full history isn't needed. Use full clone if user needs git history analysis.

Step 0: Verify gh CLI (First Use Only)

Before first use, verify gh CLI is installed and authenticated:

```bash

gh --version # Check if gh is installed

gh auth status # Check authentication status

```

If not installed, see [Installation](#installation).

If not authenticated, run gh auth login for private repos and write operations.

Step 1: Identify Command Domain

| User Request | Command Domain | Primary Command |

|--------------|----------------|-----------------|

| Fetch file content | Files | gh api repos/OWNER/REPO/contents/PATH |

| List directory | Files | gh api repos/OWNER/REPO/contents/PATH |

| Issues (list, view, create, close) | Issues | gh issue |

| Pull Requests (list, view, diff, merge) | PRs | gh pr |

| Releases (list, view, create) | Releases | gh release |

| Actions/Workflows (runs, logs) | Actions | gh run or gh workflow |

| Repository info (clone, view, fork) | Repo | gh repo |

Step 2: Discover Usage

For files/directories (use gh api):

```bash

gh api --help

```

For everything else (use gh subcommands):

```bash

gh issue --help # Shows all issue subcommands

gh issue list --help # Shows specific flags

gh pr --help # Shows all PR subcommands

gh release --help # Shows release operations

```

Step 3: Apply Pattern

Extract usage from help, substitute user's values, execute.

Step 4: Execute with Guardrails

• Max 2 attempts per command pattern
• If fails twice: STOP and report error to user
• Never loop endlessly trying variations

Use gh api for all file operations.

Fetch File Content

```bash

# Raw content (preferred for text files)

gh api repos/OWNER/REPO/contents/PATH -H "Accept: application/vnd.github.raw"

# Examples

gh api repos/facebook/react/contents/README.md -H "Accept: application/vnd.github.raw"

gh api repos/vercel/next.js/contents/package.json -H "Accept: application/vnd.github.raw"

# Specific branch/ref

gh api repos/OWNER/REPO/contents/PATH?ref=BRANCH -H "Accept: application/vnd.github.raw"

# Example

gh api repos/facebook/react/contents/package.json?ref=main -H "Accept: application/vnd.github.raw"

```

Note: If your shell interprets special characters in the URL path (like ?), quote the path appropriately for your environment.

List Directory Contents

```bash

# Get directory listing (returns JSON array)

gh api repos/OWNER/REPO/contents/PATH

# Format nicely with jq

gh api repos/OWNER/REPO/contents/PATH | jq -r '.[] | "\(.type): \(.name)"'

# Show directories and files separately

gh api repos/vercel/next.js/contents/packages | \

jq -r 'group_by(.type) | map({type: .[0].type, items: map(.name)}) | .[]'

# Simple list of names

gh api repos/OWNER/REPO/contents/PATH | jq -r '.[].name'

# Repository root

gh api repos/OWNER/REPO/contents

```

Get Default Branch

```bash

gh api repos/OWNER/REPO --jq .default_branch

```

Use gh issue subcommands.

List Issues

```bash

# Basic list

gh issue list --repo OWNER/REPO

# Filter by state

gh issue list --repo OWNER/REPO --state open

gh issue list --repo OWNER/REPO --state closed

gh issue list --repo OWNER/REPO --state all

# Filter by label

gh issue list --repo OWNER/REPO --label bug

gh issue list --repo OWNER/REPO --label "good first issue"

# Limit results

gh issue list --repo OWNER/REPO --limit 10

# JSON output

gh issue list --repo OWNER/REPO --json number,title,state,author

```

View Issue

```bash

# View issue details

gh issue view NUMBER --repo OWNER/REPO

# View with comments

gh issue view NUMBER --repo OWNER/REPO --comments

# JSON output

gh issue view NUMBER --repo OWNER/REPO --json title,body,state,comments

```

Create Issue (Requires Confirmation)

```bash

# ⚠️ MUST confirm with user first

gh issue create --repo OWNER/REPO --title "Title" --body "Description"

```

Close Issue (Requires Confirmation)

```bash

# ⚠️ MUST confirm with user first

gh issue close NUMBER --repo OWNER/REPO

```

Use gh pr subcommands.

List PRs

```bash

# Basic list

gh pr list --repo OWNER/REPO

# Filter by state

gh pr list --repo OWNER/REPO --state open

gh pr list --repo OWNER/REPO --state closed

gh pr list --repo OWNER/REPO --state merged

# Filter by author

gh pr list --repo OWNER/REPO --author USERNAME

# JSON output

gh pr list --repo OWNER/REPO --json number,title,state,author

```

View PR

```bash

# View PR details

gh pr view NUMBER --repo OWNER/REPO

# View with comments

gh pr view NUMBER --repo OWNER/REPO --comments

# JSON output

gh pr view NUMBER --repo OWNER/REPO --json title,body,state,mergeable

```

View PR Diff

```bash

gh pr diff NUMBER --repo OWNER/REPO

# Specific files only

gh pr diff NUMBER --repo OWNER/REPO --patch

```

Check PR Status

```bash

# View CI/CD checks

gh pr checks NUMBER --repo OWNER/REPO

```

Merge PR (Requires Confirmation)

```bash

# ⚠️ MUST confirm with user first

gh pr merge NUMBER --repo OWNER/REPO

```

Use gh release subcommands.

List Releases

```bash

# List all releases

gh release list --repo OWNER/REPO

# Limit results

gh release list --repo OWNER/REPO --limit 5

```

View Release

```bash

# View specific release

gh release view TAG --repo OWNER/REPO

# Latest release

gh release view --repo OWNER/REPO

```

Download Release Assets

```bash

# Download all assets from a release

gh release download TAG --repo OWNER/REPO

# Download specific pattern

gh release download TAG --repo OWNER/REPO --pattern "*.tar.gz"

```

Use gh run and gh workflow subcommands.

List Workflow Runs

```bash

# List recent runs

gh run list --repo OWNER/REPO

# Filter by workflow

gh run list --repo OWNER/REPO --workflow build.yml

# Limit results

gh run list --repo OWNER/REPO --limit 10

```

View Run Details

```bash

# View run info

gh run view RUN_ID --repo OWNER/REPO

# View logs

gh run view RUN_ID --repo OWNER/REPO --log

```

Use gh repo subcommands.

View Repository Info

```bash

# View repo details

gh repo view OWNER/REPO

# JSON output

gh repo view OWNER/REPO --json name,description,stargazersCount,forksCount

```

Clone Repository

```bash

# Clone repo

gh repo clone OWNER/REPO

# Clone to specific directory

gh repo clone OWNER/REPO target-directory

```

Fork Repository

```bash

# Fork repo to your account

gh repo fork OWNER/REPO

# Fork and clone

gh repo fork OWNER/REPO --clone

```

Failure Limits

Maximum 2 attempts per command pattern, then STOP.

1. Attempt 1: Run the command as discovered from help
2. If fails: Check error message, adjust ONCE
3. Attempt 2: Run corrected command
4. If fails again: STOP - Report error to user

Destructive Operations

Always confirm before executing:

• Delete or archive operations (gh repo delete, gh repo archive)
• State changes (gh pr merge, gh issue close)
• Creating resources (gh issue create, gh pr create)
• Security operations (gh secret set, gh workflow run)
• Force flags (--force, --yes, -y)

Confirmation pattern:

```

⚠️ This will [ACTION] in [REPO].

Command: [command]

Confirm you want to proceed?

```

Most operations work unauthenticated for public repos. Private repos and write operations require auth.

Check Auth Status

```bash

gh auth status

```

Authenticate

```bash

gh auth login

```

Refresh with Additional Scopes

```bash

# If you get "Resource not accessible" errors

gh auth refresh -s repo -s workflow -s read:org

```

Common Errors and Solutions

| Error | Cause | Solution |

|-------|-------|----------|

| gh: command not found | gh CLI not installed | Install: brew install gh (macOS) |

| HTTP 401: Unauthorized | Not authenticated | Run: gh auth login |

| HTTP 404: Not Found | Repo doesn't exist or private | Check name, or authenticate |

| unknown flag: --xyz | Wrong flag syntax | Check: gh --help |

| Resource not accessible | Insufficient permissions | Run: gh auth refresh -s repo |

| API rate limit exceeded | Too many requests | Authenticate for 5000/hr limit |

Debugging Strategy

When command fails: Read error → check gh --help → try once more → report to user if still fails.

DO NOT try multiple blind variations.

For operations not covered by gh subcommands, use gh api directly:

```bash

gh api repos/OWNER/REPO # Get repo info

gh api repos/OWNER/REPO/commits # List commits

gh api repos/OWNER/REPO/issues/NUMBER --jq '.title,.state'

```

Prefer standard commands when available - simpler and more reliable.

See [REFERENCES.md](REFERENCES.md) for GraphQL examples.

Install: brew install gh (macOS) or see [REFERENCES.md](REFERENCES.md). Then: gh auth login

---

> License: MIT | See also: [REFERENCES.md](REFERENCES.md)