@tamng0905/builder-essential-skills 0.1.0

package/install.ps1

@@ -0,0 +1,58 @@
+param([switch]$Project)
+
+# Central skills hub installer. The same skills land in Claude Code
+# (~\.claude\skills) and in Codex (${CODEX_HOME:-~\.codex}\skills); the agents /lead dispatches
+# land in ~\.claude\agents. Use -Project to install into the current repo only.
+
+$srcRoot   = Join-Path $PSScriptRoot "skills"
+$agentsSrc = Join-Path $PSScriptRoot ".claude\agents"
+if ($Project) {
+    $claudeDest = Join-Path (Get-Location) ".claude\skills"
+    $codexDest  = Join-Path (Get-Location) ".codex\skills"
+    $agentsDest = Join-Path (Get-Location) ".claude\agents"
+} else {
+    $claudeDest = Join-Path $env:USERPROFILE ".claude\skills"
+    $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
+    $codexDest  = Join-Path $codexHome "skills"
+    $agentsDest = Join-Path $env:USERPROFILE ".claude\agents"
+}
+
+function Install-Into($destRoot, $label) {
+    New-Item -ItemType Directory -Force $destRoot | Out-Null
+    foreach ($skill in Get-ChildItem -Directory $srcRoot) {
+        $dest = Join-Path $destRoot $skill.Name
+        if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }
+        Copy-Item -Recurse $skill.FullName $dest
+        Get-ChildItem -LiteralPath $dest -Recurse -Directory -Filter "__pycache__" -ErrorAction SilentlyContinue | Remove-Item -Recurse -Force
+        Write-Host "Installed $label /$($skill.Name) to $dest"
+    }
+}
+
+# Claude Code reads skills from ~\.claude\skills; Codex from ${CODEX_HOME:-~\.codex}\skills.
+Install-Into $claudeDest "Claude"
+Install-Into $codexDest  "Codex"
+
+# The /lead skill dispatches builder/reviewer subagents defined in .claude\agents.
+if (Test-Path $agentsSrc) {
+    New-Item -ItemType Directory -Force $agentsDest | Out-Null
+    foreach ($agent in Get-ChildItem -File -Filter "*.md" $agentsSrc) {
+        Copy-Item $agent.FullName (Join-Path $agentsDest $agent.Name)
+        Write-Host "Installed agent $($agent.Name) to $agentsDest"
+    }
+}
+
+Write-Host ""
+$py = Get-Command python -ErrorAction SilentlyContinue
+if (-not $py) { $py = Get-Command python3 -ErrorAction SilentlyContinue }
+if ($py) {
+    Write-Host "Model routing for /lead (defaults):"
+    & $py.Path (Join-Path $srcRoot "lead\config.py") --repo-root (Get-Location)
+} else {
+    Write-Host "python not found - install it to use 'python skills\lead\config.py' for model routing."
+}
+$codex = Get-Command codex -ErrorAction SilentlyContinue
+if ($codex) {
+    Write-Host "Codex CLI found: $(codex --version)"
+} else {
+    Write-Host "Codex CLI not found (optional builder backend for /lead): npm i -g @openai/codex@latest"
+}

package/install.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Central skills hub installer. The same skills land in Claude Code
+# (~/.claude/skills) and in Codex (${CODEX_HOME:-~/.codex}/skills), and the agents the /lead
+# skill dispatches land in ~/.claude/agents. Pass --project (or -p) to install
+# into the current repo only.
+
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+SRC_ROOT="$ROOT/skills"
+AGENTS_SRC="$ROOT/.claude/agents"
+project=0
+case "${1:-}" in --project|-p) project=1;; esac
+
+if [ "$project" -eq 1 ]; then
+    CLAUDE_DEST="$(pwd)/.claude/skills"
+    CODEX_DEST="$(pwd)/.codex/skills"
+    AGENTS_DEST="$(pwd)/.claude/agents"
+else
+    CLAUDE_DEST="$HOME/.claude/skills"
+    CODEX_DEST="${CODEX_HOME:-$HOME/.codex}/skills"
+    AGENTS_DEST="$HOME/.claude/agents"
+fi
+
+install_into() {
+    dest_root=$1; label=$2
+    mkdir -p "$dest_root"
+    for skill in "$SRC_ROOT"/*/; do
+        name="$(basename "$skill")"
+        rm -rf "${dest_root:?}/$name"
+        cp -r "$skill" "$dest_root/$name"
+        find "$dest_root/$name" -name '__pycache__' -type d -prune -exec rm -rf {} + 2>/dev/null || true
+        echo "Installed $label /$name to $dest_root/$name"
+    done
+}
+
+# Claude Code reads skills from ~/.claude/skills (user) or $CWD/.claude/skills (repo).
+install_into "$CLAUDE_DEST" "Claude"
+# Codex reads user skills from ${CODEX_HOME:-~/.codex}/skills.
+install_into "$CODEX_DEST" "Codex"
+
+# The /lead skill dispatches builder/reviewer subagents defined in .claude/agents.
+if [ -d "$AGENTS_SRC" ]; then
+    mkdir -p "$AGENTS_DEST"
+    for agent in "$AGENTS_SRC"/*.md; do
+        [ -e "$agent" ] || continue
+        cp "$agent" "$AGENTS_DEST/"
+        echo "Installed agent $(basename "$agent") to $AGENTS_DEST"
+    done
+fi
+
+echo
+if command -v python3 >/dev/null 2>&1; then
+    echo "Model routing for /lead (defaults):"
+    python3 "$SRC_ROOT/lead/config.py" --repo-root "$(pwd)" || true
+else
+    echo "python3 not found - install it to use 'python skills/lead/config.py' for model routing."
+fi
+if command -v codex >/dev/null 2>&1; then
+    echo "Codex CLI found: $(codex --version)"
+else
+    echo "Codex CLI not found (optional builder backend for /lead): npm i -g @openai/codex@latest"
+fi

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@tamng0905/builder-essential-skills",
+  "version": "0.1.0",
+  "description": "Builder's Essential Skills — reusable workflows for Claude Code and Codex",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "builder-essential-skills": "bin/builder-essential-skills.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "assets",
+    ".claude/agents",
+    "install.ps1",
+    "install.sh",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/async-learning-teacher/README.md

@@ -0,0 +1,50 @@
+# Async Learning Teacher
+
+<p align="center">
+  <img src="../../assets/skill-cards/async-learning-teacher.svg" alt="async-learning-teacher skill card" width="100%">
+</p>
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill async-learning-teacher
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill async-learning-teacher --project
+```
+
+Restart Claude Code or Codex after installation, then ask it to teach you a
+saved link, paper, article, post, video, or reference collection.
+
+A portable agent skill for turning saved links, papers, articles, posts, videos, and reference collections into approachable teaching artifacts for later study.
+
+## What It Does
+
+Async Learning Teacher helps you queue interesting resources now and learn from them later. Instead of saving raw links that are hard to restart from, the agent converts them into readable explanations, study notes, or interactive tutoring checkpoints.
+
+It supports two learning modes:
+
+## Quick Teaching
+
+Use this for a single link, paper, blog post, tweet thread, video, or small source set.
+
+The agent creates a complete teaching artifact in one pass:
+
+- Why the resource matters
+- Prerequisites
+- Step-by-step chapter-style explanation
+- Subtle points and examples
+- What to remember
+- Follow-up questions
+- Validation gaps
+
+Example prompt:
+
+```text
+Use $async-learning-teacher to teach me this paper:
+https://arxiv.org/abs/...

package/skills/async-learning-teacher/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: async-learning-teacher
+description: Transform saved links, papers, articles, posts, videos, and reference collections into approachable AI teaching artifacts for later study. Use when a user wants to queue learning material, create a readable explanation from a source, teach a paper or post step by step, or run an interactive tutor that validates understanding over multiple sessions.
+---
+
+# Async Learning Teacher
+
+## Mission
+
+Convert raw learning captures into approachable teaching artifacts so a user can queue interesting resources now and study them later with less friction than reading the original source cold.
+
+Use this skill for:
+
+- Single links: blog posts, essays, papers, tweet threads, videos, documentation pages, or notes.
+- Reference sets: 5-10+ links about one domain or topic.
+- User-supplied pasted text when a link is unavailable, paywalled, deleted, or hard to scrape.
+- Ongoing tutoring sessions where the agent should validate understanding before moving forward.
+
+## Modes
+
+Choose one mode from the user's request.
+
+### Quick Teaching
+
+Use `quick-teach` for one source or a small tightly related set of sources.
+
+Intent:
+
+```markdown
+Teach me this resource. Break it down step by step. Write each step like a chapter in a book. Write it all out at once. For subtle or difficult concepts, break things down further and use examples.
+```
+
+Produce a complete teaching artifact in one response or one saved document.
+
+### Interactive Tutor
+
+Use `interactive-tutor` for broad topics, reference collections, or requests that explicitly ask to validate understanding.
+
+Intent:
+
+```markdown
+Resources:
+[reference links or pasted excerpts]
+
+I would like you to teach me about [topic]. Presume I understand [baseline]. Build up my understanding from scratch step by step. Do not move to the next step without validating my current understanding. For subtle or difficult concepts, break things down further and use examples.
+```
+
+Teach one step at a time. Stop at the end of each step and ask the user to explain their understanding or answer validation questions before continuing.
+
+Default mode selection:
+
+- One link or one source: `quick-teach`.
+- Multiple references plus a broad topic: `interactive-tutor`.
+- User says "quiz me", "validate me", "teach me over time", or "do not move on": `interactive-tutor`.
+
+## Workflow
+
+1. Parse the user's capture:
+   - Source URLs
+   - Pasted source text
+   - Topic
+   - User's stated baseline knowledge
+   - Desired output location or format, if any
+   - Requested mode, if any
+
+2. Inspect the source when possible:
+   - Fetch or read available content.
+   - If access is unavailable, use the URL, title, abstract, snippet, or pasted user context.
+   - Clearly mark inaccessible or unverified source material.
+
+3. Create the teaching artifact:
+   - Use `quick-teach` for one-shot explanations.
+   - Use `interactive-tutor` for staged learning and validation.
+   - Preserve original source links and enough metadata for the user to revisit them.
+
+4. Save or return the result according to the user's environment:
+   - If the user names a destination, write there.
+   - If the environment has a notes app, knowledge base, or file system convention, follow that convention.
+   - If no destination is specified, return the artifact in Markdown and suggest a clear filename.
+
+5. Report:
+   - What was processed
+   - Where it was saved, if applicable
+   - Any validation gaps or follow-up questions
+
+## Quick Teaching Output
+
+Use this structure unless the user asks for another format:
+
+```markdown
+# [Resource Title] - Teaching Notes
+
+## Source
+- [Original link or citation]
+
+## Why This Matters
+-
+
+## Prerequisites
+-
+
+## Chapter 1 - [Concept]
+...
+
+## Chapter 2 - [Concept]
+...
+
+## Subtle Points
+-
+
+## Examples
+-
+
+## What To Remember
+-
+
+## Follow-Up Questions
+-
+
+## Validation Gaps
+-
+```
+
+Quality bar:
+
+- Build from first principles.
+- Prefer chapter-style explanation over bullet-only summaries.
+- Explain jargon before relying on it.
+- Use examples for subtle or abstract ideas.
+- Separate what the source claims from what the agent infers.
+- Include "Validation Gaps" for inaccessible pages, unclear claims, stale information, missing context, or uncertain interpretation.
+
+## Interactive Tutor Output
+
+Use this structure for the first response or saved checkpoint:
+
+```markdown
+# [Topic] - Interactive Tutor
+
+## Resources
+- [Link or citation]
+
+## Assumed Baseline
+-
+
+## Learning Path
+1. [Step]
+2. [Step]
+3. [Step]
+
+## Current Step
+### Step 1 - [Concept]
+...
+
+## Validation Questions
+1. ...
+2. ...
+3. ...
+
+## Continue When
+Reply with your explanation of the current step. I will check it, correct misunderstandings, and only then move to the next step.
+
+## Session Log
+- [Date/time if available] Started at Step 1.
+
+## Validation Gaps
+-
+```
+
+When continuing an interactive tutor:
+
+- Read the previous checkpoint if available.
+- Evaluate the user's answer against the current step.
+- Correct misunderstandings directly and kindly.
+- If understanding is sufficient, advance one step.
+- If not, reteach the same step with a different example.
+- Keep a concise session log of what was understood and what remains unclear.
+
+## Safety And Source Handling
+
+- Do not claim to have read inaccessible content.
+- Do not hide uncertainty. Mark gaps explicitly.
+- Do not treat generated explanations as source-grounded facts unless they are supported by the source or reliable background knowledge.
+- For medical, legal, financial, safety-critical, or current-events content, verify against authoritative current sources before presenting advice or conclusions.
+- For copyrighted material, summarize and explain rather than reproducing long passages.
+
+## Good Artifact Traits
+
+- The result should feel easier to start than the original source.
+- The explanation should meet the user at their stated level.
+- The output should preserve enough links, context, and questions to support later follow-up.
+- The artifact should be useful even if read days or weeks after capture.

package/skills/async-learning-teacher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Async Learning Teacher"
+  short_description: "Turn saved resources into teaching notes"
+  default_prompt: "Use $async-learning-teacher to turn this link into an approachable teaching artifact for later study."

package/skills/code-standards/README.md

@@ -0,0 +1,27 @@
+# Code Standards
+
+<p align="center">
+  <img src="../../assets/skill-cards/code-standards.svg" alt="code-standards skill card" width="100%">
+</p>
+
+Apply a disciplined workflow to code changes: orient, establish a baseline,
+make the smallest change, test, verify, and self-review.
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill code-standards
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill code-standards --project
+```
+
+Restart Claude Code or Codex, then ask it to implement, fix, or refactor code
+with the repository's checks kept green.
+
+See the full workflow in [SKILL.md](SKILL.md).

package/skills/code-standards/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: code-standards
+description: >-
+  Apply a disciplined engineering workflow to any code change. Use whenever
+  implementing a feature, fixing a bug, or refactoring — before writing code,
+  not after. Walks orient → baseline → smallest change → test → verify →
+  self-review, and enforces language-agnostic hard gates (don't mass-reformat,
+  keep the linter and type-checker clean, keep the build and tests green, make
+  interface changes additive, protect security invariants).
+compatibility: claude-code
+---
+
+# Code standards — the change workflow
+
+You are making a code change. This skill is the execution order; it is
+stack-agnostic. Adapt every command to the project's actual toolchain: read the
+project's own docs (README, CONTRIBUTING, `AGENTS.md`/`CLAUDE.md`, a Makefile or
+package scripts) once to learn its build, test, lint, and format commands before
+you start.
+
+## Steps
+
+1. **Orient.** Read any project lessons/gotchas file (e.g. `tasks/lessons.md`) and obey it.
+   Find and read the one doc for the subsystem you're changing, not the whole tree.
+2. **Plan if non-trivial** (3+ steps or an architectural choice): short plan in `tasks/todo.md` —
+   files touched, tests to add, risks. Going sideways → stop and re-plan.
+3. **Baseline:** get the project's build + test command green *before* touching anything. A
+   pre-existing red is the first task; never build on top of a broken baseline.
+4. **Implement** the smallest root-cause change. Hand-match the surrounding style.
+   **Don't run a mass auto-formatter** on files you touch; it buries your real diff in noise.
+5. **Test:** new behavior gets a test that fails without the change; security gates get
+   negative-assertion tests (wrong token → denied, state unchanged, no data leak).
+6. **Verify:** run the full check suite (build + lint + type-check + tests) until green
+   before you call it "done".
+7. **Self-review** your own diff as if it were someone else's PR (or invoke a review
+   skill). Fix findings before presenting.
+8. **Close out:** update docs in the same change; append to a lessons file if you were
+   corrected or surprised; write a conventional commit message (`feat|fix|docs(scope): …`).
+
+## Tripwires — stop and re-check the project's guidelines when you're about to…
+
+- change a public or shared interface (API, wire format, schema) → check every caller; prefer additive changes
+- add a dependency → weigh transitive weight and licenses, and whether the stdlib already covers it
+- touch auth, tokens, or permissions → audit every writer and reader path, add negative tests
+- write a secret to disk → use the platform's atomic create-private API, never write-then-chmod
+- hold a lock across an `await`/blocking call, or read env inside logic → extract a pure decision function
+
+## No-progress guard
+
+The same failure surviving two fix attempts means stop: write the finding to your lessons
+file, mark the item `[BLOCKED]`, and surface it. Don't thrash.

package/skills/lead/README.md

@@ -0,0 +1,29 @@
+# Lead
+
+<p align="center">
+  <img src="../../assets/skill-cards/lead.svg" alt="lead skill card" width="100%">
+</p>
+
+Run the autonomous build factory: turn a goal into an approved plan, freeze
+acceptance checks, dispatch parallel builders, review their work, and finish
+with a single pull request.
+
+## Install
+
+Install this skill and its supporting builder/reviewer agents for your user
+account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill lead
+```
+
+Install them into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill lead --project
+```
+
+Restart Claude Code or Codex, then invoke it with `/lead` or ask for an
+autonomous build run.
+
+See the full workflow in [SKILL.md](SKILL.md).