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.