github-cache-hygiene

---
name: github-cache-hygiene
description: "Use when working with gitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits from steipete/agent-scripts."
source: https://github.com/steipete/agent-scripts/tree/main/skills/github-cache-hygiene
generated: 2026-05-27T20:55:43.365Z
category: tool
audience: engineers
---

## When to use

- Using the github-cache-hygiene skill's upstream workflow, guardrails, and local-tool assumptions.
- Auditing commands or operational steps before changing github cache hygiene behavior.
- Needing a compact agent reference for gitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

## Key concepts

### Default Path

Use gh normally. On Peter's machines it is expected to be the gitcrawl-backed shim, so supported reads can be answered locally or cached without changing commands. Prefer these local/cached reads: Use exact refs and narrow fields. Avoid broad loops like one gh issue view per result when a single gh search or gh issue list --json... can answer the first-pass question. For CI, avoid tight gh run list / gh run view polling loops. After a push or workflow dispatch, identify one exact run, then...

### Freshness

Local answers are good for discovery, duplicate search, old thread review, author/label triage, and "is there likely already an issue/PR?" checks. Use a live call when: writing, commenting, closing, merging, rerunning, or editing checking final current state before a maintainer action verifying CI status after a push the local result is missing or obviously stale the user asks for latest/live state For PR review, prefer hydrating exact PR details once with gitcrawl sync owner/repo --numbers...

### XCache

Inspect cache behavior when rate limits are suspected: Read backendmissesbycommand and backendmissesbyroute in gh xcache stats --json before adding new live GitHub loops. Those maps show which command shapes are still escaping the cache. Use gh xcache flush only when a stale cached fallback read is misleading a decision. For local-only proof, temporarily make the backend unavailable for a single command:.

### Agent Etiquette

Batch questions by repo and state. Reuse data already printed in the session. Back off CI polling; inspect logs only for failing runs or the exact run under review. Do not bypass the shim with /opt/homebrew/opt/gh/bin/gh unless diagnosing the shim itself.

## API reference

```
npx skills add steipete/agent-scripts --skill github-cache-hygiene
```

Install the github-cache-hygiene skill from steipete/agent-scripts.

```
npx skills add steipete/agent-scripts --skill github-cache-hygiene
```

```
gitcrawl sync owner/repo --numbers 123 --with pr-details.
```

Command or snippet documented by the upstream github-cache-hygiene skill.

```
gitcrawl sync owner/repo --numbers 123 --with pr-details
gh search issues "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,labels,author
gh search prs "<terms>" -R owner/repo --state open --json number,title,state,url,updatedAt,isDraft,author
gh issue list -R owner/repo --state open --author user --assignee user --label bug --json number,title,url
gh pr list -R owner/repo --state open --author user --label dependencies --json number,title,url
gh issue view 123 -R owner/repo --json number,title,state,body,comments,labels,url
gh pr view 123 -R owner/repo --json number,title,state,body,comments,labels,files,commits,statusCheckRollup,url
gh pr checks 123 -R owner/repo --json name,state,detailsUrl,workflow
gh run list -R owner/repo --branch branch-name --json databaseId,workflowName,status,conclusion,url
gh pr diff 123 -R owner/repo --patch
```

```
gh xcache stats.
```

Command or snippet documented by the upstream github-cache-hygiene skill.

```
gh xcache stats
gh xcache keys
gh xcache gc
```

```
GITCRAWLGHPATH=/tmp/no-real-gh gh search issues "<terms>" -R owner/repo --json number,title,url.
```

Command or snippet documented by the upstream github-cache-hygiene skill.

```
GITCRAWL_GH_PATH=/tmp/no-real-gh gh search issues "<terms>" -R owner/repo --json number,title,url
```

## Gotchas

- Prefer these local/cached reads:.

---
Generated by SkillMake from https://github.com/steipete/agent-scripts/tree/main/skills/github-cache-hygiene on 2026-05-27T20:55:43.365Z.
Verify against source before relying on details.

File: ~/.claude/skills/github-cache-hygiene/SKILL.md