That template scores 8+ on the rubric on its own, before the underlying code is even good. Most candidates do not write READMEs this clear. Doing so puts you in roughly the top 5% of submissions a hiring manager will see this week.
## LinkedIn Optimization
LinkedIn is not optional. About 60% of recruiters source candidates through LinkedIn search; if your profile is weak or absent, you are invisible to that 60%.
#### The five LinkedIn elements that matter
1. **Headline.** Not "Student" or "Open to opportunities." Write what you actually do in concrete terms. Example: "ML Engineer building RAG systems for legal/clinical text | RugvAI Labs alum | Ex-Backend at [Company]." Specific > vague, every time.
2. **Photo.** Recent, clear, professional-but-human. Headshot, not wedding photo, not blurry, not avatar.
3. **About.** Three paragraphs maximum: what you do, what you have shipped, what you are looking for. Include your portfolio URL in plain text in the last paragraph.
4. **Featured section.** Pin 3 things: your portfolio website, your headline GitHub project, your best blog post. Add custom thumbnails (LinkedIn lets you upload one — most people don't).
5. **Experience.** STAR-format bullet points with **numbers**. Not "Worked on machine learning systems." Yes "Built a hybrid retrieval system serving 8k QPS at p99=180ms, reducing inference cost by 37% vs the prior baseline."
**LinkedIn posts as portfolio.** Posting about your work — building in public — does two things: (a) it forces you to articulate what you are doing, which deepens your understanding; (b) it builds a public track record that recruiters search. Post 1-2 times per week. Examples:
- "Just shipped v0.2 of my legal-doc-rag system. Switched from cosine similarity to hybrid BM25+vector after my eval set showed a 30% precision drop on case names. Here is what I learned: [3 bullet points]. Link in comments."
- "Three weeks into rebuilding the Karpathy makemore series in JAX. Surprising lesson: pmap is far more ergonomic than I expected. Here is the diff that converted my training loop. [code snippet]."
Posts with **specific technical content** get 5-10x the engagement of "I'm learning AI" posts. Recruiters DM the candidates who post specifics.
## Blog Posts as Portfolio Pieces
A single 1,500-word technical blog post that hits the front page of Hacker News or gets 5,000 reads on Substack/Medium can be worth more than three GitHub projects. It demonstrates **communication ability** — a skill ML interviewers explicitly probe for and most candidates fail on.
#### The 4-part technical-post structure that works
1. **The problem and why it was harder than expected.** (200-400 words.) Specific, concrete. "I tried to do X. I expected Y. The actual difficulty was Z."
2. **The approach.** (400-700 words.) Walk through what you tried, with code snippets. Include the failures, not just the successes.
3. **The evaluation.** (200-400 words.) A table, a chart, or specific numbers. "Approach A gave me 0.42 precision. Approach B gave me 0.68. Here is why."
4. **Lessons learned and what you would do differently.** (200-400 words.) Specific, honest. "Next time I would skip step X. The biggest mistake was Y."
Publish on your own domain (best for SEO), on Substack (best for distribution), or on a personal Hashnode/Hashnode-Medium (also fine). Cross-post to LinkedIn. Cross-post to Hacker News once if relevant. Cross-post to /r/MachineLearning if the topic fits their guidelines.
## Demo Videos: The Highest-Leverage 5 Minutes
A 60-90 second screen recording of your project running, embedded in your README and on your portfolio site, is the single highest-ROI artifact you can make.
**Why it works:** A recruiter who is scanning 200 portfolios in 3 hours is going to spend 30 seconds on yours. A static screenshot earns them 30 seconds of attention. A short video earns 60. A 60-second video that actually demonstrates the product earns the full 90 seconds plus a click into your repo.
**How to make one:** [Loom](https://loom.com/), [Tella](https://tella.tv/), [QuickTime + iMovie](https://www.apple.com/imovie/), or the macOS built-in screen recorder (Cmd-Shift-5). Edit out the dead time, add captions to the key moments, export as an MP4 < 25MB, embed in README via GitHub's video upload, and link to it on your portfolio site.
Most candidates do not do this. The marginal effort is one hour. The marginal upside is significant.
## The Seven Portfolio Mistakes That Nuke Strong Candidates
1. **Pinning tutorial reproductions.** Pinning your MNIST tutorial signals you did the tutorial. The hiring manager already assumes you did the tutorial. Unpin it.
2. **README of "WIP" or "Coming soon" on the headline project.** Either ship it or take it down. "WIP" reads as "abandoned, never finished" to a hiring manager.
3. **Hardcoded API keys committed in commit history.** This is an instant rejection at security-conscious companies (and a real-world security incident). Use [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) or [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) to scrub. And rotate the keys.
4. **No commit history.** A single commit titled "initial commit" with 5,000 lines of code reads as a copy-paste, not a build. Commit incrementally. Show the work.
5. **`pickle.load()` of someone else's model.** If your "ML project" downloads a pretrained model and runs inference, that is a wrapper, not an ML project. Either train something yourself (even a small one) or be explicit that the project is "applied AI using a pretrained Claude model" — which is fine as long as the wrapper does something interesting.
6. **One single 8,000-line file.** A senior engineer's instant signal of "this person has never reviewed real production code." Break into modules. Use a package layout. Add `__init__.py`.
7. **Linking to a private repo on a public resume.** The hiring manager clicks, gets a 404, moves on. If a repo cannot be public, do not link it — describe the work in text instead.
<CommonMistake>
**Treating quantity as a proxy for quality.** A profile with 80+ public repositories whose strongest project scores 4/10 on the rubric above is a weaker application than one with 4 repositories whose strongest scores 9/10 — and the reason is structural, not a matter of taste. A reviewer sampling under time pressure extracts your **best** project, not your **average** one. Repository count is not the signal you think it is; depth on one artifact is. Optimize the best.
</CommonMistake>
<ArchitectView>
The architecture of a hireable portfolio:
- **Anchor project (60-80 hours invested):** Lives at the top. Scored 8+ on the rubric. Has a writeup, a demo, an eval, and tests. This is the entire portfolio's center of gravity.
- **2-3 supporting projects (10-20 hours each):** Smaller projects that show range — one might be a fine-tuning experiment, one a Kaggle competition writeup, one a small inference-optimization exploration. Each has at least a clean README.
- **A blog with 3-6 posts:** Each post is 1,200-2,500 words on a specific technical decision or experiment. These are easier to write than projects and serve as the connective tissue between projects.
- **A portfolio website:** The four-section structure (Hero, Featured, Selected, About). Fast to load, looks clean, every link works.
- **A LinkedIn that mirrors the website:** Same projects pinned, same writeups linked, same headline. Hiring managers will Google your name and find both — they should tell the same story.
The whole system is designed to do one thing: make it as cheap as possible for a recruiter or hiring manager to verify that you can ship.
</ArchitectView>
<HistoryNote>
The "portfolio" expectation in ML hiring crystallized around 2017-2019 with the rise of accessible deep-learning frameworks (PyTorch, TF 2.0) and the maturation of fast.ai. Before that, hiring leaned on Kaggle results and academic publications, and "portfolio" mostly meant a GitHub with toy projects. The current bar — anchor project + writeup + demo + eval — emerged from frontier labs hiring practices and propagated outward. By 2023-2024 it became the standard at every applied-ML team in Big Tech. By 2025-2026, it is also expected at most AI-native startups and increasingly at IT-services AI roles.
</HistoryNote>
<PaperRef
title="Designing Machine Learning Systems"
authors="Chip Huyen"
year={2022}
note="The book most often referenced in hiring-loop calibration meetings. Chapters on evaluation and deployment overlap with the portfolio rubric used in this lesson. Reading it sharpens both your interview answers and your portfolio's substance."
/>
## Try It Yourself: Score Your Portfolio
<CodePlayground
language="python"
starterCode={`# Score your own portfolio against the 10-point rubric.
# Run this on your headline project. Be honest. Add notes.
rubric = {
"1_real_problem": {"score": 0, "note": ""},
"2_works_end_to_end": {"score": 0, "note": ""},
"3_one_click_setup": {"score": 0, "note": ""},
"4_clean_readme": {"score": 0, "note": ""},
"5_tests_in_ci": {"score": 0, "note": ""},
"6_evaluation": {"score": 0, "note": ""},
"7_live_demo_or_video": {"score": 0, "note": ""},
"8_writeup": {"score": 0, "note": ""},
"9_real_world_hardening": {"score": 0, "note": ""},
"10_non_trivial_decision": {"score": 0, "note": ""},
}
# Fill in honest scores (0 or 1) and a one-line note explaining why.
# Then identify the two lowest-cost improvements:
total = sum(d["score"] for d in rubric.values())
print(f"Your portfolio scores: {total} / 10")
if total < 8:
print("Below the hiring threshold. Pick 2 dimensions scored 0 and fix them.")
elif total < 10:
print("Above the hiring threshold. Improve the lowest-scored dimensions.")
else:
print("Maxed out. Now focus on writeup distribution and outreach.")
# Print the gap analysis
zeros = [k for k, v in rubric.items() if v["score"] == 0]
print(f"\\nDimensions to fix next ({len(zeros)} total):")
for k in zeros:
print(f" - {k}")
`}
solution={`# Run this honestly. Most candidates score 4-6 on first pass.
# The cheapest wins are usually:
# - One-click setup: spend 30 min writing a Dockerfile + .env.example
# - Clean README: spend 60 min adapting the template above
# - Tests in CI: spend 2 hours writing 10 tests + adding GitHub Actions
# - Writeup: spend 4 hours writing 1,500 words on Substack
# Combined effort: ~8 hours, lifts most portfolios from 4-6 to 7-9.`}
/>
## Quick Check
<QuizBlock questions={[
{
type: "mcq",
question: "You have 40 free hours over the next month. You currently have 3 tutorial-grade GitHub projects. What is the single highest-ROI use of those 40 hours?",
options: [
"Pick the most promising existing project and invest the full 40 hours into bringing it to 8+ on the rubric (writeup, eval, tests, demo)",
"Start 4 new small projects (10 hours each)",
"Do 40 hours of LeetCode",
"Watch 40 hours of YouTube tutorials on advanced topics"
],
correctIndex: 0,
explanation: "Depth, not breadth. Forty hours invested in deepening one project to a clear 8/10 produces ten times the hiring power of four shallow projects. The rule of 1 is the single highest-leverage portfolio principle."
},
{
type: "mcq",
question: "A hiring manager opens your GitHub project README. What MUST be visible in the first screen (no scrolling) to pass the 30-second test?",
options: [
"Your full architecture write-up",
"Your tagline, a demo screenshot/GIF, the live-demo URL, and the one-command quickstart",
"The complete eval results table",
"A list of every dependency"
],
correctIndex: 1,
explanation: "The 30-second scan needs four things visible without scrolling: what it does (tagline), what it looks like (screenshot/GIF), can I try it (demo URL), how do I run it (one-command quickstart). Everything else lives below the fold."
},
{
type: "mcq",
question: "Which of these GitHub commits patterns is most likely to be a red flag for a senior reviewer?",
options: [
"47 commits over 8 weeks, mostly small, with descriptive messages",
"12 commits over 3 weeks, half labeled 'wip', half labeled 'fix'",
"1 commit titled 'initial commit' adding 5,000 lines of code",
"23 commits over 4 weeks following Conventional Commits format"
],
correctIndex: 2,
explanation: "A single massive 'initial commit' reads as 'I copy-pasted this from a tutorial' to any experienced reviewer. Real work has incremental history. Even messy iterative commits beat a single perfect blob — the reviewer can see the build process."
},
{
type: "mcq",
question: "You wrote a 2,000-word blog post about a clever retrieval optimization. Where should you publish it for MAXIMUM portfolio impact?",
options: [
"Only on Substack",
"Only on Medium",
"Privately, as a Notion doc you can show in interviews",
"On your own portfolio site (or Substack), cross-posted to LinkedIn, with a link in your headline project's README — then optionally shared on Hacker News and Twitter"
],
correctIndex: 3,
explanation: "The post is a portfolio multiplier ONLY when it is linked from the artifacts hiring managers see. The READMEsearch hits the project; the project links the post; LinkedIn drives discovery; HN/Twitter widen the reach. The post by itself, hidden in Notion or unlinked from the project, has near-zero hiring impact."
},
{
type: "predict",
question: "Two candidates apply for the same applied ML role. Candidate A has 35 public repos, all tutorial-grade. Candidate B has 6 public repos, but the headline repo scores 9/10 on the rubric with a 2,000-word writeup and a live demo. Who gets the phone screen, and why?",
answer: "Candidate B, almost certainly, and the gap is not close. Hiring managers extract signal from your BEST project, not your average. Candidate A's 35 tutorial repos signal 'completed online courses,' which is table stakes and does not differentiate. Candidate B's single 9/10 project signals shipping ability, writing ability, eval discipline, and senior judgment — exactly what an applied ML manager is hiring for. The marginal signal from Candidate A's 35th repo is essentially zero; the marginal signal from Candidate B's writeup is enormous. Recruiters will forward Candidate B's resume the same day. Candidate A's resume gets filed under 'has done courses, see again in 6 months.'"
}
]} />
## Key Takeaways
- **The rule of 1: one great project beats five mediocre projects, every single time.** Optimize your best, not your count.
- **The 10-point rubric scores any portfolio quickly and tells you exactly what to fix.** Aim for 8+. Be honest in scoring.
- **The first 30 seconds on the README decide whether the hiring manager keeps reading.** Tagline + screenshot + demo URL + quickstart, above the fold.
- **A 4-section portfolio website + an optimized LinkedIn + 3-6 blog posts is the maximum-leverage public footprint.** Mirror the story across all three.
- **A 60-90 second demo video is the highest-ROI artifact most candidates skip.** One hour of work; large hiring upside.
- **Seven mistakes nuke strong candidates: tutorial pins, "WIP" headlines, leaked API keys, no commit history, model-wrapping disguised as ML, one giant file, dead links.** Audit and remove all seven.
<DeepDive title="Related Lessons">
- **First AI App.** What to build for your anchor project
- **Resume for AI.** The resume that complements the portfolio
- **Mock Interview Guide.** How the portfolio shows up in interviews (and how to talk about it)
- **Company Question Patterns.** Which signals each company extracts from the portfolio
</DeepDive>
<ExitTicket>
Your portfolio is **a forcing function for honesty**. Each project should hold up to both a 30-second scan (clean README, live demo, screenshot) AND a 30-minute deep dive (architecture, tradeoffs, failure analysis). Three good projects beat ten mediocre ones — and one project you actually shipped beats ten you intended to.
</ExitTicket>
---
*Your portfolio is a forcing function for honesty. Build the one project that holds up to a 30-second scan AND a 30-minute deep dive, and the interviews will come.*