| name | portfolio-strategy |
| description | Build a GitHub portfolio that gets you hired — curate 3-5 polished projects, craft compelling READMEs, deploy live demos, tell a coherent story across your repos, and align everything to AI-native development roles. Use when preparing your GitHub for job searches, deciding what to pin, or auditing your public presence. |
Portfolio Strategy
Core Principle
Your GitHub is not a graveyard of half-finished projects. It's a curated exhibit. Every pinned repo should answer one question a hiring manager has about you — and every answer should make them want to schedule an interview.
What Separates Impressive from Mediocre
MEDIOCRE PORTFOLIO IMPRESSIVE PORTFOLIO
───────────────── ────────────────────
30 repos, mostly forks 5 repos, all original work
No READMEs Each README tells a story
No live demos Every project is deployed
Random tutorials cloned Clear theme and progression
Last commit: 8 months ago Consistent, recent activity
No descriptions on repos Every repo has a one-liner
"my-first-react-app" "AI-powered code review tool"
The difference isn't talent. It's curation. The best portfolios look like someone with a plan, not someone who commits everything they touch.
Quality Over Quantity
Three to five polished projects beats thirty abandoned repos. Every time.
The Math That Matters
| Repos | READMEs | Deployed | Hiring Manager Thinks |
|---|
| 30 | 2 | 0 | "Starts things, doesn't finish them" |
| 15 | 5 | 1 | "Dabbles. Unclear what they're good at" |
| 5 | 5 | 4 | "Focused. Ships. Knows their craft" |
| 3 | 3 | 3 | "Everything they touch is polished" |
The Cleanup Rule
Before adding anything new, audit what's already there:
1. Archive or make private anything unfinished and unsalvageable.
2. Delete forked repos you never modified.
3. Add READMEs to anything you're keeping public.
4. Set descriptions on every visible repo.
5. What's left should be worth showing.
If you wouldn't put it on your resume, it shouldn't be on your public GitHub.
Tell a Story Across Your Repos
Your pinned repos aren't random samples. They're chapters. Arrange them so a visitor sees a narrative.
Story Structures That Work
The Specialist Arc:
"I go deep on AI/ML and I can prove it."
Repo 1: Fine-tuned LLM for domain-specific task
Repo 2: RAG pipeline with evaluation framework
Repo 3: Agentic workflow with tool use
Repo 4: Open-source contribution to LangChain/LlamaIndex
The Full-Stack Builder Arc:
"I build complete products from database to deploy."
Repo 1: Full-stack SaaS app (Next.js + API + DB + Auth)
Repo 2: AI-powered CLI tool (shows backend/systems chops)
Repo 3: Open-source library (shows API design thinking)
Repo 4: Personal automation tool (shows you build for yourself too)
The AI-Native Developer Arc:
"I don't just use AI — I build with it and build for it."
Repo 1: Agentic workflow / multi-agent system
Repo 2: LLM integration in a production-grade app
Repo 3: Developer tool that leverages AI (linter, reviewer, generator)
Repo 4: Contribution to an AI framework or toolchain
Progression Signals
Hiring managers notice when your repos show growth:
| Signal | What It Shows |
|---|
| Early repo: simple CRUD app | You started somewhere |
| Middle repo: API with tests and CI | You learned engineering practices |
| Recent repo: AI agent with evals | You're building at the frontier |
| Contribution to major OSS project | You can work in large codebases |
What to Pin and Why
You get six pinned repos. Use them strategically.
The Ideal Pin Layout
| Slot | What to Pin | Why |
|---|
| 1 | Full-stack project | Proves you can build a complete product |
| 2 | AI/ML project | Shows you work at the frontier |
| 3 | Open-source contribution | Proves you collaborate in real codebases |
| 4 | Developer tool or CLI | Shows you solve your own problems |
| 5 | Domain project (your specialty) | Depth signal for your target role |
| 6 | Wildcard — personal or creative | Shows personality and genuine curiosity |
Pinning Rules
DO pin:
- Projects with live demos or deployment links
- Repos with thorough READMEs and screenshots
- Work that matches the roles you're applying for
- Your most recent, most polished work
DON'T pin:
- Forked repos you didn't meaningfully modify
- Tutorial follow-alongs (even if completed)
- Repos with no README
- Anything you can't explain in an interview
README as Your Portfolio Pitch
Every pinned repo needs a README that sells the project in 30 seconds. A hiring manager will spend less time than that before deciding whether to keep reading.
README Structure for Portfolio Repos
# Project Name
One-sentence description of what it does and why it matters.
## Demo
[Link to live demo] | [Link to video walkthrough]
Screenshot or GIF showing the app in action.
## The Problem
What problem does this solve? Who has this problem?
## How It Works
Architecture overview. Key technical decisions.
Diagram if the system has multiple components.
## Tech Stack
List of technologies — but only the meaningful ones.
Don't list HTML/CSS. Do list your AI integrations, databases, deployment targets.
## Key Features
- Feature 1 — why it's interesting technically
- Feature 2 — what was hard about building it
- Feature 3 — what you'd improve next
## Getting Started
Clear setup instructions. Someone should be able to run this in under 5 minutes.
## What I Learned
Brief reflection on the hardest technical challenge and how you solved it.
README Anti-Patterns
| Bad README | Better README |
|---|
| "A React app" | "AI-powered meeting summarizer that turns recordings into action items" |
| No screenshots | Hero screenshot or GIF above the fold |
| Setup: "clone and run" | Setup: step-by-step with prerequisites listed |
| No architecture explanation | System diagram showing how components connect |
| Lists every npm package | Highlights the 3-4 technologies that matter |
Live Demos and Deployment Links
Code is a hypothesis. A deployed app is proof.
Why Deployment Matters
Hiring manager sees repo with no demo:
"Interesting code... does it actually work?"
Hiring manager sees repo with live link:
"Let me try it." → 2 minutes later → "This person ships."
Deployment Options by Project Type
| Project Type | Free Deployment | Good For |
|---|
| Full-stack web app | Vercel, Railway, Fly.io | Production-feel apps |
| API / backend | Railway, Render | Showing backend skills |
| Static site / docs | GitHub Pages, Netlify | Documentation, landing pages |
| AI/ML demo | Hugging Face Spaces, Streamlit Cloud | Model demos, data apps |
| CLI tool | npm publish, Homebrew tap | Distribution signal |
If You Can't Deploy, Record a Demo
Not everything can run in the cloud. For local-only tools, CLI apps, or complex systems:
1. Record a 60-90 second video walkthrough.
2. Upload to YouTube (unlisted is fine).
3. Create a GIF of the key interaction.
4. Put both in the README.
A video demo is ten times better than no demo.
Contribution Graph
What Consistency Signals
Hiring managers glance at your contribution graph. Here's what they actually read from it:
| Pattern | Interpretation |
|---|
| Steady green, most days | "This person codes regularly. Good habit." |
| Clusters around projects | "Works in focused sprints. Normal." |
| Green only on weekdays | "Has a job, still ships personal work." |
| Mix of own repos and contributions | "Collaborative. Not just solo projects." |
What Gaming Looks Like
Experienced reviewers can spot these instantly:
RED FLAGS:
- Perfectly uniform green (every single day, same intensity)
- Commits that are only README edits or whitespace changes
- 500 commits in a day to empty repos
- Dozens of repos created in one week, all with single commits
- Auto-generated commit bots
Gaming your graph is worse than having gaps. It signals desperation and poor judgment. Real consistency means working on things you care about on a regular cadence — gaps and all.
Building a Real Graph
Instead of faking it:
1. Pick one project and work on it 30 minutes a day.
2. Contribute to open source — even docs, tests, or bug reports count.
3. Keep a learning repo where you commit notes and experiments.
4. Build tools you actually use. You'll naturally keep improving them.
Aligning Your Portfolio to the Role You Want
Your portfolio should look like a preview of the work you'd do if hired. Tailor it to your target.
AI-Native Development Roles
These roles want to see that you can build with AI and build for AI:
| Signal | Example Repo |
|---|
| AI tool usage in your workflow | Project with .claude/ config, AI-assisted commits, Claude Code slash commands |
| Agentic workflows | Multi-step agent that researches, plans, and executes tasks |
| LLM integrations | App with structured output, prompt engineering, model routing |
| RAG and retrieval | Knowledge base with embedding search and evaluation metrics |
| Evaluation and testing | LLM output evaluation framework, prompt regression tests |
| AI-assisted development | Project README documenting how AI tools accelerated development |
Role-Specific Portfolio Targets
| Target Role | Must-Have Repos | Nice-to-Have |
|---|
| AI/ML Engineer | Fine-tuned model, eval framework, data pipeline | Paper implementation, model comparison |
| Full-Stack AI Developer | LLM-integrated app, RAG system, deployed SaaS | Open-source contribution, CLI tool |
| Platform / Infra Engineer | CI/CD pipeline, IaC repo, monitoring setup | Performance benchmark, OSS contrib |
| Developer Tools / DX | CLI tool, SDK/library, VS Code extension | Docs site, developer community tool |
Portfolio Review Checklist
Run this audit before every job search. Be honest.
First Impressions (30 seconds)
Depth Check (2 minutes)
Story Check (5 minutes)
The Ultimate Test
Open your GitHub in an incognito window. Pretend you're a hiring manager who's never met you. Spend 60 seconds. Would you move this candidate to the next round?
If the answer isn't an immediate yes, keep iterating.
Anti-Patterns
| Anti-Pattern | Why It Hurts | Fix |
|---|
| Forked repos with no changes | Looks like padding | Delete or make private |
| Tutorial clones ("todo-app", "weather-app") | Signals you followed instructions, not that you can build | Fork it, then extend it far beyond the tutorial |
| Empty repos or repos with only a README | Signals abandoned ideas | Archive or delete them |
| No READMEs on public repos | "I don't communicate about my work" | Add READMEs to everything you keep public |
| 50+ visible repos with no curation | Overwhelming noise, no signal | Archive aggressively, pin strategically |
| Outdated pinned repos (2+ years old) | "They haven't built anything recently" | Rotate pins to show recent work |
| Profile README with just auto-generated stats | Impersonal, low effort | Write a real bio with your focus and goals |
| Repos named "test", "temp", "asdf" | Careless | Rename or remove |
Power Move
"Review my GitHub portfolio at [your GitHub URL]. Evaluate it as if you're a hiring manager for an AI-native development role. Score each pinned repo on README quality, technical depth, deployment status, and relevance to AI/ML roles. Then give me a prioritized action plan: what to archive, what to improve, what's missing, and what one new project would make the biggest difference."
The agent becomes your portfolio critic — giving you the honest, specific feedback you need to turn your GitHub from a code graveyard into a career asset.
Related Skills
| Skill | When to use it |
|---|
github-profile | Implement GitHub platform mechanics — profile README, repo pinning, topics, activity graph |
career-advisor | Full career lifecycle — self-discovery, gap analysis, job search, growth |
