Contributes to and debugs Node.js core, including nodejs/node commit and PR tone, contribution workflows, native crashes, V8 performance, node-gyp builds, N-API bindings, and libuv issues. Use when drafting or reviewing a Node.js core commit or pull request, working in nodejs/node, or diagnosing C++ addons, binding.gyp failures, segfaults, native leaks, V8 deoptimizations, and event-loop internals.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
File Explorer
30 files
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview
name
nodejs-core
description
Contributes to and debugs Node.js core, including nodejs/node commit and PR tone, contribution workflows, native crashes, V8 performance, node-gyp builds, N-API bindings, and libuv issues. Use when drafting or reviewing a Node.js core commit or pull request, working in nodejs/node, or diagnosing C++ addons, binding.gyp failures, segfaults, native leaks, V8 deoptimizations, and event-loop internals.
When drafting a nodejs/node commit or pull request, read
rules/commit-and-pr-guideline.md.
Use terse subsystem-prefixed titles and plain, matter-of-fact prose. Lead with
concrete behavior, explain the reason for the change, and omit hype, canned
headings, file-by-file narration, and unsupported claims. Include the
contributor's DCO sign-off, and never add PR-URL: or Reviewed-By: — those
are added when the change lands. Validate the result with
npx core-validate-commit --no-validate-metadata <sha> in the nodejs/node
checkout.
MANDATORY: Rebuild before testing
Node.js embeds lib/ JavaScript files into the binary at compile time via
js2c. After ANY change to src/ or lib/, you MUST rebuild before
running tests. Without a rebuild, tests run against stale code and results
are meaningless.
edit src/ or lib/ → make -j$(nproc) → make lint → then test
Never skip the rebuild step. Never run ./node test/... after editing
without building first.
Before starting work, ask the user about their build configuration
(Make vs Ninja, debug vs release, what configure flags they use). Do not
assume a specific setup. Most of the time, ./configure has already been
run and only make -j$(nproc) is needed to rebuild.
MANDATORY: Lint and format before every commit
Node.js runs a Linters CI workflow on every non-draft pull request, and on
Unix make test runs no linters. Run make lint before each git commit — plus make format-cpp for C++ changes — so the lint jobs pass on
the first CI run instead of costing a force-push and another full cycle.
make -j$(nproc) # rebuild first
make lint # JS, C++, MD, docs, YAML# C++ changes only — use the merge-base form, which is what CI checks:
CLANG_FORMAT_START="$(git merge-base HEAD upstream/main)" make format-cpp
git --no-pager diff --exit-code # must be empty
git add -A && git commit -s # -s is mandatory
npx core-validate-commit --no-validate-metadata HEAD
Never skip a step because the change looks trivial, and never commit with
"will fix lint in a follow-up".
Bare make format-cpp is not enough. It defaults to
CLANG_FORMAT_START=HEAD and formats only staged changes, while the
format-cpp CI job formats everything from the merge base and fails on any
resulting diff — so unformatted code committed earlier in the branch passes
locally and fails in CI. Always pass the merge-base form shown above.
Every commit must be created with git commit -s. The -s flag adds the
Signed-off-by: trailer certifying the Developer Certificate of Origin.
Without it the signed-off-by rule of core-validate-commit fails and the PR
cannot land. The sign-off must be the human contributor's name and email —
never sign off with a tool or AI identity, and never fabricate someone else's.
If you forget it, amend with git commit --amend --signoff.
make lint runs lint-js, lint-cpp, lint-addon-docs, lint-md, and
lint-yaml — it does not cover every CI lint job. Python (make lint-py),
shell (tools/lint-sh.mjs .), C++ formatting, and commit-message validation
are separate jobs. See rules/pre-commit-lint.md
for the full gate and the CI-job-to-command mapping.
Validate every commit message with core-validate-commit, always with
--no-validate-metadata — metadata validation is on by default and enforces
trailers that only exist after landing. Never add PR-URL: or
Reviewed-By: to a commit you author; the landing process adds them.
Apply deep knowledge of Node.js internals across these domains:
Core architecture: Node.js core modules and their C++ implementations, V8 GC and JIT, libuv event loop mechanics, thread pool behavior, startup/module-loading lifecycle
Native development: N-API, node-addon-api, and NAN addon development; V8 C++ API handle management; memory safety; native debugging with gdb/lldb
gdb --args node --napi-modules ./build/Release/addon.node
# Inside gdb:
run
bt # backtrace on crash# Checkpoint: verify backtrace shows the expected call site before applying a fix
Heap snapshot for memory leaks:
node --inspect script.js # then open chrome://inspect, take heap snapshot# Checkpoint: compare two consecutive heap snapshots to confirm leak growth before and after the fix; run valgrind --leak-check=full node addon_test.js to confirm no native leaks remain
Node.js-specific diagnostic decision trees
Segfault / crash in native addon:
Is the crash reproducible with node --napi-modules? → Run gdb, capture bt
Does bt point to a V8 handle scope issue? → Check HandleScope / EscapableHandleScope usage in the addon
Does it point to a libuv callback? → Inspect async handle lifetime and uv_close() sequencing
No clear C++ frame? → Check for JS-side type mismatches passed into the native binding
V8 deoptimization / performance regression:
Run --trace-opt --trace-deopt → identify the deoptimized function and reason (e.g., "not a Smi", "wrong map")
Checkpoint: confirm the same function deoptimizes consistently across runs
Inspect hidden class transitions (--trace-ic) and fix property addition order or type inconsistencies
Re-run --trace-opt to confirm the function is now optimized
Build failure (node-gyp / binding.gyp):
Is it a missing header? → Verify include_dirs in binding.gyp and Node.js header installation
Is it a linker error? → Check libraries and link_settings entries; confirm ABI compatibility
Is it platform-specific? → Consult rules/build-system.md for Windows/macOS/Linux differences
Always consider both JavaScript-level and native-level causes, explain performance implications and trade-offs, and indicate the stability status of any experimental features discussed. Code examples should demonstrate Node.js internals patterns and be production-ready, accounting for edge cases typical developers might miss.
