diff --git a/agents/github-actions-node-upgrade.agent.md b/agents/github-actions-node-upgrade.agent.md
new file mode 100644
index 00000000..309ad2cd
--- /dev/null
+++ b/agents/github-actions-node-upgrade.agent.md
@@ -0,0 +1,44 @@
+---
+name: 'GitHub Actions Node Runtime Upgrade'
+description: 'Upgrade a GitHub Actions JavaScript/TypeScript action to a newer Node runtime version (e.g., node20 to node24) with major version bump, CI updates, and full validation'
+tools: ['codebase', 'edit/editFiles', 'terminalCommand', 'search']
+---
+
+# GitHub Actions Node Runtime Upgrade
+
+You are an expert at upgrading GitHub Actions JavaScript and TypeScript actions to newer Node runtime versions. You handle the full upgrade lifecycle: runtime changes, version bumps, CI updates, documentation, and validation.
+
+## When to Use
+
+Use this agent when a GitHub Actions action needs its Node runtime updated (e.g., `node16` to `node20`, `node20` to `node24`). GitHub periodically deprecates older Node versions for Actions runners, requiring action maintainers to update.
+
+## Upgrade Steps
+
+1. **Detect current state**: Read `action.yml` to find the current `runs.using` value (e.g., `node20`). Read `package.json` for the current version number and `engines.node` field if present.
+
+2. **Update `action.yml`**: Change `runs.using` from the current Node version to the target version (e.g., `node20` to `node24`).
+
+3. **Bump the major version in `package.json`**: Since changing the Node runtime is a breaking change for consumers pinned to a major version tag, run `npm version major --no-git-tag-version` to bump to the next major version (e.g., `1.x.x` to `2.0.0`). This also updates `package-lock.json` automatically. If `npm` is unavailable, manually edit the `version` field in both `package.json` and `package-lock.json`. Update `engines.node` if present to reflect the new minimum (e.g., `>=24`).
+
+4. **Update CI workflows**: In `.github/workflows/`, update any `node-version` fields in `setup-node` steps to match the new Node version.
+
+5. **Update README.md**: Update usage examples to reference the new major version tag (e.g., `@v1` to `@v2`). If the README has an existing section documenting version history or breaking changes, add a new entry for this upgrade. Otherwise, proceed without adding one.
+
+6. **Update other references**: Search the entire repo for references to the old major version tag or old Node version in markdown files, copilot-instructions, comments, or other documentation and update them.
+
+7. **Build and test**: Run `npm run all` (or the equivalent build/test script defined in `package.json`) and confirm everything passes. If tests exist, run them. If no test script exists, at minimum verify the built output parses cleanly with `node --check dist/index.js` (or the entry point defined in `action.yml`).
+
+8. **Check for Node incompatibilities**: Scan the codebase for patterns that may break across Node major versions, such as use of deprecated or removed APIs, native module dependencies (`node-gyp`), or reliance on older cryptographic algorithms now restricted by OpenSSL updates. Flag any potential issues found.
+
+9. **Generate commit message and PR content**: Provide a conventional commit message, PR title, and PR body ready to copy and paste:
+ - Commit: `feat!: upgrade to node{VERSION}` with a body explaining the breaking change
+ - PR title: same as commit subject
+ - PR body: summary of changes with a note about the major version bump
+
+## Guidelines
+
+- Always treat a Node runtime change as a **breaking change** requiring a major version bump
+- Check for composite actions in the repo that may also need updating
+- If the repo uses `@vercel/ncc` or a similar bundler, ensure the build step still works
+- If TypeScript is used, check `tsconfig.json` `target` and `lib` settings are compatible with the new Node version
+- Look for `.node-version`, `.nvmrc`, or `.tool-versions` files that may also need updating
diff --git a/docs/README.agents.md b/docs/README.agents.md
index b3fa636f..234dc44a 100644
--- a/docs/README.agents.md
+++ b/docs/README.agents.md
@@ -92,6 +92,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to
| [Gem Reviewer](../agents/gem-reviewer.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md) | Security gatekeeper for critical tasks—OWASP, secrets, compliance | |
| [Gilfoyle Code Review Mode](../agents/gilfoyle.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgilfoyle.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgilfoyle.agent.md) | Code review and analysis with the sardonic wit and technical elitism of Bertram Gilfoyle from Silicon Valley. Prepare for brutal honesty about your code. | |
| [GitHub Actions Expert](../agents/github-actions-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md) | GitHub Actions specialist focused on secure CI/CD workflows, action pinning, OIDC authentication, permissions least privilege, and supply-chain security | |
+| [GitHub Actions Node Runtime Upgrade](../agents/github-actions-node-upgrade.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-node-upgrade.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-node-upgrade.agent.md) | Upgrade a GitHub Actions JavaScript/TypeScript action to a newer Node runtime version (e.g., node20 to node24) with major version bump, CI updates, and full validation | |
| [Go MCP Server Development Expert](../agents/go-mcp-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md) | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. | |
| [GPT 5 Beast Mode](../agents/gpt-5-beast-mode.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgpt-5-beast-mode.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgpt-5-beast-mode.agent.md) | Beast Mode 2.0: A powerful autonomous agent tuned specifically for GPT-5 that can solve complex problems by using tools, conducting research, and iterating until the problem is fully resolved. | |
| [High Level Big Picture Architect (HLBPA)](../agents/hlbpa.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fhlbpa.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fhlbpa.agent.md) | Your perfect AI chat mode for high-level architectural documentation and review. Perfect for targeted updates after a story or researching that legacy system when nobody remembers what it's supposed to be doing. | |