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
- Identify the command domain from the request.
- Check the relevant help output if the exact syntax is not already obvious.
- Substitute the user's repo, path, issue number, PR number, or other arguments.
- Run the command.
- If it fails, adjust once based on the error message.
- 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:
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
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
Summarize the findings in plain language.
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
1---2name: github-navigator3description: GitHub operations via gh CLI. CRITICAL: Use instead of WebFetch for any `github.com` URL or GitHub repo path like `owner/repo`. Use when the user asks to inspect repositories, files, issues, pull requests, releases, Actions runs, or repository structure. Use when the user says 'show README', 'list issues', 'check PR', 'clone repo', or 'analyze this repo'.4---5
6# GitHub Navigator
7
8Use `gh` for GitHub work. Prefer command discovery over memorizing flags.
9
10This 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](REFERENCES.md) only when you need concrete examples, installation steps, or GraphQL details.
11
12## When to Use
13
14Activate when:
15
16- the user gives a `github.com` URL
17- the user names a repo path like `facebook/react` or `owner/repo`
18- the user asks about repository files, issues, PRs, releases, workflows, or metadata
19- the user wants to understand the architecture or structure of a GitHub-hosted codebase
20
21## Core Rules
22
23- Always prefer `gh` over `WebFetch` for GitHub content and operations.
24- Use `gh api` for raw file content, directory listings, and API-only endpoints.
25- Use `gh` subcommands (`issue`, `pr`, `release`, `run`, `workflow`, `repo`) when a dedicated command exists.
26- Use `gh <domain> --help` before guessing flags or subcommands.
27- Limit each command pattern to 2 attempts; if it still fails, stop and report the error.
28
29## Command Routing
30
31| User Intent | Primary Command Path |
32|-------------|----------------------|
33| fetch file or list directory | `gh api repos/OWNER/REPO/contents/...` |
34| inspect issues | `gh issue ...` |
35| inspect pull requests | `gh pr ...` |
36| inspect releases | `gh release ...` |
37| inspect Actions runs or workflows | `gh run ...` or `gh workflow ...` |
38| inspect repo metadata or clone/fork | `gh repo ...` |
39| endpoints without a dedicated subcommand | `gh api ...` |
40
41Use dedicated subcommands first. Fall back to `gh api` only when needed.
42
43## Execution Pattern
44
451. Identify the command domain from the request.
462. Check the relevant help output if the exact syntax is not already obvious.
473. Substitute the user's repo, path, issue number, PR number, or other arguments.
484. Run the command.
495. If it fails, adjust once based on the error message.
506. If it fails again, stop and report the error instead of trying blind variations.
51
52## Deep Analysis Mode
53
54When the user wants to understand a codebase deeply, clone it locally for inspection instead of making many remote API calls.
55
56Default flow:
57
581. Clone with depth 1 to `/tmp/github-navigator/OWNER-REPO/`
59
60 ```bash
61 git clone --depth 1 https://github.com/OWNER/REPO.git /tmp/github-navigator/OWNER-REPO
62 ```
63
642. Inspect the repository for:
65 - tech stack signals (`package.json`, `go.mod`, `Cargo.toml`, `pom.xml`, `requirements.txt`, etc.)
66 - high-level directory structure
67 - entry points and primary modules
68 - README, docs, examples, and contribution files
69 - architectural patterns worth calling out
70
713. Summarize the findings in plain language.
724. Keep the clone for follow-up questions unless cleanup is requested.
73
74Use a full clone only if the user explicitly needs commit history or deeper git analysis.
75
76## Safety
77
78Always confirm before executing state-changing or destructive commands, including:
79
80- creating, closing, or reopening issues
81- creating, merging, or closing pull requests
82- deleting, archiving, or transferring repositories
83- setting secrets or triggering workflows
84- any use of `--force`, `--yes`, or similar bypass flags
85
86## Authentication and Recovery
87
88- Check `gh auth status` when the task touches private repos or write operations.
89- Use `gh auth login` if the client is not authenticated.
90- If permissions are insufficient, use `gh auth refresh -s repo -s workflow -s read:org` as appropriate.
91- If a command fails, read the error, check help, retry once, then stop.
92- If `gh` is not installed, point the user to [REFERENCES.md](REFERENCES.md) for installation guidance.
93
94## Reference Handoff
95
96Use [REFERENCES.md](REFERENCES.md) when you need:
97
98- concrete example commands for common tasks
99- install and auth setup details
100- troubleshooting reminders
101- GraphQL examples or other lower-frequency patterns
102
103---
104
105> **License:** MIT
106> **See also:** [REFERENCES.md](REFERENCES.md)
majiayu000