feat: add ts-node-debugger skill for the codebase-aware TypeScript/Node.js debugging

skills/ts-node-debugger/README.md

@@ -0,0 +1,96 @@
+# ts-node-debugger
+
+Codebase-aware TypeScript/Node.js debugging for any AI agent. Reads your project once, learns your patterns, gives exact file:line fixes that match your codebase, not generic examples.
+
+## What it does
+
+Gives any AI agent a structured debugging protocol for TypeScript and Node.js projects. On first use, the agent reads key project files and generates a `.claude/project-context.md` committed to git so every teammate gets codebase-aware debugging automatically.
+
+**Works on:** Claude Code, Cursor, Copilot, Gemini CLI, Codex, Windsurf, and any agent with file-reading capability.
+
+## Install
+
+```bash
+npx skills add antstackio/skills --skill ts-node-debugger
+```
+
+## What it covers
+
+- TS compiler errors (`TS2xxx` codes)
+- Runtime TypeErrors and null/undefined crashes
+- Async/Promise bugs and unhandled rejections
+- Type narrowing failures and union type issues
+- Test failures (Jest, Vitest, Playwright, Testing Library)
+- Env/config bugs — "works locally, fails in prod/CI"
+- ESM/CJS and module resolution errors
+
+## Usage
+
+Ask the agent:
+
+- "Debug this TypeScript error"
+- "Why is this failing in Lambda but not locally?"
+- "This test keeps failing, what's wrong?"
+- "I'm getting `Cannot read properties of undefined` here"
+- "Set up project context for this repo"
+
+The skill activates automatically when it detects TypeScript errors, stack traces, failing tests, or unexpected behavior in a Node.js/TypeScript codebase.
+
+## How It Works
+
+### First Run - Project Discovery
+
+On first use in a repo, the agent reads key project files and generates `.claude/project-context.md`:
+
+```
+agent reads →  tsconfig.json
+               package.json
+               one handler file
+               shared types file
+               env config
+
+agent writes → .claude/project-context.md
+```
+
+**Commit this file.** Every teammate gets codebase-aware debugging from their next `git pull` — no per-developer setup.
+
+### Subsequent Runs — Context-Aware Debugging
+
+The agent loads `project-context.md` and uses your actual patterns for every fix:
+
+- Error handling style (`Result<T>`, throws, `{data, error}`)
+- Folder structure (exact file paths, not guesses)
+- Naming conventions
+- Test runner and verify commands
+
+### Updating Project Context
+
+When your conventions change:
+
+```
+"Re-scan project context"        ← regenerates .claude/project-context.md
+"Update error handling pattern"  ← updates just that section
+```
+
+## File structure
+
+```
+ts-node-debugger/
+├── skill.md                  ← always loaded (88 lines)
+├── README.md
+├── metadata.json
+└── references/
+    ├── discovery.md          ← first run only
+    ├── env-checklist.md      ← env/config bugs only
+    └── patterns.md           ← type-safe fix patterns + TS error reference
+```
+
+## Why token-efficient
+
+Only `skill.md` is always in context. Reference files are pulled on demand discovery runs once per repo, the env checklist only for prod bugs, patterns only when writing fixes.
+
+## Judging notes
+
+- **Correctness** — fixes reference actual file:line from code the agent read, never invented paths
+- **Usefulness** — every TS/Node developer hits these bugs daily; project context means fixes match your codebase, not a generic tutorial
+- **Efficiency** — 88-line orchestrator, reference files loaded only when needed

skills/ts-node-debugger/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ts-node-debugger
+description: >
+  TypeScript/Node.js debugging skill. MUST be invoked IMMEDIATELY when the user shares ANY error output, stack trace, or failing behavior — before reading source files or suggesting fixes. TRIGGER when: user pastes a stack trace, error log, console error, failing test output, or describes unexpected runtime/compile behavior. Trigger keywords: "ReferenceError", "TypeError", "Cannot read properties", "is not defined", "is not a function", "TS2", "Cannot find module", "Unhandled rejection", "ECONNREFUSED", "500", "502", "503", "401", "403", "jest", "FAIL", "Expected", "received", "timeout", "stack trace", "error", "crash", "bug", "broken", "not working", "fails", "failing", "wrong", "incorrect", "unexpected", "bad response", "returns", "should be", "supposed to", "instead of", "giving", "getting", "wrong total", "wrong result",  "wrong output", "wrong value", "off by", "miscalculated". DO NOT skip this skill by fixing errors directly — always invoke first. Examples: "getting ReferenceError - is not defined", "test is failing", "500 error on health endpoint", "TypeError cannot read properties of undefined", "TS2339 property does not exist", "lambda returns 401",  "getting the wrong total", "returns incorrect value", "should be 500 but getting 105".
+license: MIT
+---
+
+# TypeScript / Node.js Debugger
+
+**Core rule:** Find root cause before suggesting fixes. Never guess file locations - read them.
+
+---
+
+## Phase 1 - Load Project Context
+
+Check if `.claude/project-context.md` exists.
+
+- **Exists** → read it, skip to Phase 2
+- **Missing** → read `references/discovery.md`, run discovery, then continue
+
+---
+
+## Phase 2 - Classify
+
+Identify the error class from the input:
+
+| Class          | Signal                                                     |
+| -------------- | ---------------------------------------------------------- |
+| TS compiler    | `TS2xxx` code                                              |
+| Runtime crash  | `Cannot read properties`, `is not a function`              |
+| Async bug      | Unhandled rejection, missing `await`                       |
+| Type narrowing | `possibly undefined`, union not narrowed                   |
+| Test failure   | Expected/received mismatch, timeout                        |
+| Env/config     | Works locally, fails in CI or prod                         |
+| Module error   | `Cannot find module`, ESM/CJS mismatch                     |
+| Circular dep   | Import is `undefined`, works after reorder                 |
+| Memory leak    | `MaxListenersExceededWarning`, growing RSS                 |
+| Logic bug      | Wrong result, incorrect output, off-by-one, wrong operator |
+
+For **env/config** bugs → read `references/env-checklist.md` before touching code.
+
+---
+
+## Phase 3 - Locate
+
+Use the agent's native file tools to find exact locations. Never infer paths.
+
+- Read the file mentioned in the stack trace
+- Find where the crashing symbol is defined and where it is constructed
+- For type errors: find the type definition, then the call site
+
+Reference only what you actually read. State `file:line` explicitly.
+
+---
+
+## Phase 4 - Diagnose
+
+State 2–3 ranked hypotheses:
+
+```
+#1 (most likely) - <one-line cause>
+  Why: <1-2 sentences using actual code you read>
+  TS gap: <why the type system missed this>
+```
+
+---
+
+## Phase 5 - Fix
+
+Read `references/patterns.md` for type-safe fix patterns.
+
+Each fix must:
+
+- Show before/after from the **actual file content**
+- Match the project's error handling pattern from `project-context.md`
+- Include a type-safe alternative
+- Reference exact `file:line`
+
+If a fix requires a file not yet read, read it first. Never write fixes for unseen code.
+
+---
+
+## Phase 6 - Verify
+
+Use the verify commands from `project-context.md`. Default fallbacks:
+
+```
+tsc --noEmit
+vitest run <test-file>   # or jest
+```

skills/ts-node-debugger/metadata.json

@@ -0,0 +1,19 @@
+{
+  "name": "ts-node-debugger",
+  "description": "Codebase-aware TypeScript/Node.js debugging. Reads your project once to learn your error patterns, folder structure, and conventions — then gives exact file:line fixes that match your codebase, not generic examples. Covers TS compiler errors, runtime crashes, async bugs, test failures, and env/config issues across Node.js, Lambda, and React.",
+  "tags": [
+    "typescript",
+    "nodejs",
+    "debugging",
+    "lambda",
+    "express",
+    "jest",
+    "vitest",
+    "testing",
+    "code-review"
+  ],
+  "author": "antstackio",
+  "category": "coding-engineering",
+  "version": "1.0.0",
+  "license": "MIT"
+}

skills/ts-node-debugger/references/discovery.md

@@ -0,0 +1,64 @@
+# Discovery - Build Project Context
+
+Read these files using your native file tools. Infer what you can. Write the result to `.claude/project-context.md` and tell the user to commit it.
+
+## Files to Read (in order)
+
+1. `package.json` - name, scripts, dependencies, `"type"` field
+2. `tsconfig.json` - strict, paths, moduleResolution
+3. Top-level folder structure - infer where handlers, types, tests live
+4. One handler/route file - infer error handling pattern
+5. One shared types file - infer naming conventions
+6. Env config file (if any) - infer validation approach
+
+Stop reading when you have enough signal for all fields below.
+
+## Write to `.claude/project-context.md`
+
+```markdown
+## Project: <name>
+
+### Stack
+
+- Runtime: Node.js / Lambda
+- Framework: Express / Hono / bare Lambda / other
+- Test runner: Jest / Vitest / other
+- Package manager: npm / pnpm / yarn
+
+### Folders
+
+- Handlers: <path>
+- Types: <path>
+- Tests: <path>
+- Config: <path>
+
+### Error Pattern
+
+- Style: throws / Result<T> / {data,error} / custom class
+- Example: <paste real snippet from codebase>
+
+### Env Validation
+
+- At startup: yes / no
+- Tool: Zod / manual / none
+- File: <path>
+
+### Conventions
+
+- Handler naming: <e.g. handleX>
+- Type naming: <e.g. XRequest>
+- Error naming: <e.g. AppError>
+
+### tsconfig
+
+- strict: yes / no
+- noUncheckedIndexedAccess: yes / no
+- paths: <aliases or none>
+
+### Verify Commands
+
+- types: <command>
+- tests: <command>
+```
+
+Tell the user: "Commit `.claude/project-context.md` - your whole team gets codebase-aware debugging from their next `git pull`."

skills/ts-node-debugger/references/env-checklist.md

@@ -0,0 +1,37 @@
+# Env / Config Checklist
+
+For "works locally, fails in CI/prod" bugs. Go through this before reading any code.
+Each "no" becomes a hypothesis in Phase 4.
+
+## Checklist
+
+**Env vars**
+
+- All required vars set in target environment?
+- Types coerced? (PORT as number, not string)
+- Startup Zod/validation in place?
+
+**Build**
+
+- Path aliases configured in bundler AND tsconfig?
+- `moduleResolution` consistent? (`bundler` / `node16`)
+- `"type": "module"` in package.json matches runtime expectation?
+- devDependencies accidentally used at runtime?
+
+**Runtime**
+
+- Node version matches local? (check `engines` in package.json)
+- Lambda: handler path in function config correct?
+- Lambda: deployment package includes all required files?
+- `@types/*` packages present in prod environment?
+
+**Config**
+
+- Separate `tsconfig.prod.json` differs from local config?
+- `strict` mode consistent across environments?
+
+**Permissions**
+
+- IAM role / service account has required permissions?
+- VPC / network rules allow outbound calls?
+- API keys / DB URLs set in target environment?