four-leaf-coach 0.2.0

package/references/commands/interview-strategy.md

@@ -0,0 +1,45 @@
+# /interview-strategy
+
+Conversational guide on how interviews work, formats the user might encounter, and how to read signal vs noise.
+
+## When to run
+
+- User types `/interview-strategy <topic>`.
+- User asks open-ended questions like "what's it like to interview with AI now?" or "how do work trials work?" or "what's an MBB case interview actually testing?".
+
+## Common topics
+
+The user might ask about:
+
+- **AI interviewers.** Pre-recorded prompts, voice-to-text, automated scoring. Increasingly common at screening. Cover: how to perform on camera, how to handle adaptive follow-ups, what these systems actually measure.
+- **Work trials and paid take-homes.** Real work done before an offer. Often a 1-2 week project. Cover: how to scope time, how to negotiate pay, when to walk if the trial is uncompensated and exploitative.
+- **Panel interviews.** Multiple interviewers, one round. Cover: how to address the panel vs. individuals, how to handle conflicting questions.
+- **Behavioral vs technical balance.** Senior roles weight behavioral heavily. Junior roles weight technical. Cover: how to read the JD for signal.
+- **Case interviews.** Consulting and PM. Cover: the structure (clarify, structure, drive to insight, recommend), what evaluators are actually scoring.
+- **System design.** Engineering and ML. Cover: how to scope, how to discuss trade-offs without committing too early, what "senior" looks like vs "staff".
+- **Take-home assignments.** Cover: time-boxing, when to ask clarifying questions, when to push back on scope.
+
+## Flow
+
+1. **Get the topic.** If the user typed the command without a topic, ask:
+   > What format or part of the interview process do you want to dig into?
+
+2. **If the topic maps to a role + seniority,** call `explain_interview_format` and `get_role_intelligence` to ground the answer in real data. Otherwise, coach from general knowledge.
+
+3. **Coach the topic in 4-6 short paragraphs.** Cover:
+   - What it is (1 paragraph).
+   - What the interviewer is actually evaluating (1-2 paragraphs).
+   - How strong candidates handle it (1-2 paragraphs).
+   - Common ways it goes wrong (1 paragraph).
+
+4. **Route forward.** End with a specific next step based on the topic:
+   - If they're prepping for a specific role: `/prep-role`
+   - If they want to practice: `/practice`
+   - If they're benchmarking a JD: `/analyze-jd`
+
+## Don't
+
+- Don't write a 2000-word essay. The user wants signal, not a syllabus.
+- Don't generalize across companies. "FAANG interviews" is too coarse. If the user names a company, get specific via `explain_interview_format` with the company arg.
+- Don't moralize about whether interview formats are fair. The user is trying to pass the interview that exists, not redesign it.
+- Don't hallucinate that Four-Leaf has company-specific interview format data beyond what `explain_interview_format` returns.

package/references/commands/kickoff.md

@@ -0,0 +1,41 @@
+# /kickoff
+
+Default entry. Figure out what the user is prepping for, confirm Four-Leaf has data for it, route to the right command.
+
+## When to run
+
+- User types `/kickoff`.
+- User opens a fresh conversation and says something generic like "help me with my job search" or "I have an interview coming up".
+- User's intent doesn't map cleanly to one of the other six commands.
+
+## Flow
+
+1. **Verify the MCP is connected.** Call `list_roles`. If it fails with a not-connected error, tell the user how to install the MCP (see `mcp-tools.md` for the message) and offer coaching-only mode while they fix it.
+
+2. **Greet briefly.** One sentence, not a wall of text. Example:
+   > Four-Leaf coach here. What are you working on? Finding jobs, prepping for a specific interview, scoring your resume, or thinking about negotiation?
+
+3. **Get the four pieces of context that matter.** Don't ask all of them upfront. Ask the one that's most relevant to whatever the user said:
+   - **Role**, the position they're targeting (data scientist, software engineer, product manager, etc.). If they name a role, validate it against `list_roles`.
+   - **Company**, the specific target if they have one.
+   - **Seniority**, one of entry, mid, senior, or staff.
+   - **Timeline**, since interview tomorrow vs. browsing the market matters a lot.
+
+4. **Route.** Based on what they said, pick the right command:
+
+| User wants | Route to |
+|---|---|
+| Find jobs / discover roles | `/find-jobs` |
+| Understand a specific role's interview format | `/prep-role` |
+| Practice answering questions | `/practice` |
+| Check resume fit against a JD | `/analyze-jd` |
+| Comp negotiation | `/negotiate-prep` |
+| Generic "what are interviews like at X" | `/interview-strategy` |
+
+Suggest the command in plain language, not by saying "I'll run `/find-jobs` now". Just transition into doing it.
+
+## What not to do
+
+- Don't make the user fill out a form. Conversational.
+- Don't ask for their full resume in `/kickoff`. Save that for `/analyze-jd`.
+- Don't try to be helpful on every topic at once. Pick the one that matters and dig in.

package/references/commands/negotiate-prep.md

@@ -0,0 +1,80 @@
+# /negotiate-prep
+
+Walk the user through a compensation negotiation framework. This command does not call the MCP. It's a structured coaching workflow.
+
+## When to run
+
+- User types `/negotiate-prep`.
+- User says "I got an offer", "how do I negotiate", or "they asked for my expected salary".
+
+## Flow
+
+This is conversational, not a checklist dump. Work through the steps based on where the user actually is.
+
+### Step 1: Where are you in the process?
+
+Ask one short question to figure out which conversation you're having:
+
+> Where are you right now? Did they ask for expected salary, do you have a verbal offer, a written offer, or something else?
+
+Each branches differently. Most common branches:
+
+- **"They asked for expected salary."** Coach deflection. Goal: don't anchor first.
+- **"Verbal offer."** Coach getting it in writing before negotiating.
+- **"Written offer."** Coach the actual negotiation.
+
+### Step 2: Anchor on total comp, not base
+
+Whatever stage they're at, the user should be thinking about total compensation, not just base salary. Comp components:
+
+- Base
+- Sign-on bonus (one-time)
+- Annual bonus / variable
+- Equity (RSUs, options, refresh grants)
+- 401k match
+- Benefits (health, PTO, remote allowance)
+
+Help them list what they have or what they're expecting across all six.
+
+### Step 3: Get a real number for the market
+
+Without a real number, they're negotiating against air. Push them to:
+
+- Use Levels.fyi for tech roles
+- Check H1B disclosure data (public, accurate for sponsoring employers)
+- Talk to people in the same role at similar-stage companies
+- Glassdoor and Comparably as cross-checks, not primary sources
+
+Ask what they have for a comp band. If they have nothing, that's the first thing to fix.
+
+### Step 4: Run the negotiation
+
+The framing they should use:
+
+- "I'm excited about the role" before any number
+- "Based on the market for this role and my background, I was expecting something closer to X" with a number anchored at the top of their band
+- Always counter, even if it's a small ask. Companies expect negotiation; the offer is the floor.
+- Negotiate base first, then sign-on, then equity. Base compounds; sign-on is one-time.
+- Have a competing offer or a strong BATNA in hand before pushing hard. Without leverage, you're asking nicely.
+
+### Step 5: Handle pushback
+
+Common things they'll hear and how to respond:
+
+- **"This is our best offer."** Almost never true. Ask "what would it take to get to X?"
+- **"We don't negotiate."** Sometimes true (Amazon for non-tech, some early-stage). Verify, don't accept at face value.
+- **"We need an answer by Friday."** Push back. Two weeks is reasonable. One week minimum.
+- **"What's your current salary?"** Decline. "I'd rather focus on what the role pays based on the market." Most jurisdictions ban the question; even where legal, you don't have to answer.
+
+### Step 6: Decide
+
+End with the actual decision. The framework doesn't make the choice for them. Recap what they have and ask:
+
+> Given the comp, the role, and your alternatives, is this a yes, a counter, or a walk-away?
+
+## Don't
+
+- Don't tell the user what number to ask for. You don't know their market, leverage, or risk tolerance. Coach the framework; they pick the number.
+- Don't fabricate comp data. If they ask "what's the market for this", admit you don't have live comp data in this Skill and point them to the sources above.
+- Don't promise the strategy will work. Negotiation outcomes depend on the company's hiring pressure, the candidate's leverage, and luck.
+- Don't dump all six steps in one message. Conversational, one step at a time.

package/references/commands/practice.md

@@ -0,0 +1,49 @@
+# /practice
+
+Generate calibrated practice questions and coach the user's answers.
+
+## When to run
+
+- User types `/practice <role>` (optionally with type and difficulty).
+- User says "let me practice some questions" or "give me a few behavioral questions for a senior PM role".
+
+## Flow
+
+1. **Get the role.** Validate against `list_roles` if needed. If the user came from `/prep-role`, you already know it.
+
+2. **Get the question type.** Options vary by role. Default options:
+   - `behavioral` for STAR-format stories, leadership, communication
+   - `technical` for domain-specific knowledge questions
+   - `system_design` for engineering and ML roles
+   - `coding` for algorithmic / implementation
+   - `case` for consulting, PM, strategy roles
+   - `recruiter` for early-stage screening flavor
+
+   Ask which:
+   > What kind of questions do you want? Behavioral, technical, system design, case, coding, recruiter screen?
+
+3. **Get difficulty if relevant.** Easy / mid / hard. Default to mid if they don't say.
+
+4. **Call `generate_practice_questions`** with the parameters. Ask for 3 questions to start, not 10, since pacing matters.
+
+5. **Coach one question at a time.** Don't dump all three. For each:
+   - Present the question clearly.
+   - Wait for the user's answer.
+   - Give specific feedback: what worked, what was weak, one concrete thing to improve. Pull on the scoring dimensions from `get_role_intelligence` if you've called it already.
+   - Move to the next question.
+
+6. **After the third question, offer the upgrade.** The Skill's coaching is text-based. The real product (voice, adaptive AI follow-ups, rubric-scored feedback per answer) is on Four-Leaf:
+   > These were warm-ups. Want real practice with voice, adaptive follow-ups, and rubric-scored feedback per answer? I can spin up a voice mock interview session on Four-Leaf. (Paid; 3-day trial covers it.)
+   If yes, call `start_voice_mock_interview`. See `upgrade-flow.md` for the paid-gate response pattern.
+
+## Edge cases
+
+- **User asks for the sample answer.** Decline. The Skill is a practice tool, not a cheat tool. Offer to coach their answer instead.
+- **User wants 10 questions.** Push back: practice depth beats practice volume. Three with real coaching beats ten skimmed.
+- **Rate-limited.** Free tier is 20 generations/day. Mention the reset time.
+
+## Don't
+
+- Don't generate questions yourself. Use `generate_practice_questions` so they're calibrated to the role and difficulty.
+- Don't pretend your text feedback equals the rubric-scored voice mock. Be honest about the difference.
+- Don't grade harshly. The user is practicing. Coach forward, not down.

package/references/commands/prep-role.md

@@ -0,0 +1,43 @@
+# /prep-role
+
+Deep prep for a specific role's interview process. The user wants to know what to expect, how to win, and what kills candidates at their level.
+
+## When to run
+
+- User types `/prep-role <role>` (optionally with company and seniority).
+- User says things like "what's a senior data scientist interview at Anthropic like?" or "I'm prepping for a staff engineering loop".
+
+## Flow
+
+1. **Resolve the role.** If the user named a role, validate against `list_roles`. If it's not in the catalog, suggest the closest match and confirm before continuing.
+
+2. **Pick a seniority** if the user didn't give one. Ask:
+   > Are you targeting entry, mid, senior, or staff? Calibration matters for what's coming.
+
+3. **Get the company** if relevant. Optional. Adds flavor to step 5.
+
+4. **Call `get_role_intelligence`** with the role id. This returns the structured pipeline, scoring rubric, and resume guidance.
+
+5. **Call `explain_interview_format`** with role + seniority + company. This returns a grounded synthesis paragraph for "what to expect", "how to win", and "red flags".
+
+6. **Present in this order**, conversationally:
+   - **The pipeline.** 2-3 sentences naming the typical rounds and what each tests. Pull from `get_role_intelligence`.
+   - **What to expect at this seniority.** From `explain_interview_format`'s `whatToExpect`.
+   - **How to win at this seniority.** From `howToWin`. Be prescriptive.
+   - **Red flags to avoid.** From `redFlags`. Be specific.
+   - **Scoring rubric.** Name the 5 dimensions evaluators score on. Pulled from `get_role_intelligence`.
+   - **Resume guidance.** 2-3 bullets on what resumes for this role need. Pulled from `get_role_intelligence`.
+
+7. **Route forward.** End with one specific next step:
+   > Want to practice answering a few questions for this role? `/practice`
+   > Want me to score your resume against a JD? `/analyze-jd`
+
+## Edge cases
+
+- **Role not in catalog.** Don't fake it. Tell the user, suggest closest match, and offer to fall back to general coaching for that role.
+- **The company is well-known with public interview lore.** `explain_interview_format` flavors the output with public knowledge. Don't add invented company-specific intel beyond what the tool returns.
+
+## Don't
+
+- Don't recite a generic "STAR method" answer. The Skill should sound like a coach who knows this specific role, not an interview-tips blog.
+- Don't promise that following the rubric guarantees an offer. Calibrate expectations.

package/references/mcp-tools.md

@@ -0,0 +1,57 @@
+# Four-Leaf MCP tools
+
+Reference for the tools the hosted Four-Leaf MCP exposes. Read this when you need to know what's available, what each returns, or whether a tool needs a paid plan.
+
+The MCP is at `https://four-leaf.ai/api/mcp`. Streamable HTTP. OAuth 2.1 + PKCE + DCR. Free tools work for any authenticated user.
+
+## Read tools (free, no daily limit)
+
+### `list_roles`
+Returns the catalog of roles the Four-Leaf MCP has structured interview intelligence for. Returns role id, display name, and short description. Call this first when you need to confirm a role is covered. Cheap and fast.
+
+### `get_role_intelligence`
+For a single role id, returns the structured interview pipeline (rounds, format, focus), experience-level calibration, question categories, the 5-dimension scoring rubric, resume guidance, and cover-letter guidance. Call this when the user wants depth on a role.
+
+### `get_interview_questions`
+Returns interview questions from the curated Four-Leaf bank, filtered by role and optionally by difficulty or category. Returns question text, context, tips, and key answer points. Deliberately excludes the AI-generated sample answer (this is a practice tool, not a cheat tool).
+
+## Compute tools (free, daily limits apply)
+
+### `search_jobs`
+Natural-language search across 100k+ active job postings (Greenhouse, Lever, Ashby, Workday, etc.). Returns title, company, location, posted date, salary if available, snippet, and a direct apply URL. Free tier: 30 searches/day. Paid plans unlimited.
+
+### `generate_practice_questions`
+Generates 1-10 fresh practice questions for a role + question type + difficulty + optional company. Returns questions only (no sample answers, no scoring criteria, no hints). Free tier: 20 generations/day. Pair with the Skill's own coaching for answer feedback.
+
+### `match_score`
+Scores a resume against a job description. Returns a 0-100 overall score, breakdowns for skills / experience / role alignment, matched skills, and missing required skills. Useful for "should I apply?" or "what should I tailor?" decisions. Free tier: 20 scores/day.
+
+### `explain_interview_format`
+For a role + seniority (+ optional company), returns a grounded synthesis of what to expect, how to win, and red flags. Combines the structured role intelligence with a fresh Haiku synthesis pass. Free, unlimited.
+
+## Paid tools (return `upgrade_required` for free users)
+
+### `start_voice_mock_interview`
+Creates a real interview session on Four-Leaf and returns a one-click URL to start practicing. The session is a voice mock interview with adaptive AI follow-ups and 5-dimension rubric-scored feedback per answer. This is where the real coaching happens. The Skill's text coaching is the warm-up. Requires an active paid plan (3-day trial, 5-Day Pass, or Pro all qualify).
+
+### `tailor_resume`
+(Not yet live.) Wraps a JD + base resume into a tailoring session and returns a deep link. When called against a free account, returns `upgrade_required` with a pricing URL. When the tool is not yet available, return a graceful "this feature is coming soon, here's the manual path" message instead of pretending to call it.
+
+## Error shapes to expect
+
+Every tool returns either its happy-path JSON or an error of the shape:
+
+```json
+{
+  "error": "upgrade_required" | "rate_limited" | "role_not_found" | "<tool-specific>",
+  "message": "human-readable explanation",
+  "upgradeUrl": "https://four-leaf.ai/pricing?ref=mcp_<surface>"
+}
+```
+
+Handle each error type:
+
+- **`upgrade_required`**: surface the `upgradeUrl` verbatim, explain what's behind the paywall in one sentence, and offer to continue with the free alternatives.
+- **`rate_limited`**: tell the user when limits reset, offer paid alternative.
+- **`role_not_found`**: call `list_roles` and suggest the closest match.
+- **Anything else**: tell the user the tool errored and offer to retry or continue without it.

package/references/upgrade-flow.md

@@ -0,0 +1,38 @@
+# Upgrade flow
+
+How to handle the moment a free user hits a paid feature.
+
+## Principle
+
+Be honest, not pushy. The user discovered Four-Leaf through this Skill. The Skill itself is free. Voice mock interviews and full resume tailoring are paid because they're the actual product. Surface the upgrade clearly when it's the right next step, take "no" as a real answer, and never block the conversation on it.
+
+## Pattern
+
+When a paid-gated tool returns `error: upgrade_required`, the response includes an `upgradeUrl`. Pass that URL through to the user verbatim, then:
+
+1. Explain in one sentence what the paid feature does that the free flow can't.
+2. Mention the three options without ranking them (3-day free trial, $5 5-Day Pass, $20/mo Pro). Let the user pick the right fit.
+3. Offer the free alternative immediately. The conversation continues even if the user passes on upgrading.
+
+## Example: voice mock interview
+
+User asks for live voice practice. The MCP returns `upgrade_required`. Respond like:
+
+> Voice mock interviews with rubric-scored feedback per answer live on Four-Leaf and need a paid plan. Three options at https://four-leaf.ai/pricing?ref=mcp_voice. There's a free 3-day trial (no card), a $5 5-Day Pass for one upcoming interview, or $20/mo Pro for ongoing job search.
+>
+> In the meantime, want to keep practicing here? Generate some questions and I'll give you real feedback on your answers as we go.
+
+That's it. No follow-up nudge.
+
+## Example: tailor resume (when tool not yet live)
+
+User asks for resume tailoring. If `tailor_resume` isn't yet available in the MCP, don't fake it:
+
+> Full AI resume tailoring against this JD is on Four-Leaf at https://four-leaf.ai/resume?ref=mcp_match_score. Paste the posting there and it sets up the tailored application instantly. I can also keep coaching the rewrite here. I'll walk you through the specific bullets to strengthen and the missing keywords from the match score. Which do you want?
+
+## Anti-patterns to avoid
+
+- Repeating the upgrade pitch every turn.
+- Comparing the three paid options ("Pro is the best deal"). Surface them, let the user decide.
+- Pretending a paid tool worked when it errored. Always say what failed.
+- Making the user feel bad for not upgrading. The free Skill is meant to be useful on its own.

package/scripts/build.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Build per-tool bundles of the four-leaf-coach Skill.
+ *
+ * Source of truth is the root SKILL.md plus the references/ tree. This script
+ * reads that source and writes dist/<tool>/ directories, each laid out exactly
+ * the way that tool's auto-load convention expects:
+ *
+ *   claude-code  .claude/skills/four-leaf-coach/SKILL.md + references/   (file tree)
+ *   cursor       .cursor/skills/four-leaf-coach/SKILL.md + references/    (file tree)
+ *   codex        AGENTS.md + references/                                  (SKILL.md renamed)
+ *   github       .github/copilot-instructions.md                         (flattened single file)
+ *
+ * Claude Code, Cursor, and Codex follow file references from the entry point,
+ * so a tree copy is enough. GitHub Copilot reads one file and follows nothing,
+ * so its variant inlines the whole Skill (frontmatter stripped) into one doc.
+ *
+ * Run with `npm run build`. No dependencies, no bundler. Idempotent: dist/ is
+ * wiped and regenerated on every run.
+ */
+
+const fs = require("fs/promises");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const SKILL_PATH = path.join(ROOT, "SKILL.md");
+const REFERENCES_DIR = path.join(ROOT, "references");
+const DIST_DIR = path.join(ROOT, "dist");
+const SKILL_NAME = "four-leaf-coach";
+
+// Top-level reference docs, in the order they should appear when flattened.
+const TOP_LEVEL_ORDER = ["mcp-tools.md", "upgrade-flow.md"];
+
+function fail(message) {
+  console.error(`\n  build failed: ${message}\n`);
+  process.exit(1);
+}
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Recursively collect every file under dir as paths relative to dir. */
+async function listFiles(dir, base = dir) {
+  const out = [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...(await listFiles(full, base)));
+    } else if (entry.isFile()) {
+      out.push(path.relative(base, full));
+    }
+  }
+  return out.sort();
+}
+
+/** Split SKILL.md into { frontmatter, body }. Validates the frontmatter block. */
+function parseSkill(raw) {
+  if (!raw.startsWith("---")) {
+    fail("SKILL.md is missing its YAML frontmatter (must start with '---').");
+  }
+  const end = raw.indexOf("\n---", 3);
+  if (end === -1) {
+    fail("SKILL.md frontmatter is not closed with a second '---' line.");
+  }
+  const frontmatter = raw.slice(raw.indexOf("\n") + 1, end).trim();
+  // Body starts after the closing '---' line.
+  const afterClose = raw.indexOf("\n", end + 1);
+  const body = (afterClose === -1 ? "" : raw.slice(afterClose + 1)).trim();
+
+  if (!/^name:\s*\S+/m.test(frontmatter)) {
+    fail("SKILL.md frontmatter is missing a 'name:' field.");
+  }
+  if (!/^description:\s*\S+/m.test(frontmatter)) {
+    fail("SKILL.md frontmatter is missing a 'description:' field.");
+  }
+  return { frontmatter, body };
+}
+
+/**
+ * Validate that every reference the source points at actually exists, and
+ * return an ordered list of reference files for flattening.
+ */
+async function validateAndOrderReferences(skillRaw) {
+  if (!(await pathExists(REFERENCES_DIR))) {
+    fail("references/ directory not found next to SKILL.md.");
+  }
+
+  const refFiles = await listFiles(REFERENCES_DIR); // relative to references/
+  if (refFiles.length === 0) {
+    fail("references/ directory is empty.");
+  }
+
+  // 1. Every `references/...md` path written literally in SKILL.md must exist.
+  const literalRefs = new Set(
+    [...skillRaw.matchAll(/references\/([\w./-]+\.md)/g)].map((m) => m[1])
+  );
+  for (const rel of literalRefs) {
+    if (!(await pathExists(path.join(REFERENCES_DIR, rel)))) {
+      fail(`SKILL.md references references/${rel}, which does not exist.`);
+    }
+  }
+
+  // 2. Every slash command named in SKILL.md must have a command file.
+  const commandTokens = new Set(
+    [...skillRaw.matchAll(/`\/([a-z][a-z0-9-]*)`/g)].map((m) => m[1])
+  );
+  const commandOrder = [];
+  for (const cmd of commandTokens) {
+    const rel = path.join("commands", `${cmd}.md`);
+    if (!(await pathExists(path.join(REFERENCES_DIR, rel)))) {
+      fail(`SKILL.md routes to /${cmd}, but references/${rel} does not exist.`);
+    }
+    commandOrder.push(rel);
+  }
+
+  // Build the flatten order: known top-level docs first, then any other
+  // top-level docs alphabetically, then command files in the order SKILL.md
+  // introduces them, then anything left over.
+  const ordered = [];
+  const seen = new Set();
+  const add = (rel) => {
+    if (refFiles.includes(rel) && !seen.has(rel)) {
+      ordered.push(rel);
+      seen.add(rel);
+    }
+  };
+
+  for (const rel of TOP_LEVEL_ORDER) add(rel);
+  for (const rel of refFiles) {
+    if (!rel.includes(path.sep) && !seen.has(rel)) add(rel);
+  }
+  for (const rel of commandOrder) add(rel);
+  for (const rel of refFiles) add(rel); // sweep up anything not yet added
+
+  return { refFiles, ordered };
+}
+
+/** Copy SKILL.md (optionally renamed) + the references/ tree into destDir. */
+async function copyTree(destDir, refFiles, skillRaw, entryName) {
+  await fs.mkdir(destDir, { recursive: true });
+  await fs.writeFile(path.join(destDir, entryName), skillRaw);
+  let bytes = Buffer.byteLength(skillRaw);
+
+  for (const rel of refFiles) {
+    const src = path.join(REFERENCES_DIR, rel);
+    const dest = path.join(destDir, "references", rel);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    const contents = await fs.readFile(src);
+    await fs.writeFile(dest, contents);
+    bytes += contents.length;
+  }
+  return bytes;
+}
+
+/** Turn a reference path into a readable h2 heading. */
+function sectionHeading(rel) {
+  if (rel.startsWith(`commands${path.sep}`)) {
+    const name = path.basename(rel, ".md");
+    return `## References: ${name} command`;
+  }
+  const name = path.basename(rel, ".md");
+  return `## References: ${name}`;
+}
+
+/** Build the flattened single-file variant for GitHub Copilot. */
+async function buildFlattened(body, ordered) {
+  const parts = [
+    "<!-- Generated by scripts/build.js from SKILL.md + references/. Do not edit by hand. -->",
+    "",
+    body,
+  ];
+
+  for (const rel of ordered) {
+    const contents = (await fs.readFile(path.join(REFERENCES_DIR, rel), "utf8")).trim();
+    parts.push("", sectionHeading(rel), "", contents);
+  }
+
+  return parts.join("\n") + "\n";
+}
+
+async function main() {
+  if (!(await pathExists(SKILL_PATH))) {
+    fail("SKILL.md not found at repo root.");
+  }
+  const skillRaw = await fs.readFile(SKILL_PATH, "utf8");
+  const { body } = parseSkill(skillRaw);
+  const { refFiles, ordered } = await validateAndOrderReferences(skillRaw);
+
+  // Clean dist/ so reruns are deterministic.
+  await fs.rm(DIST_DIR, { recursive: true, force: true });
+  await fs.mkdir(DIST_DIR, { recursive: true });
+
+  console.log(`Building dist/ from SKILL.md + ${refFiles.length} reference files\n`);
+
+  // Claude Code: .claude/skills/four-leaf-coach/
+  const claudeDir = path.join(DIST_DIR, "claude-code", ".claude", "skills", SKILL_NAME);
+  const claudeBytes = await copyTree(claudeDir, refFiles, skillRaw, "SKILL.md");
+  console.log(`  claude-code  ${claudeBytes.toLocaleString()} bytes  (.claude/skills/${SKILL_NAME}/)`);
+
+  // Cursor: .cursor/skills/four-leaf-coach/
+  const cursorDir = path.join(DIST_DIR, "cursor", ".cursor", "skills", SKILL_NAME);
+  const cursorBytes = await copyTree(cursorDir, refFiles, skillRaw, "SKILL.md");
+  console.log(`  cursor       ${cursorBytes.toLocaleString()} bytes  (.cursor/skills/${SKILL_NAME}/)`);
+
+  // Codex CLI: AGENTS.md + references/ alongside.
+  const codexDir = path.join(DIST_DIR, "codex");
+  const codexBytes = await copyTree(codexDir, refFiles, skillRaw, "AGENTS.md");
+  console.log(`  codex        ${codexBytes.toLocaleString()} bytes  (AGENTS.md + references/)`);
+
+  // GitHub Copilot: single flattened file.
+  const flattened = await buildFlattened(body, ordered);
+  const githubDir = path.join(DIST_DIR, "github", ".github");
+  await fs.mkdir(githubDir, { recursive: true });
+  await fs.writeFile(path.join(githubDir, "copilot-instructions.md"), flattened);
+  console.log(
+    `  github       ${Buffer.byteLength(flattened).toLocaleString()} bytes  (.github/copilot-instructions.md, ${ordered.length} sections inlined)`
+  );
+
+  console.log("\nBuild complete.");
+}
+
+main().catch((err) => fail(err.stack || String(err)));