Github repo researcher

GitHub Repo Researcher

Use this skill when you need to:

• Understand project structure and file organization
• Find where specific functionality is implemented
• Read source code for any file
• Search for code patterns or keywords

Bootstrap

Before running any other command:

If jq is not on $PATH, install it:

# Install using Homebrew (macOS/Linux)
brew install jq

# Alternatively using apt (Debian/Ubuntu)
sudo apt-get update && sudo apt-get install -y jq

# Alternatively using apk (Alpine)
sudo apk add jq

# Then verify installation
jq --version

If repomix is not on $PATH, install it:

# Install using npm
npm install -g repomix

# Alternatively using yarn
yarn global add repomix

# Alternatively using bun
bun add -g repomix

# Alternatively using Homebrew (macOS/Linux)
brew install repomix

# Then verify installation
repomix --version

Workflow

1. Understand the user's intent. Define the research goal and the main questions.
2. Download the repository context with repomix --remote <url> --style json --compress --output /tmp/<repo-name>-analysis.json.
3. Read the summary of /tmp/<repo-name>-analysis.json with jq -r '.fileSummary | to_entries | map("\(.key):\n\(.value)") | join("\n\n")' /tmp/<repo-name>-analysis.json.
4. Inspect the documentation and repository structure.

• Read the main documentation files.

jq -r '
  .files
  | to_entries[]
  | select(
      (.key | test("(^|/)README\\.md$"))
      or (.key | test("(^|/)CLAUDE\\.md$"))
      or (.key | test("(^|/)AGENTS\\.md$"))
      or (.key == "CONTRIBUTING.md")
      or (.key == "SECURITY.md")
    )
  | "===== " + .key + " =====\n" + .value + "\n"
' /tmp/<repo-name>-analysis.json

• Try to find additional documentation files.

jq -r '
  .files
  | keys[]
  | select(
      test("(^|/)(README|CONTRIBUTING|SECURITY|CHANGELOG|CLAUDE|AGENTS|FAQ|INSTALLATION|USAGE|GUIDE)(\\.[^/]+)?$"; "i")
      or test("(^|/)(docs|documentation)/"; "i")
    )
' /tmp/<repo-name>-analysis.json

• Read whichever documentation file is most relevant to the research goal and main questions.

jq -r '.files["<file-name>"]' /tmp/<repo-name>-analysis.json

• Read the first-level structure of the repository.

jq -r '.directoryStructure' /tmp/<repo-name>-analysis.json \
| awk '{
  match($0, /^ */)
  depth = RLENGTH / 2
  if (depth <= 1) print
}'

• List the file names in the relevant directory.

jq -r '
  .files
  | keys[]
  | select(startswith("<directory>/"))
' /tmp/<repo-name>-analysis.json

• Read the code file that is most relevant to the research goal and main questions.

jq -r '.files["<file-name>"]' /tmp/<repo-name>-analysis.json

• Prepare relevant queries and use jq to search across files. Run as many searches as necessary to fully address the research goal and answer the core questions with confidence.

Note: jq uses the Oniguruma regular expression library.

By regular expression:

jq -r '
  .files
  | to_entries[]
  | select(.value | test("repomix|mcp|compression"; "i"))
  | .key
' /tmp/<repo-name>-analysis.json

By substring:

jq -r '
  .files
  | to_entries[]
  | select(.value | contains("repomix"))
  | .key
' /tmp/<repo-name>-analysis.json

By whole word:

jq -r '
  .files
  | to_entries[]
  | select(.value | test("\\brepomix\\b"; "i"))
  | .key
' /tmp/<repo-name>-analysis.json

5. Prepare a comprehensive, well-grounded response for the user. It should stay closely aligned with the research objective, answer the core questions in depth, and be backed by concrete evidence from the repository. Be rigorous in your analysis: do not speculate, do not gloss over uncertainty, and make sure every claim is traceable to repository facts.

Command Examples

1. repomix --remote https://github.com/yamadashy/repomix/tree/main --style json --compress --output /tmp/repomix-analysis.json
2. jq -r '.fileSummary | to_entries | map("\(.key):\n\(.value)") | join("\n\n")' /tmp/repomix-analysis.json
3. jq -r '.files | to_entries[] | select((.key | test("(^|/)README\\.md$")) or (.key | test("(^|/)CLAUDE\\.md$")) or (.key | test("(^|/)AGENTS\\.md$")) or (.key == "CONTRIBUTING.md") or (.key == "SECURITY.md")) | "===== " + .key + " =====\n" + .value + "\n"' /tmp/repomix-analysis.json
4. jq -r '.files | keys[] | select(test("(^|/)(README|CONTRIBUTING|SECURITY|CHANGELOG|CLAUDE|AGENTS|FAQ|INSTALLATION|USAGE|GUIDE)(\\.[^/]+)?$"; "i") or test("(^|/)(docs|documentation)/"; "i"))' /tmp/repomix-analysis.json
5. jq -r '.files["README.md"]' /tmp/repomix-analysis.json
6. jq -r '.directoryStructure' /tmp/repomix-analysis.json | awk '{ match($0, /^ */); depth = RLENGTH / 2; if (depth <= 1) print }'
7. jq -r '.files | keys[] | select(startswith("src/"))' /tmp/repomix-analysis.json
8. jq -r '.files | to_entries[] | select(.value | test("repomix|mcp|compression"; "i")) | .key' /tmp/repomix-analysis.json
9. jq -r '.files | to_entries[] | select(.value | contains("repomix")) | .key' /tmp/repomix-analysis.json
10. jq -r '.files | to_entries[] | select(.value | test("\\brepomix\\b"; "i")) | .key' /tmp/repomix-analysis.json

Instructions

• Start by defining the research goal, success criteria, and the exact questions to answer.
• Follow the workflow in order unless the evidence clearly requires a detour.
• Do not jump to conclusions. Gather evidence first, then update your working hypothesis.
• After each command, file read, or search result, pause and choose the next highest-value step.
• Prefer small, targeted reads over broad dumps. Expand scope only when the current evidence is insufficient.
• For ambiguous questions, keep 2-3 competing hypotheses and eliminate them with evidence.
• Verify important claims in more than one place when possible, ideally in both documentation and code.
• Ground every material claim in exact repository evidence: file paths, symbols, and short excerpts.
• If evidence is missing, weak, or conflicting, say so explicitly instead of guessing.
• Before finishing, check that every original question is either answered with evidence or explicitly marked unresolved.
• Do not stop early. Continue until the research goal is satisfied or the remaining uncertainty is clearly bounded.