# Github Repo Reader

> Deeply analyze GitHub repositories with a github-repo-reader MCP server and generate one-page project presentation documents (PDF-ready Markdown, Markdown, or HTML) with repository links, architecture summaries, code snippets, technical highlights, and engineering-quality evidence. Use when users ask to analyze a GitHub URL, extract technical highlights from a repository, build project portfolio entries, or present practical programming experience from source code.

- Skill: `samxiexs/github-repo-reader` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add samxiexs/github-repo-reader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samxiexs/github-repo-reader/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: samxiexs (https://skillmd.com/u/samxiexs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/samxiexs/github-repo-reader

---


# GitHub Repository Reader

Analyze repository internals and produce professional project pages suitable for hiring packets, portfolio sites, and technical reviews.

## Output Contract

Create one separate deliverable per project.

Enforce the page limit:
- Maximum 1 page per project for PDF-oriented output.
- For Markdown and HTML, keep the content equivalent to a one-page brief.

Always include:
- Project title and one-line value statement.
- Prominent repository URL.
- Core tech stack (language, framework, tooling).
- 3 to 5 key capabilities.
- 2 to 3 code snippets (10 to 20 lines each, with short commentary).
- Architecture summary.
- Metrics (stars, forks, contributors, activity, tests, or other measurable evidence).

## Execution Workflow

### 1. Confirm input and target

Collect:
- GitHub URL(s).
- Target output format: `pdf`, `markdown`, or `html`.
- Audience: hiring manager, technical interviewer, engineering peer, or general audience.

If user does not specify format, default to `markdown`.

### 2. Discover MCP capabilities

Inspect the `github-repo-reader` MCP server and map available operations.

Prefer these capabilities when available:
- Repository metadata retrieval.
- File tree listing.
- README retrieval.
- File content read.
- Optional code search.

If exact method names differ, map semantically and continue.

If MCP access is unavailable:
- State the limitation.
- Continue with any locally available repository snapshot, if provided.

### 3. Collect repository evidence

Gather:
- Name, description, owner, default branch.
- Primary language and language distribution.
- Stars, forks, watchers, open issues, contributors count (if available).
- Last updated timestamp.
- README content.
- Root file tree.

Store links for:
- Repository home.
- Core files used for analysis.

### 4. Classify project and architecture

Infer project type:
- Web app, API service, CLI, library/framework, data/ML pipeline, infra/tooling, or mixed.

Infer architecture style:
- Layered, MVC, modular monolith, event-driven, microservice, plugin-based, pipeline, or library-centric.

Read `analyzers/language-detector.md` for language and ecosystem hints.
Read `analyzers/pattern-recognizer.md` for architecture and design pattern evidence.

### 5. Prioritize files for deep reading

Read in this order unless repo shape requires adjustment:
1. `README.md`
2. Dependency manifests (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.)
3. Entrypoints (`main.*`, `index.*`, CLI command entry files)
4. Core source directories (`src/`, `lib/`, `cmd/`, `app/`)
5. Test files and test configuration
6. CI/CD and quality configs (`.github/workflows/`, lint/format/test configs)
7. Docs (`docs/`, design notes, ADRs)

Select only the highest-signal files when repositories are large.

Depth policy:
- If repository has 200 files or fewer, perform full file-by-file traversal.
- If repository has more than 200 files, perform high-signal traversal first, then continue package-by-package until confidence is sufficient.
- If user explicitly asks for exhaustive review, continue traversal across all files and clearly mark longer runtime.

### 6. Evaluate engineering quality

Use `analyzers/quality-metrics.md` and score:
- Documentation quality.
- Test evidence.
- Code organization and modularity.
- Reliability practices (validation, error handling, retries, logging).
- Operational readiness (CI/CD, tooling, observability hints).

Report both strengths and concrete gaps.

### 7. Extract code highlights

Choose snippets that prove practical engineering skill:
- Non-trivial logic, algorithmic clarity, or data-structure usage.
- Robust error handling and boundary checks.
- Extensibility or clean abstraction.
- Performance-conscious implementation.

Snippet rules:
- 10 to 20 lines each.
- Maximum 3 snippets.
- Add 1 to 2 sentence explanation for each snippet.
- Include direct link to original file.

### 8. Generate deliverable

Use templates in `templates/`:
- `templates/pdf-template.md` for PDF-ready content.
- `templates/markdown-template.md` for editable documentation.
- `templates/html-template.html` for one-page web showcase.

Keep content dense and specific. Avoid generic claims.

### 9. Validate before finalizing

Check each project output against this checklist:
- Exactly one project per page/document.
- Repository link visible near title.
- Technical stack identified with evidence.
- At least 2 real code snippets.
- Architecture and key decisions explained.
- Measurable metrics included.
- Claims traceable to files/metadata.

## Multi-Project Mode

When user provides multiple repositories:
- Analyze each repository independently.
- Produce one output per repository.
- Keep consistent section order for comparability.
- Do not merge multiple projects into a single page unless user explicitly asks.

## Error Handling

If repository is private or inaccessible:
- Report access failure clearly.
- Ask for token-enabled access or exported repository snapshot.

If README is missing:
- Infer purpose from source tree and entrypoints.
- State confidence level.

If repository is too large:
- Sample critical files first.
- Note that analysis is based on high-signal subset.

If project is multi-language:
- Identify primary language by source and manifests.
- Label secondary languages and their role.

## Collaboration With Other Skills

When available:
- Use `docx` skill to produce Word output before PDF conversion.
- Use `pdf` skill to convert final layout to PDF.
- Use frontend design skills to refine advanced HTML showcase pages.

Use this skill first for technical extraction and evidence gathering, then hand off formatted content.