portfolio-strategy

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)

• Profile photo is professional (or intentionally distinctive)
• Bio states what you do and what you're looking for
• Pinned repos have descriptions that make sense to a stranger
• At least 3 pinned repos have screenshots or demo links in the README
• No embarrassing repo names visible on the first page

Depth Check (2 minutes)

• Each pinned repo has a README that explains the what, why, and how
• At least one project has a live demo or deployment link
• Code quality in pinned repos reflects your current skill level
• Commit history shows real development (not a single "initial commit" blob)
• At least one repo demonstrates testing or CI/CD

Story Check (5 minutes)

• Your pinned repos tell a coherent story about your skills
• There's visible progression from older to newer projects
• Your portfolio aligns with the roles you're targeting
• You can explain every pinned repo in a 60-second elevator pitch
• You'd hire yourself based on this GitHub

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