github-navigator

Use gh for GitHub work. Prefer command discovery over memorizing flags.

This is an execution skill. Use gh instead of generic web fetching for GitHub tasks, inspect gh --help when syntax is uncertain, then execute with tight guardrails. Keep the main flow lean and load REFERENCES.md only when you need concrete examples, installation steps, or GraphQL details.

When to Use

Activate when:

• the user gives a github.com URL
• the user names a repo path like facebook/react or owner/repo
• the user asks about repository files, issues, PRs, releases, workflows, or metadata
• the user wants to understand the architecture or structure of a GitHub-hosted codebase

Core Rules

• Always prefer gh over WebFetch for GitHub content and operations.
• Use gh api for raw file content, directory listings, and API-only endpoints.
• Use gh subcommands (issue, pr, release, run, workflow, repo) when a dedicated command exists.
• Use gh <domain> --help before guessing flags or subcommands.
• Limit each command pattern to 2 attempts; if it still fails, stop and report the error.

Command Routing

| User Intent | Primary Command Path | |-------------|----------------------| | fetch file or list directory | gh api repos/OWNER/REPO/contents/... | | inspect issues | gh issue ... | | inspect pull requests | gh pr ... | | inspect releases | gh release ... | | inspect Actions runs or workflows | gh run ... or gh workflow ... | | inspect repo metadata or clone/fork | gh repo ... | | endpoints without a dedicated subcommand | gh api ... |

Use dedicated subcommands first. Fall back to gh api only when needed.

Execution Pattern

1. Identify the command domain from the request.
2. Check the relevant help output if the exact syntax is not already obvious.
3. Substitute the user's repo, path, issue number, PR number, or other arguments.
4. Run the command.
5. If it fails, adjust once based on the error message.
6. If it fails again, stop and report the error instead of trying blind variations.

Deep Analysis Mode

When the user wants to understand a codebase deeply, clone it locally for inspection instead of making many remote API calls.

Default flow:

1. Clone with depth 1 to /tmp/github-navigator/OWNER-REPO/

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

2. Inspect the repository for:

   • tech stack signals (package.json, go.mod, Cargo.toml, pom.xml, requirements.txt, etc.)
   • high-level directory structure
   • entry points and primary modules
   • README, docs, examples, and contribution files
   • architectural patterns worth calling out

3. Summarize the findings in plain language.

4. Keep the clone for follow-up questions unless cleanup is requested.

Use a full clone only if the user explicitly needs commit history or deeper git analysis.

Safety

Always confirm before executing state-changing or destructive commands, including:

• creating, closing, or reopening issues
• creating, merging, or closing pull requests
• deleting, archiving, or transferring repositories
• setting secrets or triggering workflows
• any use of --force, --yes, or similar bypass flags

Authentication and Recovery

• Check gh auth status when the task touches private repos or write operations.
• Use gh auth login if the client is not authenticated.
• If permissions are insufficient, use gh auth refresh -s repo -s workflow -s read:org as appropriate.
• If a command fails, read the error, check help, retry once, then stop.
• If gh is not installed, point the user to REFERENCES.md for installation guidance.

Reference Handoff

Use REFERENCES.md when you need:

• concrete example commands for common tasks
• install and auth setup details
• troubleshooting reminders
• GraphQL examples or other lower-frequency patterns

---

License: MIT See also: REFERENCES.md