@tamng0905/builder-essential-skills 0.1.0

package/.claude/agents/lead-builder.md

@@ -0,0 +1,55 @@
+---
+name: lead-builder
+description: Runs one techlead-loop builder job from a frozen slice spec, respecting job boundaries, worktree isolation, raw-only reporting, and never committing or pushing.
+tools: Glob, Read, Edit, Write, PowerShell, Bash, Grep
+disallowedTools: Bash(git commit *), Bash(git push *), PowerShell(git commit *), PowerShell(git push *)
+model: inherit
+isolation: worktree
+background: true
+---
+
+You are a techlead-loop builder. Your task is: execute exactly one job from the
+Lead's frozen slice spec.
+
+Operating rules:
+
+- PHASE 0 happens before code. Reply with your plan and every disagreement you
+  have with the spec, with reasons citing real files. Silent compliance is a
+  defect. If you have no disagreements, state what you checked.
+- Obey the job shape. `ship` may change only the files in BOUNDARIES; `scout`
+  writes only the requested report and may not modify code.
+- Build your job only. The Lead owns job splitting; files outside your BOUNDARIES
+  are out of scope even if they look related.
+- The files under `docs/checks/` are read-only at all times.
+- The files matching `docs/jobs/*-rulings.md` are also read-only — they are
+  Lead-owned, the same class as `docs/checks/`; creating or editing one fails the
+  job.
+- No placeholder implementations. Search before implementing and keep the
+  existing voice of touched files.
+- No silent fallbacks or success-shaped defaults; no unrequested
+  backwards-compatibility shims. Fail loudly, with context. Exception: only when
+  the spec explicitly requests them.
+- Run the job's check commands sequentially with temp/cache paths inside
+  `.lead/tmp/<purpose>`.
+- Write the job report exactly where requested — the convention is
+  `docs/jobs/<issue-slug>-01.md` — as the raw-evidence artifact: tables, command
+  output, exit codes, errors, and status claims backed by tool output from this
+  run.
+- End the report with exactly one status line:
+  `STATUS: COMPLETE | COMPLETE_WITH_CONCERNS (list them) | BLOCKED (exact blocker + what you tried)`.
+- Mirror duty: when the job's final STATUS is reached, post it plus a short
+  summary as a comment on the issue via `gh` when available. If the sandbox does
+  not allow `gh`/network, do not fake the post — write `MIRROR: LEAD` in the
+  report and let the Lead relay it.
+- Blocker behavior: if you hit a blocker, post `BLOCKED: <exact blocker> + what I
+  tried` on the issue (or record it in the report if `gh` is unavailable), then
+  EXIT. Never idle waiting for an answer — a blocker is a completion event.
+- Never commit, push, or mutate shared history. If git fails, record the exact
+  error and continue.
+- Your `tools:` order pads Bash and Read away from the first and last slot because
+  some harnesses drop those two positions at subagent spawn.
+- If Bash is absent at runtime (a desktop strip), run check commands via the
+  PowerShell tool instead and record which executor ran each command.
+
+Verdicts belong to the reviewer, the Lead, and the human. Persist until the job is
+complete or blocked by an exact, recorded blocker.

package/.claude/agents/lead-reviewer.md

@@ -0,0 +1,39 @@
+---
+name: lead-reviewer
+description: Runs frozen techlead-loop checks as a fresh read-only reviewer, verifies checks integrity and diff-vs-intent, and returns PASS/FAIL/INVALID verdicts with raw evidence only.
+tools: Glob, Read, PowerShell, Bash, Grep
+disallowedTools: Edit, Write, Bash(git add *), Bash(git commit *), Bash(git push *), Bash(git checkout *), Bash(git merge *), Bash(git rebase *), Bash(git reset *), Bash(git clean *), Bash(rm *), Bash(del *), Bash(Remove-Item *), PowerShell(git add *), PowerShell(git commit *), PowerShell(git push *), PowerShell(git checkout *), PowerShell(git merge *), PowerShell(git rebase *), PowerShell(git reset *), PowerShell(git clean *), PowerShell(rm *), PowerShell(del *), PowerShell(Remove-Item *)
+model: inherit
+---
+
+You are a techlead-loop reviewer. You inherit no builder context and no Lead
+discussion. Use only the fixed reviewer template supplied by the Lead.
+
+Duties:
+
+- Read the frozen check file named in the prompt.
+- Read `docs/jobs/<issue-slug>-rulings.md` when present. It is Lead-owned,
+  append-only, frozen post-freeze intent; read it alongside the frozen check
+  file, spec, and job report. If it is absent or empty, record that there are no
+  post-freeze rulings.
+- Check checks integrity with the freeze commit SHA and branch to review.
+- Run each check command exactly as written, unless it is impossible to execute
+  in this environment; then return INVALID with raw evidence.
+- Read the diff against the frozen spec intent. Tests passing is necessary, not
+  sufficient.
+- Return verdicts only: per-check PASS / FAIL / INVALID, checks-integrity
+  PASS / FAIL / INVALID, diff-vs-intent PASS / FAIL / INVALID, raw evidence, and a
+  slice verdict.
+- Post the verdict as an issue comment when `gh` is available; if `gh`/network is
+  unavailable, record that in the verdict evidence instead of faking the post.
+- Your `tools:` order pads Bash and Read away from the first and last slot with
+  read-only tools because some harnesses drop those two positions at subagent
+  spawn.
+- If Bash is absent at runtime, run check commands via the PowerShell tool
+  instead and record which executor ran each command.
+- Flag only gaps that affect correctness, the stated requirements, or documented
+  project invariants — cite file:line evidence for every finding. Do not report
+  stylistic preferences.
+
+Do not edit files, do not fix failures, do not stage changes, do not commit, and
+do not add advice beyond the requested verdict fields.

package/README.md

@@ -0,0 +1,276 @@
+<p align="center">
+  <img src="assets/readme-hero.png" alt="Builder's Essential Skills, shown as an original dark atelier of connected creative tools" width="100%">
+</p>
+<p align="center">
+  <strong>Builder's Essential Skills</strong><br>
+  A considered collection of reusable workflows for planning, building, researching, learning, validating, writing, and reviewing with Claude Code and Codex.
+</p>
+
+<p align="center">
+  <a href="#pick-a-skill">Pick a skill</a> ·
+  <a href="#get-started">Get started</a> ·
+  <a href="#bring-your-own-workflow">Create a skill</a>
+</p>
+
+## Pick a skill
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <a href="skills/lead/SKILL.md"><img src="assets/skill-cards/lead.svg" alt="lead — build and delivery skill" width="100%"></a>
+    </td>
+    <td width="50%" valign="top">
+      <a href="skills/lead-research/SKILL.md"><img src="assets/skill-cards/lead-research.svg" alt="lead-research — research and strategy skill" width="100%"></a>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <a href="skills/async-learning-teacher/SKILL.md"><img src="assets/skill-cards/async-learning-teacher.svg" alt="async-learning-teacher — learning skill" width="100%"></a>
+    </td>
+    <td width="50%" valign="top">
+      <a href="skills/validate-market/SKILL.md"><img src="assets/skill-cards/validate-market.svg" alt="validate-market — product and market skill" width="100%"></a>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <a href="skills/write-blog/SKILL.md"><img src="assets/skill-cards/write-blog.svg" alt="write-blog — writing and growth skill" width="100%"></a>
+    </td>
+    <td width="50%" valign="top">
+      <a href="skills/orwell-writing/SKILL.md"><img src="assets/skill-cards/orwell-writing.svg" alt="orwell-writing — direct writing skill" width="100%"></a>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <a href="skills/code-standards/SKILL.md"><img src="assets/skill-cards/code-standards.svg" alt="code-standards — engineering quality skill" width="100%"></a>
+    </td>
+    <td width="50%" valign="top">
+      <a href="skills/session-profiler/SKILL.md"><img src="assets/skill-cards/session-profiler.svg" alt="session-profiler — developer tools skill" width="100%"></a>
+    </td>
+  </tr>
+</table>
+
+Every skill lives in `skills/<name>/SKILL.md`. Some also ship scripts,
+reference material, or agent definitions that support the workflow.
+
+## Why this exists
+
+An AI agent is much more useful when it has a repeatable way to handle the
+work. This collection packages practical workflows as portable skills: compact
+instructions, scripts, references, and agent definitions that you can install,
+adapt, and share.
+
+Use the whole collection, or take only the skills your team needs.
+
+## Get started
+
+From the repository root, install every skill for the current user:
+
+```bash
+./install.sh
+```
+
+Once this repository is published to npm, install the collection from
+anywhere with:
+
+```bash
+npx @tamng0905/builder-essential-skills
+```
+
+To install into the repository you are currently in:
+
+```bash
+npx @tamng0905/builder-essential-skills --project
+```
+
+To install only one skill:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill lead
+```
+
+Add `--project` to that command to install the selected skill into the current
+repository.
+
+The `npx` command installs the same files as the scripts below. It supports
+macOS, Linux, and Windows wherever Node.js 18 or newer is available.
+
+On Windows:
+
+```powershell
+./install.ps1
+```
+
+Restart Claude Code or Codex, then invoke a skill in plain English:
+
+```text
+/lead Build the smallest version of this feature and open a PR.
+$async-learning-teacher Teach me this paper step by step: https://arxiv.org/abs/...
+```
+
+Want to try the collection inside one repository first? Install it locally
+instead:
+
+```bash
+./install.sh --project
+```
+
+```powershell
+./install.ps1 -Project
+```
+
+The project install uses `.claude/skills` and `.codex/skills`, so it stays
+with that repository rather than changing your user-level setup.
+
+## What gets installed
+
+The installers copy each folder in `skills/` to the right location for your
+agent and install the `lead` builder and reviewer agents for Claude Code.
+
+| Install mode | Claude Code | Codex |
+| --- | --- | --- |
+| User | `~/.claude/skills` | `${CODEX_HOME:-~/.codex}/skills` |
+| Current project | `.claude/skills` | `.codex/skills` |
+
+You will need Claude Code and/or Codex, depending on which agent you use.
+Python 3 is required for the `lead` routing helper and the
+`session-profiler` tools. The Codex CLI is optional, but `lead` can use it for
+builder jobs:
+
+```bash
+npm i -g @openai/codex@latest
+```
+
+## Go deeper
+
+### Route models for `lead`
+
+`lead` and `lead-research` can assign different models to roles such as
+lead, builder, reviewer, researcher, scout, and critic. Inspect the active
+routing before a run:
+
+```bash
+python skills/lead/config.py
+python skills/lead/config.py --role builder
+python skills/lead/config.py --check
+```
+
+Defaults live in `skills/lead/config.py` and `skills/lead/models.json`. Use
+`.lead/config` for a repository override or `~/.lead/config` for a personal
+default.
+
+### Profile an agent session
+
+After installation, point `SP` at the wrapper for your agent:
+
+```bash
+# Claude Code install
+SP="$HOME/.claude/skills/session-profiler/scripts/sp"
+
+# Codex install
+SP="${CODEX_HOME:-$HOME/.codex}/skills/session-profiler/scripts/sp"
+```
+
+Then explore your sessions:
+
+```bash
+$SP list --provider codex --n 20
+$SP info <session-id-or-jsonl-path>
+$SP parse <session-id-or-jsonl-path>
+$SP brief
+$SP agent-summary
+$SP costs
+$SP slowest-tools --n 20
+$SP errors
+$SP turns
+```
+
+Generate richer artifacts:
+
+```bash
+$SP toc
+$SP review
+$SP trace
+```
+
+`brief` writes a scan-friendly `brief.md` with headline metrics, standout slow
+paths or failures, a prompt trail or TOC storyline, and an agent scoreboard. The
+Perfetto trace adds an overview lane, labeled TOC phases, per-agent work lanes,
+prompt lanes, and cumulative token/cost counters.
+
+Cost reports are estimates based on public model pricing, not billing records.
+Session files and traces can include prompts, code, file paths, and other
+sensitive project context. Review them before sharing.
+
+## Repository map
+
+```text
+skills/                  The skill collection
+  <skill>/SKILL.md        Each skill's entry point and workflow
+assets/readme-hero.png    README banner
+.claude/agents/          Builder and reviewer agents for lead
+install.sh                macOS/Linux installer
+install.ps1               Windows installer
+package.json              npm package metadata and npx entrypoint
+bin/builder-essential-skills.js     cross-platform npx installer
+```
+
+### Publish the installer
+
+Choose an available npm package name in `package.json`, authenticate with npm,
+then publish from the repository root:
+
+```bash
+npm login
+npm publish --access public
+```
+
+npm requires either 2FA enabled on the account, followed by the one-time code
+requested by `npm publish`, or a granular access token with read/write access
+and **Bypass two-factor authentication** enabled. For a local interactive
+publish, enabling 2FA and running `npm login` again is the simplest option.
+Never commit an access token; use npm's login flow or a secure CI secret.
+
+After publishing, users can run `npx @tamng0905/builder-essential-skills` without cloning the
+repository. Bump the version in `package.json` for each subsequent publish.
+
+## Bring your own workflow
+
+Start with one folder:
+
+```text
+skills/my-skill/
+  SKILL.md
+```
+
+Give `SKILL.md` clear frontmatter and a focused workflow:
+
+```markdown
+---
+name: my-skill
+description: Explain when an agent should use this skill.
+---
+
+# My Skill
+
+Write the workflow, rules, examples, and expected output here.
+```
+
+Keep skills easy to move between projects:
+
+- Avoid hard-coding a company, repository, branch, or tool unless the skill is intentionally private.
+- Put reusable scripts beside the skill instead of relying on global shell state.
+- Include request examples that show exactly when the skill should run.
+- Create `assets/skill-cards/<name>.svg` for each new skill and add it to the
+  README's "Pick a skill" table.
+- Never put credentials, tokens, or private data in a skill folder.
+
+Re-run the installer after adding or changing a skill:
+
+```bash
+./install.sh
+```
+
+## License
+
+Add the license that matches how you want others to use this collection before
+publishing it broadly.

package/assets/skill-cards/async-learning-teacher.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">async-learning-teacher skill card</title><desc id="desc">A Builder's Essential Skill for turning materials into clear learning.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#181519"/><stop offset="1" stop-color="#0b0b10"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#0b0a0d"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#765d84" stroke-opacity=".6"/><circle cx="966" cy="164" r="120" fill="#9875b5" fill-opacity=".2" filter="url(#glow)"/><path d="M78 532C275 532 359 204 608 204s278 264 516 264" fill="none" stroke="#b292d4" stroke-opacity=".72" stroke-width="3"/>
+  <text x="78" y="106" fill="#c7b2d3" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 03</text><text x="78" y="204" fill="#f5eff7" font-family="Arial, Helvetica, sans-serif" font-size="55" font-weight="700">async-learning-teacher</text><text x="80" y="258" fill="#cbc4cf" font-family="Arial, Helvetica, sans-serif" font-size="28">Turn dense material into a paced lesson, study guide,</text><text x="80" y="296" fill="#cbc4cf" font-family="Arial, Helvetica, sans-serif" font-size="28">or interactive tutoring session.</text>
+  <g transform="translate(848 112)" fill="none" stroke="#c0a0dc" stroke-width="5"><path d="M12 38q80-30 160 0v126q-80-30-160 0zM92 24v144"/><path d="M38 76h40M38 104h40M106 76h40M106 104h40"/></g><rect x="78" y="376" width="1044" height="1" fill="#b79bc3" fill-opacity=".35"/><text x="78" y="432" fill="#b99cc5" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#f3edf6" font-family="Arial, Helvetica, sans-serif" font-size="29">Learning</text><text x="520" y="432" fill="#b99cc5" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#f3edf6" font-family="Arial, Helvetica, sans-serif" font-size="29">Understanding that stays with you</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#1a1620" stroke="#765a82"/><text x="104" y="596" fill="#dfc9ef" font-family="monospace" font-size="19">$async-learning-teacher Teach me this paper.</text><circle cx="1058" cy="586" r="30" fill="#a884bd"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#1a1020" stroke-width="5"/>
+</svg>

package/assets/skill-cards/code-standards.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">code-standards skill card</title><desc id="desc">A Builder's Essential Skill for disciplined engineering changes.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#11161d"/><stop offset="1" stop-color="#080b10"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#080a0d"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#536f8a" stroke-opacity=".65"/><circle cx="971" cy="164" r="118" fill="#587daa" fill-opacity=".18" filter="url(#glow)"/><path d="M72 540C294 540 358 194 618 194s269 286 506 286" fill="none" stroke="#72a1cf" stroke-opacity=".76" stroke-width="3"/>
+  <text x="78" y="106" fill="#a7c2d8" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 07</text><text x="78" y="204" fill="#ecf4fa" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">code-standards</text><text x="80" y="258" fill="#c1cbd3" font-family="Arial, Helvetica, sans-serif" font-size="28">Keep an engineering change focused: understand the code,</text><text x="80" y="296" fill="#c1cbd3" font-family="Arial, Helvetica, sans-serif" font-size="28">make the smallest change, then prove it.</text>
+  <g transform="translate(849 112)" fill="none" stroke="#83b3df" stroke-width="5"><path d="M55 29 10 92l45 63M125 29l45 63-45 63M73 166h54"/><path d="m83 92 17 17 35-41"/></g><rect x="78" y="376" width="1044" height="1" fill="#96b2c9" fill-opacity=".35"/><text x="78" y="432" fill="#9ebad0" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#edf5fb" font-family="Arial, Helvetica, sans-serif" font-size="29">Engineering quality</text><text x="520" y="432" fill="#9ebad0" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#edf5fb" font-family="Arial, Helvetica, sans-serif" font-size="29">A reviewable change with proof</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#101924" stroke="#4e718e"/><text x="104" y="596" fill="#c6ddf0" font-family="monospace" font-size="17">$code-standards Fix this bug using the project workflow.</text><circle cx="1058" cy="586" r="30" fill="#6393c0"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#091521" stroke-width="5"/>
+</svg>

package/assets/skill-cards/lead-research.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">lead-research skill card</title><desc id="desc">A Builder's Essential Skill for source-grounded strategic research.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#121719"/><stop offset="1" stop-color="#080b0c"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#080a0b"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#587276" stroke-opacity=".55"/><circle cx="976" cy="166" r="118" fill="#5a9b94" fill-opacity=".18" filter="url(#glow)"/><path d="M74 540C305 540 350 182 620 182s277 294 504 294" fill="none" stroke="#78b4aa" stroke-opacity=".74" stroke-width="3"/>
+  <text x="78" y="106" fill="#a9c1bc" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 02</text><text x="78" y="204" fill="#eff6f1" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">lead-research</text><text x="80" y="258" fill="#c1cac6" font-family="Arial, Helvetica, sans-serif" font-size="28">Map a decision, investigate the field, and make</text><text x="80" y="296" fill="#c1cac6" font-family="Arial, Helvetica, sans-serif" font-size="28">a source-grounded recommendation.</text>
+  <g transform="translate(848 116)" fill="none" stroke="#83c1b6" stroke-width="5"><circle cx="93" cy="93" r="64"/><path d="m140 140 52 52M93 45v96M45 93h96"/><circle cx="93" cy="93" r="10" fill="#83c1b6"/></g><rect x="78" y="376" width="1044" height="1" fill="#90b2a8" fill-opacity=".35"/><text x="78" y="432" fill="#89ada3" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#edf5ef" font-family="Arial, Helvetica, sans-serif" font-size="29">Research &amp; strategy</text><text x="520" y="432" fill="#89ada3" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#edf5ef" font-family="Arial, Helvetica, sans-serif" font-size="29">Evidence you can act on</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#131a1a" stroke="#50766d"/><text x="104" y="596" fill="#bfe0d6" font-family="monospace" font-size="20">/lead-research Research the best approach.</text><circle cx="1058" cy="586" r="30" fill="#6ca99d"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#0d1715" stroke-width="5"/>
+</svg>

package/assets/skill-cards/lead.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">lead skill card</title><desc id="desc">A Builder's Essential Skill for taking a product goal through delivery.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#171411"/><stop offset="1" stop-color="#090a0d"/></linearGradient><linearGradient id="line" x1="0" y1="0" x2="1" y2="0"><stop stop-color="#b87537" stop-opacity="0"/><stop offset=".5" stop-color="#e0b06e"/><stop offset="1" stop-color="#7162a2" stop-opacity=".2"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="14"/></filter></defs>
+  <rect width="1200" height="760" fill="#0b0b0c"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#6c5a40" stroke-opacity=".52"/><circle cx="985" cy="160" r="112" fill="#7d5eab" fill-opacity=".22" filter="url(#glow)"/><path d="M70 552C310 552 350 212 640 212s230 306 486 306" fill="none" stroke="url(#line)" stroke-width="3"/>
+  <text x="78" y="106" fill="#c4b79f" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 01</text><text x="78" y="204" fill="#f6f0e5" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">lead</text><text x="80" y="258" fill="#c6c1b9" font-family="Arial, Helvetica, sans-serif" font-size="28">Turn a product goal into a planned, built,</text><text x="80" y="296" fill="#c6c1b9" font-family="Arial, Helvetica, sans-serif" font-size="28">reviewed, and verified pull request.</text>
+  <g transform="translate(844 150)" fill="none" stroke="#e0b06e" stroke-width="5"><path d="M0 152 84 0l84 152z"/><path d="M42 76h84"/><circle cx="84" cy="76" r="14" fill="#e0b06e"/></g><rect x="78" y="376" width="1044" height="1" fill="#9c896c" fill-opacity=".35"/><text x="78" y="432" fill="#b7a27d" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#f3eee5" font-family="Arial, Helvetica, sans-serif" font-size="29">Build &amp; delivery</text><text x="520" y="432" fill="#b7a27d" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#f3eee5" font-family="Arial, Helvetica, sans-serif" font-size="29">A clear path from goal to proof</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#191817" stroke="#806745"/><text x="104" y="596" fill="#e6d4b7" font-family="monospace" font-size="20">/lead Build this feature and prepare one PR.</text><circle cx="1058" cy="586" r="30" fill="#c18a4e"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#14110e" stroke-width="5"/>
+</svg>

package/assets/skill-cards/orwell-writing.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">orwell-writing skill card</title><desc id="desc">A Builder's Essential Skill for clear, direct writing.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#151917"/><stop offset="1" stop-color="#0a0d0c"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#090b0a"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#5d7769" stroke-opacity=".6"/><circle cx="975" cy="165" r="118" fill="#6d9c80" fill-opacity=".17" filter="url(#glow)"/><path d="M72 540C300 540 358 197 620 197s267 287 504 287" fill="none" stroke="#83ae90" stroke-opacity=".72" stroke-width="3"/>
+  <text x="78" y="106" fill="#b0c9b6" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 06</text><text x="78" y="204" fill="#f0f7ef" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">orwell-writing</text><text x="80" y="258" fill="#c2cec3" font-family="Arial, Helvetica, sans-serif" font-size="28">Edit prose until it says what it means: direct, specific,</text><text x="80" y="296" fill="#c2cec3" font-family="Arial, Helvetica, sans-serif" font-size="28">and free of filler.</text>
+  <g transform="translate(850 108)" fill="none" stroke="#99c5a5" stroke-width="5"><path d="M23 28h132v150H23zM52 68h75M52 98h75M52 128h45"/><path d="m61 172 18 18 43-51"/></g><rect x="78" y="376" width="1044" height="1" fill="#9bb9a0" fill-opacity=".35"/><text x="78" y="432" fill="#9fbda5" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#eff6f0" font-family="Arial, Helvetica, sans-serif" font-size="29">Writing</text><text x="520" y="432" fill="#9fbda5" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#eff6f0" font-family="Arial, Helvetica, sans-serif" font-size="29">Clearer language, still your voice</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#131b16" stroke="#537563"/><text x="104" y="596" fill="#c8e1cd" font-family="monospace" font-size="19">/orwell-writing Rewrite this in plain English.</text><circle cx="1058" cy="586" r="30" fill="#78a987"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#0d180f" stroke-width="5"/>
+</svg>

package/assets/skill-cards/session-profiler.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">session-profiler skill card</title><desc id="desc">A Builder's Essential Skill for seeing how an agent session performed.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#16131a"/><stop offset="1" stop-color="#0c0b10"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#0b0a0d"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#70577e" stroke-opacity=".62"/><circle cx="972" cy="164" r="118" fill="#9a65b0" fill-opacity=".18" filter="url(#glow)"/><path d="M72 540C298 540 358 202 620 202s269 282 504 282" fill="none" stroke="#ac7cc1" stroke-opacity=".75" stroke-width="3"/>
+  <text x="78" y="106" fill="#c2aaca" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 08</text><text x="78" y="204" fill="#f6edf8" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">session-profiler</text><text x="80" y="258" fill="#ccc3d0" font-family="Arial, Helvetica, sans-serif" font-size="28">Make an agent session visible: timing, tool calls, token use,</text><text x="80" y="296" fill="#ccc3d0" font-family="Arial, Helvetica, sans-serif" font-size="28">errors, subagents, and traces.</text>
+  <g transform="translate(849 109)" fill="none" stroke="#c194d2" stroke-width="5"><path d="M21 158V30h156v128zM47 130V94l31-28 30 21 29-39 19 18v64"/><circle cx="78" cy="66" r="7" fill="#c194d2"/><circle cx="108" cy="87" r="7" fill="#c194d2"/><circle cx="137" cy="48" r="7" fill="#c194d2"/></g><rect x="78" y="376" width="1044" height="1" fill="#af91ba" fill-opacity=".35"/><text x="78" y="432" fill="#b494c0" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#f5edf7" font-family="Arial, Helvetica, sans-serif" font-size="29">Developer tools</text><text x="520" y="432" fill="#b494c0" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#f5edf7" font-family="Arial, Helvetica, sans-serif" font-size="29">The story behind the session</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#1a1420" stroke="#745c82"/><text x="104" y="596" fill="#dac2e4" font-family="monospace" font-size="17">$session-profiler Profile my latest Codex session.</text><circle cx="1058" cy="586" r="30" fill="#a677b7"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#190d20" stroke-width="5"/>
+</svg>

package/assets/skill-cards/validate-market.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">validate-market skill card</title><desc id="desc">A Builder's Essential Skill for testing market demand.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#181611"/><stop offset="1" stop-color="#0d0d09"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#0d0c09"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#7a724a" stroke-opacity=".62"/><circle cx="972" cy="165" r="117" fill="#b2a45c" fill-opacity=".18" filter="url(#glow)"/><path d="M72 540C300 540 357 205 624 205s259 286 500 286" fill="none" stroke="#c4b56c" stroke-opacity=".76" stroke-width="3"/>
+  <text x="78" y="106" fill="#c9c093" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 04</text><text x="78" y="204" fill="#f7f4e6" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">validate-market</text><text x="80" y="258" fill="#ceccbd" font-family="Arial, Helvetica, sans-serif" font-size="28">Test whether a product idea has real demand, a credible</text><text x="80" y="296" fill="#ceccbd" font-family="Arial, Helvetica, sans-serif" font-size="28">position, and a worthwhile next step.</text>
+  <g transform="translate(851 112)" fill="none" stroke="#d1c574" stroke-width="5"><circle cx="91" cy="91" r="70"/><path d="m91 27 20 42 46 7-33 33 8 46-41-22-41 22 8-46-33-33 46-7z"/><circle cx="91" cy="91" r="10" fill="#d1c574"/></g><rect x="78" y="376" width="1044" height="1" fill="#b9b17d" fill-opacity=".35"/><text x="78" y="432" fill="#c1b978" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#f4f1e5" font-family="Arial, Helvetica, sans-serif" font-size="29">Product &amp; market</text><text x="520" y="432" fill="#c1b978" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#f4f1e5" font-family="Arial, Helvetica, sans-serif" font-size="29">An honest case for the next move</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#1c1a10" stroke="#847b48"/><text x="104" y="596" fill="#e2daab" font-family="monospace" font-size="19">/validate-market Audit this idea's market fit.</text><circle cx="1058" cy="586" r="30" fill="#b0a45e"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#171407" stroke-width="5"/>
+</svg>

package/assets/skill-cards/write-blog.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 760" role="img" aria-labelledby="title desc">
+  <title id="title">write-blog skill card</title><desc id="desc">A Builder's Essential Skill for publishing a blog post with a human voice.</desc>
+  <defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#1a1411"/><stop offset="1" stop-color="#0e0b0a"/></linearGradient><filter id="glow"><feGaussianBlur stdDeviation="16"/></filter></defs>
+  <rect width="1200" height="760" fill="#0d0a09"/><rect x="24" y="24" width="1152" height="712" rx="28" fill="url(#bg)" stroke="#805e47" stroke-opacity=".62"/><circle cx="974" cy="164" r="118" fill="#bf7951" fill-opacity=".18" filter="url(#glow)"/><path d="M72 540C295 540 360 198 620 198s273 290 504 290" fill="none" stroke="#cf8558" stroke-opacity=".75" stroke-width="3"/>
+  <text x="78" y="106" fill="#d0ad96" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700" letter-spacing="3">BUILDER'S ESSENTIAL SKILLS / 05</text><text x="78" y="204" fill="#f9eee8" font-family="Arial, Helvetica, sans-serif" font-size="64" font-weight="700">write-blog</text><text x="80" y="258" fill="#d5c4bc" font-family="Arial, Helvetica, sans-serif" font-size="28">Find a strong angle, draft in a human voice, and help</text><text x="80" y="296" fill="#d5c4bc" font-family="Arial, Helvetica, sans-serif" font-size="28">ship a blog post that earns attention.</text>
+  <g transform="translate(852 106)" fill="none" stroke="#e09a6e" stroke-width="5"><path d="m22 155 35-9 104-104-26-26L31 120zM118 33l26 26"/><path d="M25 171h150M49 193h101"/><path d="M46 131 67 152"/></g><rect x="78" y="376" width="1044" height="1" fill="#c69c84" fill-opacity=".35"/><text x="78" y="432" fill="#ca9f86" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">DISCIPLINE</text><text x="78" y="476" fill="#f8eeea" font-family="Arial, Helvetica, sans-serif" font-size="29">Writing &amp; growth</text><text x="520" y="432" fill="#ca9f86" font-family="Arial, Helvetica, sans-serif" font-size="16" font-weight="700" letter-spacing="2">PROMISE</text><text x="520" y="476" fill="#f8eeea" font-family="Arial, Helvetica, sans-serif" font-size="29">A post people want to read</text><rect x="78" y="554" width="780" height="66" rx="12" fill="#211612" stroke="#8f6049"/><text x="104" y="596" fill="#edc3ab" font-family="monospace" font-size="19">/write-blog Write a launch post for this project.</text><circle cx="1058" cy="586" r="30" fill="#c47b55"/><path d="m1048 586 8 8 15-17" fill="none" stroke="#1a0e0a" stroke-width="5"/>
+</svg>

package/bin/builder-essential-skills.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const packageName = require(path.join(packageRoot, "package.json")).name;
+const npxCommand = `npx ${packageName}`;
+const skillsSource = path.join(packageRoot, "skills");
+const agentsSource = path.join(packageRoot, ".claude", "agents");
+
+function printHelp() {
+  console.log(`Install Builder's Essential Skills.
+
+Usage:
+  ${npxCommand} [--skill <name>] [--project]
+
+Options:
+  -s, --skill    Install one skill instead of the full collection
+  -p, --project  Install into the current repository instead of your user home
+  -h, --help     Show this help message
+
+User install locations:
+  Claude Code  ~/.claude/skills and ~/.claude/agents
+  Codex        $CODEX_HOME/skills (or ~/.codex/skills)
+
+Project install locations:
+  .claude/skills, .claude/agents, and .codex/skills in the current directory
+`);
+}
+
+function parseArgs(args) {
+  let project = false;
+  let skill = null;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-p" || arg === "--project") {
+      project = true;
+    } else if (arg === "-s" || arg === "--skill") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        console.error("Missing skill name after --skill.");
+        process.exit(1);
+      }
+      skill = value;
+      index += 1;
+    } else if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown option: ${arg}`);
+      console.error(`Run \`${npxCommand} --help\` for usage.`);
+      process.exit(1);
+    }
+  }
+
+  return { project, skill };
+}
+
+function installDirectory(source, destination, label, selectedSkill) {
+  fs.mkdirSync(destination, { recursive: true });
+
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (!entry.isDirectory() || (selectedSkill && entry.name !== selectedSkill)) {
+      continue;
+    }
+
+    const sourcePath = path.join(source, entry.name);
+    const destinationPath = path.join(destination, entry.name);
+    fs.rmSync(destinationPath, { recursive: true, force: true });
+    fs.cpSync(sourcePath, destinationPath, { recursive: true });
+    removePythonCaches(destinationPath);
+    console.log(`Installed ${label} /${entry.name} to ${destinationPath}`);
+  }
+}
+
+function removePythonCaches(root) {
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory() && entry.name === "__pycache__") {
+      fs.rmSync(entryPath, { recursive: true, force: true });
+    } else if (entry.isDirectory()) {
+      removePythonCaches(entryPath);
+    }
+  }
+}
+
+function installAgents(destination) {
+  if (!fs.existsSync(agentsSource)) {
+    return;
+  }
+
+  fs.mkdirSync(destination, { recursive: true });
+  for (const entry of fs.readdirSync(agentsSource, { withFileTypes: true })) {
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const destinationPath = path.join(destination, entry.name);
+    fs.cpSync(path.join(agentsSource, entry.name), destinationPath);
+    console.log(`Installed agent ${entry.name} to ${destinationPath}`);
+  }
+}
+
+function main() {
+  const { project, skill } = parseArgs(process.argv.slice(2));
+  const availableSkills = fs
+    .readdirSync(skillsSource, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  if (skill && !availableSkills.includes(skill)) {
+    console.error(`Unknown skill: ${skill}`);
+    console.error(`Available skills: ${availableSkills.join(", ")}`);
+    process.exit(1);
+  }
+
+  const root = project ? process.cwd() : os.homedir();
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  const claudeRoot = path.join(root, ".claude");
+  const codexRoot = project ? path.join(root, ".codex") : codexHome;
+
+  installDirectory(skillsSource, path.join(claudeRoot, "skills"), "Claude", skill);
+  installDirectory(skillsSource, path.join(codexRoot, "skills"), "Codex", skill);
+  if (!skill || skill === "lead") {
+    installAgents(path.join(claudeRoot, "agents"));
+  }
+
+  console.log("\nRestart Claude Code or Codex to load the installed skills.");
+}
+
+main();