Portfolio Adder Skill

The Problem

Documenting what you’ve delivered is critical for performance reviews — but it almost never happens in real time. By the time quarterly or year-end reviews arrive, the specific decisions, the metrics that moved, and the problems that were hard to solve have all faded. The result is generic self-assessments that undersell months of complex work. The friction isn’t writing ability; it’s the activation energy of sitting down with a blank page and reconstructing context from memory weeks or months after the fact.

The Solution

A two-part system: a static portfolio site that renders structured case studies from markdown files, and a Claude Code skill that conducts a guided interview, asks targeted follow-ups where answers are thin, and writes a complete entry in the exact format the site expects. The workflow is: finish a project, invoke the skill, answer questions for a few minutes, and a permanent structured record exists. No blank-page problem, no format decisions, no context reconstruction.

Outcome & Impact

The time to document a completed project dropped from 30–60 minutes (when it happened at all) to roughly 5 minutes of conversation. More importantly, documentation now happens per-project as work is completed rather than in reconstruction batches at review time — which means the detail quality is fundamentally higher, captured while context is fresh rather than reconstructed from memory.

Metric	Before	After
Time to document a project	30–60 min (if it happened at all)	~5 min conversation
Documentation timing	Sporadic, usually at review time	Per-project as completed
Detail quality	Reconstructed from memory	Captured while fresh
Format consistency	N/A	Enforced by schema at build time

My Role & Contributions

Aspect	Detail
Role	Sole designer and implementer
Team size	1
Timeline	1 day
Scope	Site architecture, content schema, skill prompt engineering, section taxonomy
Key decisions	Framework selection, content collection schema design, interview flow structure, section coverage

Technical Overview

┌─────────────────────────────────┐
│     Claude Code Skill           │
│     /portfolio-adder            │
│                                 │
│  • Guided interview flow        │
│  • Section-by-section capture   │
│  • Frontmatter generation       │
│  • File placement               │
└──────────────┬──────────────────┘
               │ writes .md file
               ▼
┌─────────────────────────────────┐
│     Astro Content Collection    │
│     src/content/cases/          │
│                                 │
│  • Zod schema validation        │
│  • Date-sorted rendering        │
│  • Tag + tool badge display     │
│  • Month-grouped sidebar        │
└──────────────┬──────────────────┘
               │ builds to
               ▼
┌─────────────────────────────────┐
│     Static Site                 │
│  • Card grid index              │
│  • Detail pages per entry       │
│  • Screenshot galleries         │
└─────────────────────────────────┘

The skill is a structured prompt that walks through ten defined sections — problem, solution, role, technical overview, challenges, impact, and others — and pushes specifically on impact and role, the sections that most differentiate strong entries from generic ones. It generates a complete markdown file with validated frontmatter and writes it directly to the content collection; the site picks it up automatically on the next build.

The site is built on Astro with content collections and Zod schema validation. The schema enforces required fields at build time, so a malformed entry (missing a date, an empty summary) fails the build rather than silently rendering a broken card. Detail pages use dynamic routes rendering markdown with tool badges, tags, and optional screenshot galleries.

Challenges & Key Decisions

Skill-driven entry creation over templates

A template file or web form would have been simpler to build. The skill approach is better because it asks follow-up questions, surfacing details I’d skip if filling out a form. It handles formatting and frontmatter so I stay focused on content. Most importantly, it pushes on impact and specifics — it acts as an interviewer, not a blank page.

Astro over simpler alternatives

I could have used a plain markdown folder with a viewer, or a Notion database. Astro’s content collections with Zod validation catch malformed entries at build time rather than at runtime. Static output means zero hosting complexity. Markdown bodies allow arbitrary depth per entry without schema bloat — a short entry and a long one coexist without any schema negotiation.

Comprehensive section prompts over minimal templates

Ten sections feels like a lot. But it’s easier to skip a section that doesn’t apply than to remember one you forgot to include. The prompts act as a checklist that ensures angles like “what decisions were specifically yours” and “what would you do differently” don’t get silently dropped.

Lessons Learned

• The best documentation system is the one with lowest friction. A guided conversation has less activation energy than a blank template. The skill acts as an accountability partner that won’t accept vague answers.
• Schema validation at build time catches drift before it compounds. Zod ensures every entry has required fields before the site renders — no broken cards from a forgotten frontmatter field discovered weeks later.
• Comprehensive section prompts beat minimal templates. It’s easier to skip a section that doesn’t apply than to remember one you forgot.