Github Ops

GitHub Ops Skill

Provides structured guidance for repository reconnaissance using gh api and gh search.

Overview

Repository reconnaissance often fails when agents guess file paths or attempt to fetch large files blindly. This skill enforces a structured Map -> Identify -> Fetch sequence using the GitHub CLI to minimize token waste and improve reliability.

⚡ Essential Reconnaissance Commands

Use these commands to understand a repository structure before fetching content.

1. List Repository Root

gh api repos/{owner}/{repo}/contents --jq '.[].name'

2. List Specific Directory

gh api repos/{owner}/{repo}/contents/{path} --jq '.[].name'

3. Fetch File Content (Base64 Decoded)

gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d

4. Search for Pattern in Repository

gh search code "{pattern}" --repo {owner}/{repo}

5. Get Repository Metadata

gh repo view {owner}/{repo} --json description,stargazerCount,updatedAt

🔄 Token-Efficient Workflow

1. Map Tree: List the root and core directories (commands, src, docs). 2. Identify Entrypoints: Look for README.md, gemini-extension.json, package.json, or SKILL.md. 3. Targeted Fetch: Download only the entrypoints first. 4. Deep Dive: Use gh search code to find logic patterns rather than reading every file.

🛡️ Platform Safety (Windows)

• When using base64 -d, ensure the output is redirected to a file using the Write tool if it's large.
• Avoid Linux-style /dev/stdin patterns in complex pipes.
• Use native paths for any local storage.

Iron Laws

1. ALWAYS follow the Map → Identify → Fetch sequence before reading any file — blindly fetching files by guessed path wastes tokens, triggers 404s, and produces hallucinated repo structure. 2. NEVER fetch a file without first listing its parent directory or confirming it exists via gh api — large files fetched unnecessarily can exhaust the context window. 3. ALWAYS use --jq to filter gh api JSON output to only the fields needed — unfiltered API responses contain hundreds of irrelevant fields that inflate token usage. 4. NEVER use gh search code without a scoping qualifier (repo, org, or path) — unscoped code search returns results from all of GitHub, producing irrelevant noise. 5. ALWAYS prefer gh api structured queries over reading repository files directly when repository metadata is needed — API queries are faster, structured, and don't require authentication context for public repos.

Anti-Patterns

GitHub MCP Server Operations

When the official GitHub MCP server (@modelcontextprotocol/server-github) is configured, use these higher-level tools for repository management and automation:

// settings.json configuration
"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}

PR Automation Pattern

# Create PR with auto-generated description
gh pr create \
  --title "feat: add feature X" \
  --body "$(gh api repos/{owner}/{repo}/compare/{base}...{head} --jq '.commits[].commit.message' | head -5)" \
  --base main \
  --head feature/x

# Auto-merge after CI passes
gh pr merge --auto --squash --delete-branch

Issue Management

# List open issues by label
gh issue list --label "bug" --state open --json number,title,assignees

# Bulk-close resolved issues
gh issue list --label "stale" --json number --jq '.[].number' | \
  xargs -I{} gh issue close {} --comment "Closing as stale"

# Create issue from template
gh issue create \
  --title "Bug: [description]" \
  --body-file .github/ISSUE_TEMPLATE/bug_report.md \
  --label "bug,needs-triage"

Release Automation

# Create release with auto-generated notes
gh release create v1.2.0 \
  --generate-notes \
  --title "v1.2.0" \
  --target main

# Upload release assets
gh release upload v1.2.0 dist/*.tar.gz dist/*.zip

Workflow Management

# Trigger workflow manually
gh workflow run deploy.yml --field environment=production

# Watch workflow run
gh run watch $(gh run list --workflow=deploy.yml --limit=1 --json databaseId --jq '.[0].databaseId')

# Download workflow artifacts
gh run download --name=build-artifacts --dir=./artifacts

Assigned Agents

• artifact-integrator: Lead agent for repository onboarding.
• developer: PR management and exploration.

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

Invoke the github-ops skill and follow it exactly as presented to you

Research Requirements: github-ops

Research Details

• Date: 2026-02-17
• Query Intent: Identify best practices for repository reconnaissance and structured API usage via GitHub CLI (gh).
• Sources:
• GitHub REST API Documentation (Best Practices)
• GitHub CLI (gh) Manual
• GitHub Community Discussions

Exa Findings

• High-Confidence Keywords: gh api, jq filtering, code search, repository structure, pagination.
• Actionable Design Constraints:

1. Structured Reconnaissance: Use gh api repos/{owner}/{repo}/contents with --jq to list files before fetching content. 2. Token Efficiency: Filter JSON responses to return only necessary fields (e.g., name, type, path). 3. Automated Pagination: Use the --paginate flag for endpoints that return large lists (e.g., issues, PRs).

• Non-Goals:
• Do not implement complex local caching (assume session-level persistence).
• Do not provide exhaustive wrappers for all 100+ API endpoints; focus on reconnaissance.

Actionable Design Constraints

1. Tooling: Always prioritize gh api for reconnaissance over blind Read or WebFetch of raw files. 2. Workflow: Implement a Map -> Identify -> Fetch sequence. 3. Guardrails: Block Linux-specific path constructs (e.g., /dev/stdin) in Windows environments.

Operating Rules: github-ops

1. Reconnaissance-First: Always list directory contents via gh api before attempting to read specific files. 2. Filter Aggressively: Use the --jq flag to select only relevant metadata (name, type, size) to keep the context clean. 3. Placeholders: Use {owner}, {repo}, and {branch} placeholders in API endpoints; the CLI will automatically resolve them if in a git directory. 4. No Linux Paths: Never use /dev/stdin or Linux-style absolute paths in gh commands when on Windows. 5. Output Redirection: For large API responses, redirect output to a temporary file instead of outputting directly to the prompt. 6. Pagination: Always use --paginate for endpoints known to return large collections (e.g., repository contents with 50+ items).

Implementation Template: github-ops

Use this template when implementing repository reconnaissance workflows.

1. Map Root

// Step 1: List root files
Skill({
  skill: 'github-ops',
  args: ['api', 'repos/{owner}/{repo}/contents', '--jq', '.[].name'],
});

2. Locate Core Logic

// Step 2: Search for entrypoints
Skill({
  skill: 'github-ops',
  args: ['search', 'code', 'pattern', '--repo', '{owner}/{repo}'],
});

3. Ingest Entrypoints

// Step 3: Fetch file content
Skill({
  skill: 'github-ops',
  args: ['api', 'repos/{owner}/{repo}/contents/{path}', '--jq', '.content'],
});