nodejs-core
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.
- License 许可
- MIT
- 最近更新
- 2026-08-19
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- metadata
- { "tags": "nodejs, nodejs-core, contributing, commit-message, pull-request, v8, libuv, cpp, native-addons, performance, debugging, internals" }
- 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.
02 资源文件 29
- 参考文档rules/build-and-test-workflow.md12.8 KB
- 参考文档rules/build-system.md7.6 KB
- 参考文档rules/child-process-internals.md12.1 KB
- 参考文档rules/cli-options.md14.8 KB
- 参考文档rules/commit-and-pr-guideline.md16.2 KB
- 参考文档rules/configure.md5.1 KB
- 参考文档rules/contributing.md11.1 KB
- 参考文档rules/crypto-internals.md11.6 KB
- 参考文档rules/debugging-native.md7.9 KB
- 参考文档rules/documentation.md10.6 KB
- 参考文档rules/fs-internals.md10.5 KB
- 参考文档rules/libuv-async-io.md10.6 KB
- 参考文档rules/libuv-event-loop.md11.1 KB
- 参考文档rules/libuv-thread-pool.md10.4 KB
- 参考文档rules/memory-debugging.md11.7 KB
- 参考文档rules/napi.md14.0 KB
- 参考文档rules/native-memory.md11.9 KB
- 参考文档rules/net-internals.md13.8 KB
- 参考文档rules/node-addon-api.md14.6 KB
- 参考文档rules/pre-commit-lint.md11.2 KB
- 参考文档rules/primordials.md12.6 KB
- 参考文档rules/profiling-v8.md9.8 KB
- 参考文档rules/reviewing-prs.md10.3 KB
- 参考文档rules/streams-internals.md11.7 KB
- 参考文档rules/v8-garbage-collection.md10.9 KB
- 参考文档rules/v8-hidden-classes.md9.2 KB
- 参考文档rules/v8-jit-compilation.md10.2 KB
- 参考文档rules/worker-threads-internals.md13.3 KB
- 参考文档tile.json355 B
03 SKILL.md 正文
When to use
Use this skill when you need deep Node.js internals expertise, including:
- C++ addon development
- V8 engine debugging
- libuv event loop issues
- Build system problems
- Compilation failures
- Performance optimization at the engine level
- Understanding Node.js core architecture
- Writing or reviewing
nodejs/nodecommits and pull request descriptions
How to use
Read individual rule files for detailed explanations and code examples:
V8 Engine
- rules/v8-garbage-collection.md - Scavenger, Mark-Sweep, Mark-Compact, generational GC
- rules/v8-hidden-classes.md - Hidden classes, inline caching, optimization
- rules/v8-jit-compilation.md - TurboFan, optimization/deoptimization patterns
libuv
- rules/libuv-event-loop.md - Event loop phases, timers, I/O, idle, check, close
- rules/libuv-thread-pool.md - Thread pool size, blocking operations, UV_THREADPOOL_SIZE
- rules/libuv-async-io.md - Async I/O patterns, handles, requests
Native Addons
- rules/napi.md - N-API development, ABI stability, async workers
- rules/node-addon-api.md - C++ wrapper patterns, best practices
- rules/native-memory.md - Buffer handling, external memory, prevent leaks
Core Modules Internals
- rules/streams-internals.md - How Node.js streams work at C++ level
- rules/net-internals.md - TCP/UDP implementation, socket handling
- rules/fs-internals.md - libuv fs operations, sync vs async
- rules/crypto-internals.md - OpenSSL integration, performance considerations
- rules/child-process-internals.md - IPC, spawn, fork implementation
- rules/worker-threads-internals.md - SharedArrayBuffer, Atomics, MessageChannel
JavaScript Internals
- rules/primordials.md - Using primordials to prevent prototype pollution (required for
lib/internal/)
Build & Contributing
- rules/build-and-test-workflow.md - The edit-build-lint-test cycle (start here)
- rules/pre-commit-lint.md - Mandatory lint, format, and
core-validate-commitgate for every commit so CI passes first time - rules/configure.md -
./configureflags for debug builds, ASan, Ninja, etc. - rules/build-system.md - gyp, ninja, make, cross-platform compilation
- rules/cli-options.md - Adding CLI options and gating experimental modules
- rules/contributing.md - How to contribute to Node.js core, the process
- rules/commit-and-pr-guideline.md - Commit message and PR description style, trailers, DCO sign-off, and validation
- rules/reviewing-prs.md - Reviewing PRs for correctness, clarity, and contribution quality
Documentation
- rules/documentation.md - Updating doc/api/*.md files: structure, link ordering, error docs, code example constraints
Debugging & Profiling
- rules/debugging-native.md - gdb, lldb, debugging C++ addons
- rules/profiling-v8.md - --prof, --trace-opt, --trace-deopt, flame graphs
- rules/memory-debugging.md - Heap snapshots, memory leak detection
Instructions
Node.js contribution writing
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.
See rules/build-and-test-workflow.md for the full workflow including configure flags, lint targets, and test commands.
Core knowledge domains
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
- Build systems: node-gyp, gyp, ninja, make; cross-platform compilation; linker errors; dependency issues; platform-specific considerations (Windows, macOS, Linux, embedded)
- Performance & debugging: Event loop profiling, memory leak detection in JS and native code, CPU flame graphs, V8 optimization/deoptimization tracing
Quick-reference debugging commands
V8 optimization tracing:
node --trace-opt --trace-deopt script.js
# Checkpoint: confirm no unexpected deoptimization warnings before proceeding to profiling
node --prof script.js && node --prof-process isolate-*.log > processed.txt
Event loop lag detection:
node --trace-event-categories v8,node,node.async_hooks script.js
Native addon debugging (gdb):
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? → Rungdb, capturebt - Does
btpoint to a V8 handle scope issue? → CheckHandleScope/EscapableHandleScopeusage 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-optto confirm the function is now optimized
Build failure (node-gyp / binding.gyp):
- Is it a missing header? → Verify
include_dirsinbinding.gypand Node.js header installation - Is it a linker error? → Check
librariesandlink_settingsentries; confirm ABI compatibility - Is it platform-specific? → Consult
rules/build-system.mdfor 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.
04 同仓库更多 Skills
youtube-transcript
Extract transcripts from YouTube videos. Use when the user asks for a transcript, subtitles, or captions of a YouTube video and provides a YouTube URL (youtube.com/watch?v=, youtu.be/, or similar). Supports output with or without timestamps.
youtube-thumbnail-design
YouTube thumbnail design with specific dimensions, contrast rules, and mobile preview optimization. Covers safe zones, text placement, face expression psychology, and A/B testing. Use for: YouTube thumbnails, video cover images, click-through optimization. Triggers: youtube thumbnail, thumbnail design, video thumbnail, click through rate, ctr optimization, youtube cover, video cover image, thumbnail maker, thumbnail tips, youtube design, video preview image
youtube-short-maker
Make YouTube Shorts that hold attention with Pexo — vertical 9:16, fast-paced, hook in the first 3 seconds. Describe your topic and Pexo writes the script, generates the shots, picks the models, and assembles a finished Short with music and captions. Use for YouTube Shorts: "youtube short", "make a youtube short", "shorts video", "short-form video". NOT for long-form or landscape video.
xcode-project-setup
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
x402
Set up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key. Two setups it works out up front — "just use it" (set up a wallet so you or Claude Code can run cloud browser tasks paid from the wallet — Claude writes and runs throwaway scripts, nothing touches your codebase) or "build it in" (install the SDK and write the key + code into your project). Walks through wallet setup, funding, .env, and a ~$1 test run. Use when the user asks about x402, pay-per-use, USDC payments, or wants Browser Use Cloud without an API key. For the free-tier signup (reverse-CAPTCHA → API key), use `browser-use cloud signup` or the `cloud` skill instead.
x-twitter-scraper
Build GitHub Copilot workflows with Xquik X API SDKs, REST endpoints, hosted Apify Actor runs, MCP tools, TweetClaw OpenClaw plugin installs, signed webhooks, tweet search, user lookup, follower exports, media actions, and agent automation.