Deck Review Skill
Help startup founders strengthen their pitch decks before sending them to investors. Produce a structured, scored review with specific, actionable recommendations grounded in current best practices from Sequoia, DocSend, YC, a16z, and Carta data. The tone is founder-first: a candid coaching session, not a VC evaluation.
Skill Metadata
- Author: lool-ventures
- Version: managed in
founder-skills/.claude-plugin/plugin.json - Compatibility: Python 3.10+ and
uvfor script execution. - Exports:
checklist.json→financial-model-review,ic-sim,fundraise-readiness
Skill Execution Model (READ FIRST)
This skill runs inline in the main thread (not as a sub-agent). The main thread has full tool access including Bash, and is responsible for orchestrating the full pipeline: running producer scripts, persisting artifacts, and dispatching the deck-review sub-agent at specific moments.
Two dispatch contexts for the sub-agent:
- Context A — Per-step analytical dispatch (Mitigation 1): Steps 4 and 5 dispatch the deck-review agent via the
Tasktool. The agent does deep analysis and returns structured JSON. The main thread captures the JSON and pipes it through the producer script (slide_reviews.pyorchecklist.py). The sub-agent does NOT write artifacts directly. - Context B — Post-compose coaching dispatch: Step 7 dispatches the sub-agent after
compose_report.pywritesreport.md. The sub-agent readsreport.md, appends## Coaching Commentary, verifies all canonical artifacts on disk, and returns a structured success payload.
Why this model: In Cowork, sub-agents have a restricted tool allowlist (no Bash). By keeping orchestration in the main thread and dispatching sub-agents only for analytical or post-compose tasks that use only Read/Edit/Glob/Grep, the pipeline works correctly in both Claude Code (CLI) and Cowork.
Tolerant JSON extraction protocol (Context A): After dispatching the sub-agent, capture its final assistant message. The sub-agent should return raw JSON, but may wrap it in ```json ... ``` fences or add a prose preamble. Extract JSON tolerantly:
- If the message is wrapped in a
```json ... ```(or plain``` ... ```) fence, strip the fence first. - Try to parse the stripped text directly as JSON.
- If that fails, walk through the text looking for the first
{character and tryjson.JSONDecoder().raw_decode(text[i:])— this is brace-aware and handles nested objects correctly (unlike regex, which truncates on the first}). - If extraction fails entirely, re-prompt the sub-agent with: "Your previous reply could not be parsed as JSON. Return ONLY the JSON object — no markdown fences, no prose preamble."
See
founder-skills/references/skill-execution-model.mdfor the full inline-skill execution model (3 dispatch contexts, Mitigation 1+2, producer contract, Cowork quirks, per-symptom triage).
Input Formats
Accept any format: PDF, PowerPoint (PPTX), markdown, or text descriptions of slides.
Available Scripts
All scripts are at ${CLAUDE_PLUGIN_ROOT}/skills/deck-review/scripts/:
checklist.py— Scores 35 criteria across 7 categories (pass/fail/warn/not_applicable)compose_report.py— Assembles artifacts into final report with cross-artifact validation;--strictexits 1 on high/medium warningsvisualize.py— Generates self-contained HTML with SVG charts (not JSON)
Also available from ${CLAUDE_PLUGIN_ROOT}/scripts/ (shared):
founder_context.py— Per-company context management (init/read/merge/validate)
Run with: python3 ${CLAUDE_PLUGIN_ROOT}/skills/deck-review/scripts/<script>.py --pretty [args]
Available References
Read as needed from ${CLAUDE_PLUGIN_ROOT}/skills/deck-review/references/:
deck-best-practices.md— Full best practices: slide frameworks, stage-specific guidelines, design rules, AI-company requirementschecklist-criteria.md— Definitions for all 35 criteria with pass/fail/warn thresholdsartifact-schemas.md— JSON schemas for all artifacts
Artifact Pipeline
Every review deposits structured JSON artifacts into a working directory. The final step assembles all artifacts into a report and validates consistency. This is not optional.
| Step | Artifact | Producer |
|---|---|---|
| 1 | founder context | founder_context.py read/init |
| 2 | deck_inventory.json | deck_inventory.py (agent provides JSON via stdin) |
| 3 | stage_profile.json | stage_profile.py (agent provides JSON via stdin) |
| 4 | slide_reviews.json | slide_reviews.py (agent provides JSON via stdin) |
| 5 | checklist.json | checklist.py |
| 6 | Report | compose_report.py (writes both report.json and report.md) |
Rules:
- Deposit each artifact before proceeding to the next step
- For producer-script artifacts (Steps 2-4), the agent supplies JSON on stdin and the script schema-validates against
references/schemas/<artifact>.schema.json. Never write artifacts directly viaWriteorEdit— always pipe through the producer script sometadata.run_idis injected and the schema is enforced. - If a step is not applicable, deposit a stub:
{"skipped": true, "reason": "..."}
Keep the founder informed with brief, plain-language updates at each step. Never mention file names, scripts, or JSON. After each analytical step (4–5), share a one-sentence finding before moving on.
Workflow
Step 0: Path Setup
SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/deck-review/scripts"
REFS="${CLAUDE_PLUGIN_ROOT}/skills/deck-review/references"
SHARED_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"
ARTIFACTS_ROOT="${ARTIFACTS_ROOT:-$(pwd)/artifacts}"
mkdir -p "$ARTIFACTS_ROOT"
# Preliminary RUN_ID — used by Step 1 (founder_context init) before slug-aware
# setup_run.py runs. Will be reused by setup_run via --run-id, OR overwritten
# by gate_state.json on re-invocation (see below).
RUN_ID="${RUN_ID:-$(date -u +%Y%m%dT%H%M%SZ)}"
If CLAUDE_PLUGIN_ROOT is empty, fall back: Glob for **/founder-skills/skills/deck-review/scripts/checklist.py, strip to get SCRIPTS, derive REFS and SHARED_SCRIPTS.
After Step 1 (when the slug is known) — call setup_run.py to resolve REVIEW_DIR and clean stale state in one atomic step. Re-invocation special case: if the caller's task prompt indicated this is a resume (it includes REVIEW_DIR=... and / or RUN_ID=..., or $REVIEW_DIR/gate_state.json already exists with a non-empty answer), rehydrate RUN_ID from gate_state.json's metadata.run_id and skip the --clean flag:
# Resolve REVIEW_DIR (from prompt if provided, else derive)
if [ -z "$REVIEW_DIR" ]; then
REVIEW_DIR="$ARTIFACTS_ROOT/deck-review-$SLUG"
fi
mkdir -p "$REVIEW_DIR"
mkdir -p "$REVIEW_DIR/.staging" # for ad-hoc sub-agent JSON staging (v0.4.2)
IS_RESUMING=""
if [ -f "$REVIEW_DIR/gate_state.json" ]; then
GATE_ANSWER="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("answer",""))' "$REVIEW_DIR/gate_state.json")"
if [ -n "$GATE_ANSWER" ]; then
IS_RESUMING=1
RUN_ID="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("metadata",{}).get("run_id",""))' "$REVIEW_DIR/gate_state.json")"
fi
fi
if [ -z "$IS_RESUMING" ]; then
SETUP_JSON="$(python3 "$SCRIPTS/setup_run.py" \
--artifacts-root "$ARTIFACTS_ROOT" \
--slug "$SLUG" \
--run-id "$RUN_ID" \
--clean \
--pretty)"
REVIEW_DIR="$(echo "$SETUP_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["review_dir"])')"
# RUN_ID stays the preliminary value passed via --run-id; setup_run echoes it back.
fi
Pass RUN_ID to every producer script via --run-id. Producer scripts inject it into metadata.run_id automatically. compose_report.py enforces that all required artifacts share the same run_id and emits a MISSING_METADATA (high) warning for any artifact without one. **The rehydration