GitHub Repository Reader Skill

Deep repository analysis skill for turning a GitHub URL into a professional, one-page project brief that demonstrates practical programming experience with concrete source evidence.

Table of Contents

• Overview
• What This Skill Produces
• Core Workflow
• Inputs and Outputs
• Repository Analysis Depth Policy
• Code Snippet Selection Rules
• Engineering Quality Assessment
• Output Formats and Templates
• Multi-Project Behavior
• Error Handling and Fallbacks
• Skill Directory Structure
• Quick Start
• Example Prompts
• Recommended Collaboration with Other Skills
• Evaluation Suite
• Performance Targets
• Limitations
• Customization Guide
• Maintenance Checklist

Overview

github-repo-reader is designed for portfolio and hiring-oriented project presentation.

It reads repository metadata and source files, identifies architecture and technical decisions, extracts representative code snippets, and generates concise deliverables that answer requirements such as:

"Each project should be presented separately (max 1 page per project), with clear links to GitHub or relevant repositories that showcase source code and practical programming experience."

This skill emphasizes evidence-based analysis. Every technical claim should map back to repository files or metadata.

What This Skill Produces

For each repository, the skill produces one project-focused summary with:

• Project title and one-line value statement.
• Prominent repository link.
• Core technical stack.
• 3 to 5 key capabilities.
• 2 to 3 code snippets (typically 10 to 20 lines each).
• Architecture summary.
• Practical engineering highlights.
• Metrics (stars, forks, contributors, activity, tests, and related indicators when available).

Output can be generated as:

• PDF-oriented Markdown (templates/pdf-template.md).
• Standard Markdown (templates/markdown-template.md).
• One-page responsive HTML (templates/html-template.html).

Core Workflow

The workflow is intentionally strict and repeatable:

1. Confirm user intent and output target.
2. Discover available MCP capabilities from github-repo-reader.
3. Collect repository evidence (metadata, README, tree, core files).
4. Classify project type and architecture style.
5. Read high-signal files deeply.
6. Assess engineering quality using a structured rubric.
7. Select high-value code snippets.
8. Generate final document in requested format.
9. Validate one-page and evidence-traceability constraints.

For the full operational instruction set, see SKILL.md.

Inputs and Outputs

Typical Input

• One or more GitHub repository URLs.
• Desired output format: pdf, markdown, or html.
• Audience context (hiring manager, interviewer, engineer peer, etc.).

Typical Output

• One output per repository.
• Concise and structured project brief.
• Repository and file links for verification.
• Clear, practical narrative focused on implementation quality.

Repository Analysis Depth Policy

This skill supports both fast and exhaustive modes:

• If repository size is small (about 200 files or fewer), default to full file-by-file traversal.
• If repository is larger, start with high-signal files and expand package-by-package.
• If user explicitly requests exhaustive review, continue through all files and state that runtime may increase.

This policy keeps analysis both practical and controllable.

Code Snippet Selection Rules

Select snippets that demonstrate technical depth, not boilerplate.

Prioritize:

• Core business logic or algorithmic code.
• Error handling and edge-case protection.
• Extensible abstractions and clean interfaces.
• Performance-aware implementation details.

Avoid:

• Trivial setup code.
• Snippets requiring too much hidden context.
• Duplicative patterns that do not add new evidence.

Engineering Quality Assessment

Use analyzers/quality-metrics.md to score and summarize:

• Documentation quality.
• Test evidence and testing discipline.
• Code structure and maintainability.
• Reliability and defensive practices.
• Delivery/operations maturity.

Final assessment should include:

• A weighted score.
• Top strengths.
• Highest-impact gaps.
• Confidence level based on available evidence.

Output Formats and Templates

PDF-Oriented Markdown

• Template: templates/pdf-template.md
• Goal: one A4-equivalent page.
• Best for resumes, interviews, and formal submission packets.

Markdown

• Template: templates/markdown-template.md
• Goal: editable, version-control-friendly project documentation.
• Best for GitHub profile pages and technical notes.

HTML

• Template: templates/html-template.html
• Goal: interactive one-page web presentation.
• Includes responsive layout and collapsible code sections.

Multi-Project Behavior

When analyzing multiple repositories:

• Process each project independently.
• Generate one page/document per project.
• Keep consistent section ordering for cross-project comparison.
• Do not merge multiple projects into one page unless explicitly requested.

Error Handling and Fallbacks

Private or inaccessible repository

• Report access issue clearly.
• Request token-enabled access or local snapshot.

Missing README

• Infer project purpose from code structure and entry points.
• Label confidence level explicitly.

Very large repository

• Start with high-signal files.
• Record sampling strategy in output.

Multi-language repository

• Identify primary language and secondary language roles.
• Explain role boundaries in stack section.

Skill Directory Structure

github-repo-reader/
├── SKILL.md
├── README.md
├── README_CN.md
├── agents/
│   └── openai.yaml
├── templates/
│   ├── pdf-template.md
│   ├── markdown-template.md
│   └── html-template.html
├── analyzers/
│   ├── language-detector.md
│   ├── pattern-recognizer.md
│   └── quality-metrics.md
├── evals/
│   ├── evals.json
│   └── files/
│       ├── sample-repos.json
│       └── expected-outputs/
│           ├── web-app-test.md
│           ├── cli-tool-test.md
│           ├── library-test.md
│           └── minimal-repo-test.md
└── examples/
    ├── web-app-example.md
    ├── cli-tool-example.md
    └── library-example.html

Quick Start

1. Trigger this skill by asking to analyze a GitHub repository and generate a project brief.
2. Provide repository URL and desired output format.
3. Confirm intended audience and purpose (resume, interview, portfolio page).
4. Run analysis workflow from SKILL.md.
5. Fill template placeholders and produce final output.

Example Prompts

• "Analyze this GitHub repository and create a one-page project summary for interviews."
• "Extract technical highlights from this repo and generate Markdown output."
• "Generate an HTML one-page showcase with code examples from this project."
• "Review three repos and create one separate page for each project."

Recommended Collaboration with Other Skills

This skill is extraction-first. For polished deliverables:

• Use a DOCX-oriented skill to convert structured content into interview-ready documents.
• Use a PDF-focused skill for final one-page PDF conversion.
• Use a frontend design skill for enhanced HTML visual presentation.

Recommended sequence:

1. github-repo-reader for analysis and evidence extraction.
2. Formatting skill (docx/pdf/frontend) for final output packaging.

Evaluation Suite

Evaluation data is included under evals/:

• evals/evals.json: test cases and quality gates.
• evals/files/sample-repos.json: representative repositories.
• evals/files/expected-outputs/*: expected output characteristics per repo category.

Current test categories:

• Complex web application.
• CLI tool.
• Open-source library.
• Minimal repository with sparse evidence.

Performance Targets

Target behavior for practical use:

• Analyze a medium-size repository quickly (goal: within a few minutes, depending on MCP throughput).
• Keep final project page concise and one-page equivalent.
• Include at least two high-value snippets in every normal case.
• Maintain high stack-identification accuracy via file-based evidence.

Limitations

• Actual capability depends on the connected github-repo-reader MCP server methods.
• Private repository access requires proper authentication path.
• Extremely large repositories may require staged analysis and selective depth.
• Generated quality metrics are evidence-based heuristics, not full static analysis.

Customization Guide

To tailor this skill to your environment:

• Update template wording and visual style in templates/.
• Extend stack heuristics in analyzers/language-detector.md.
• Extend architecture rules in analyzers/pattern-recognizer.md.
• Tune scoring weights in analyzers/quality-metrics.md.
• Add domain-specific eval cases in evals/evals.json.

Maintenance Checklist

• Keep templates aligned with your hiring/portfolio narrative.
• Revisit analyzer heuristics when your project types change.
• Add new eval samples when quality drift appears.
• Periodically verify MCP capability mapping in live usage.