Ghq

What it does

When your agent uses it

• Referencing source code from any remote repository — even for a single file
• Include look at Xs source
• How does X implement Y
• Check the X repo

Example prompts

• “look at X”
• “how does X implement Y”
• “check the X repo”
• “/ghq”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

1. 1Check first — ghq list (or ghq list -e / for exact match). If it prints a path, the repo is already there; skip the clone.
2. 2Clone if missing — ghq get /. Add --shallow for one-off inspection of a specific commit's tree, or --partial blobless if the repo is huge…
3. 3Resolve the path — ghq list -p -e / returns the absolute path. Use this with Read/Grep/Glob, not cd.
4. 4Update only when needed — ghq get -u / to pull latest. Don't update reflexively; a stale clone is usually fine for "how does X work"…

What it can do on your machine

Read from SKILL.md and the folder at commit ce7dae8. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • gh
  • rg
  • git

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • github.com
  • raw.githubusercontent.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ghq loads about 1.2k tokens when it runs. Until then it costs about 171 tokens; SKILL.md has 528 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~171

When it runs · the whole SKILL.md, loaded when a task matches

~1.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from natsukium/dotfiles at commit ce7dae8, republished under its CC0-1.0 licence (© natsukium). 528 words, ~1,233 tokens.

name

ghq

description

Clone and reuse GitHub/GitLab repositories under a single managed root (`ghq root`) instead of fetching files one-by-one via `gh api`/`WebFetch` or scratch-cloning into `/tmp`. Use this skill whenever investigating, reading, grepping, or referencing source code from any remote repository — even for a single file. Triggers include "look at X's source", "how does X implement Y", "check the X repo", "find Z in nixpkgs/react/linux/etc.", or any moment a remote repo URL appears and you need to read more than one file from it. Skip only for one-shot GitHub API operations that have no source code in them (PR comments, issue bodies, workflow runs — those belong to the `gh` skill).

<examples>
  <example type="bad">
    <description>Fetching files individually via the GitHub API</description>
    <bad>gh api repos/NixOS/nixpkgs/contents/pkgs/development/interpreters/python/default.nix</bad>
    <good>ghq get NixOS/nixpkgs && Read $(ghq list -p -e NixOS/nixpkgs)/pkgs/development/interpreters/python/default.nix</good>
  </example>
  <example type="bad">
    <description>Cloning into /tmp for "just this session"</description>
    <bad>git clone --depth 1 https://github.com/facebook/react /tmp/react</bad>
    <good>ghq get --shallow facebook/react  # ends up at ~/src/private/github.com/facebook/react, reusable</good>
  </example>
  <example type="bad">
    <description>Using WebFetch on raw.githubusercontent.com to read source</description>
    <bad>WebFetch https://raw.githubusercontent.com/owner/repo/main/src/foo.ts</bad>
    <good>ghq get owner/repo && Read $(ghq list -p -e owner/repo)/src/foo.ts</good>
  </example>
</examples>

<examples>
  <example>
    <user>Check how nixpkgs handles uv2nix</user>
    <agent>I'll make sure nixpkgs is cloned, then grep it locally.
`ghq get NixOS/nixpkgs` (no-op if present)
`rg -l uv2nix $(ghq list -p -e NixOS/nixpkgs)/pkgs`</agent>
  </example>
  <example>
    <user>Look at how React implements useEffect</user>
    <agent>I'll fetch React once and search the source tree.
`ghq get facebook/react`
Then `Grep` for `function useEffect` inside `$(ghq list -p -e facebook/react)`.</agent>
  </example>
  <example>
    <user>I want to see the changes in https://github.com/owner/repo/pull/42</user>
    <agent>That's a PR review, not source-code reading — using `gh` instead: `gh pr diff 42 --repo owner/repo`. (If I then need to explore the surrounding code, I'll `ghq get owner/repo`.)</agent>
  </example>
  <example>
    <user>The linux kernel has a function called vmalloc, can you find where it's defined?</user>
    <agent>Huge repo — partial clone keeps it tractable.
`ghq get --partial blobless torvalds/linux`
`rg -n 'void \*vmalloc\(' $(ghq list -p -e torvalds/linux)`</agent>
  </example>
</examples>

© natsukium, CC0-1.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in modules/features/coding-agents/common/skills/ghq of natsukium/dotfiles.

Open the folder on GitHubat commit ce7dae8