Add agent skills for recurring repo workflows

[cristianrgreco]

Summary

Moves the step-by-step workflows out of AGENTS.md into seven repository skills. They live in .agents/skills/, where Codex reads them, and .claude/skills/ symlinks each one so Claude Code reads them too:

Skill	Covers
open-pr	Verify, commit, push and open a PR, with title, label and PR body conventions, and a publish dry run for risky changes
review-pr	Review a PR against recurring review feedback and draft inline comments for approval
add-module	Conventions for a new module: container class, tests, image pin, docs
triage-issue	Check what's missing, search the source, issues, PRs and docs for an existing answer, verify claims, reproduce, write the failing test, draft a reply
diagnose-ci	Read the failed step and the workflow behind it, compare with main and the last green run, search past PRs and issues, reproduce, then fix or route
update-dependencies	Find the bump that broke a Dependabot PR, then adapt, hold back or ignore it; replace images that no longer pull; npm audit passes
review-release	Review of the draft release before a maintainer publishes it: labels, version bump, titles, hidden breaking changes, and a publish dry run when it has permission

The skill content comes from:

• review feedback on about 60 past PRs
• about 25 issues
• the Dependabot, npm audit and release history

triage-issue, diagnose-ci and update-dependencies deliberately have no list of known causes. Such lists go stale, as the Bun/Ryuk workaround already had, so the skills send the agent to the source, the workflow files, the failing bump, past issues and PRs, and docs/ instead.

AGENTS.md now holds only the rules that apply to every task:

• PR process, labels and review style moved to open-pr and review-pr.
• Removed "Instruction precedence" and the branch-prefix rule.
• Grouped "Development Expectations" under API and docs, Code, Dependencies and Tests. The rules that merged into main while this PR was open (root cause, test images, codeinclude marker names, import boundaries, public API exports) keep their text, and the skills point to them where they apply.
• Added "Verification" and "Git and GitHub" sections. The first lists the checks to run, including npm run knip. The second keeps the approval gate, signing and force-push rules. open-pr and update-dependencies repeat the signing and force-push rules where they commit.
• Added a "Releases" section: agents never publish, never run npm publish without --dry-run, and never edit releases. A maintainer releases by publishing the draft. Agents with permission dispatch the npm-publish.yml dry run: open-pr for large, possibly breaking or release-affecting changes, and review-release on main before a release. Without permission, they ask a maintainer to run it.
• "Cross-language Implementations" now links the org's repositories and says to check more than one implementation. The skills point there instead of naming Java and Go.
• Added the module image-pinning rule, including the catch that Dependabot collapses FROM lines for the same image.
• Added the rule that runtime dependencies must load from CommonJS.
• Added a rule to keep code comments to a minimum: only where they say something the code, the PR and the git history don't. review-pr flags comments that restate the code or describe the change.
• Fixed the Vitest guidance: Vitest 5 has no .sequential modifier, so it now says { concurrent: false }.

The bug report template now asks for:

• DEBUG=testcontainers* logs, and how to collect them
• the container runtime and its version
• the test runner, and whether the project is CJS or ESM
• the module and image
• the last working version

CONTRIBUTING.md no longer tells contributors to run the Git hooks that were removed with Husky. It now gives the format, lint, knip and targeted test commands and the PR title convention, and points at AGENTS.md and the skills.

add-module ends with listing the new module in the catalog at testcontainers.com/modules, through a PR to testcontainers/community-module-registry. Six recent modules never got that entry.

Verification

Skill format. Checked against Claude's skill authoring best practices:

• Every SKILL.md frontmatter parses with js-yaml, each name matches its folder, and each has a .claude/skills symlink that resolves.
• Names are verb-noun throughout.
• Descriptions are third person, 280–450 characters, with no XML tags.
• Files are 40–70 lines.

Symlinks. Claude Code's skills docs say a .claude/skills/<name> entry can be a symlink to a directory elsewhere. The symlinks are committed as git symlinks (mode 120000). Codex reads .agents/skills directly.

Test runs. Fresh subagents ran two skills, read-only, using the first version of each. The skills were then tightened from what they reported. triage-issue and diagnose-ci were reworked again in review, when their lists of known causes were replaced with working from the source, the run and past issues.

• review-pr on PR 1447 independently raised the points from the maintainer's own review:

  • the restart() path is untouched
  • a test that fails without the fix is needed

  It also flagged:

  • lower timeouts are a breaking change
  • an exited container makes the port wait hang until the timeout
  • fork CI that is waiting for approval looks green

• triage-issue on issue 1442 reproduced the leak with testcontainers-python 4.15.0 alongside a Node suite. It traced the cause to the Python binding force-removing its Ryuk, which corrects the session-id explanation in the report. It also checked a one-line lang=node filter red-green in reaper.test.ts, then reverted it.

CI. changed-modules.mjs selects no packages for these paths, so Checks runs only Lint and Docs. Compile, the smoke tests and Tests are skipped.

Skill discovery. A fresh Claude Code 2.1.283 session on the PR head lists all seven skills through the .claude/skills symlinks.

Not breaking

This only touches docs, agent configuration and the issue template. No package source, manifest or lockfile changed.

[netlify]

✅ Deploy Preview for testcontainers-node ready!

Name	Link
🔨 Latest commit	aa81c72
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-node/deploys/6ac7f08713700000081d9033
😎 Deploy Preview	https://deploy-preview-1486--testcontainers-node.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[cristianrgreco]

@claude Push access is fixed (#1493). Please apply the pending changes from these review threads in one run and push. Where threads overlap, follow the order below.

1. publish-release → review-release: go ahead with your proposal. Keep the read-only review-release skill (rename the folder and the .claude/skills symlink, drop disable-model-invocation), make open-pr lines 17–21 the single "say so in the PR body" bullet, add the ## Releases section to AGENTS.md, and update the PR description. If you can't edit the description, post the new text in your reply.
2. publish-release line 60: superseded by 1. Don't apply the publish-release rewrite.
3. open-pr line 21, forks: the fork dry-run wording is superseded by 1. Leave labels alone: don't add the triage/labels line, the reviewer sets them.
4. open-pr line 54: remove the --body-file note, keep --body-file <path> in the example command.
5. triage-issue tables: go ahead with your proposed replacement for lines 11–47, the renumbering and the description change. This supersedes the Bun row edit in the line 42 thread.
6. Signing rule, AGENTS.md:92: go ahead with your proposed edits to open-pr, update-dependencies and diagnose-ci. Keep AGENTS.md lines 92–93 as they are.

[claude]

Claude finished @cristianrgreco's task in 4m 4s —— View job

---

Applied and pushed the review changes in 980ac70. One symlink still needs adding

• Read the current skills, AGENTS.md and the working tree state
• 1. Replaced publish-release with the read-only review-release skill, without disable-model-invocation
• 1. Rename the .claude/skills symlink. I removed publish-release but couldn't add review-release (see below)
• 1. Made open-pr lines 17–21 the single "say so in the PR body" bullet
• 1. Added ## Releases to AGENTS.md, and line 8 now says "release review"
• 2. Didn't apply the publish-release rewrite
• 3. Left labels alone. No triage/labels line, no fork dry-run wording.
• 4. Removed the --body-file note, and kept --body-file <path> in the example
• 5. Replaced triage-issue lines 11–47, renumbered sections 3–6, and updated the description. The Bun row went with the table.
• 6. open-pr has a new "Commit and push" section, and git push is gone from its final code block. Updated update-dependencies (signing/force-push, open-pr for the audit PR) and diagnose-ci (step 4). AGENTS.md lines 92–93 are unchanged.
• Commit and push
• Update the PR description: I couldn't. The new text is below.

Please add the review-release symlink

The action's checkout has no .claude/ directory. This run also isn't allowed to create a symlink or write a symlink entry into the index: mkdir .claude, ln -s, git update-index and git apply --cached all need permissions it doesn't have.

So the commit removes .claude/skills/publish-release, to avoid leaving a link to a folder that no longer exists, but doesn't add .claude/skills/review-release. Until that link is added, Claude Code won't list review-release. Codex reads .agents/skills directly, so it isn't affected. From a local checkout of the branch:

ln -s ../../.agents/skills/review-release .claude/skills/review-release
git add .claude/skills/review-release
git commit -m "Link the review-release skill for Claude Code"

The other six symlinks are unchanged on the branch.

Notes

• Where ## Releases sits. It comes after the @claude Action section, so it's clearly not one of the "Git and GitHub" rules that section replaces. That way it applies to the Action too.
• review-release is the draft from the earlier thread, unchanged. I checked its one factual change against .github/release-drafter.yml: there are no exclude-labels, so a PR without a type label is listed uncategorised rather than dropped.
• Left as is: the "Only Podman jobs red… Known Podman slowness" row in diagnose-ci, which I'd offered to drop. You didn't ask for that.

Checks

npm isn't available in the Action, so I couldn't run format or lint, or parse the new review-release frontmatter with js-yaml. The changes are Markdown only. Counted by hand:

• The triage-issue description is now 449 characters, just inside the 450 the PR body states.
• The review-release description is about 340 characters.
• Skill files are now 30–65 lines long.

New PR description

## Summary

Moves the step-by-step workflows out of `AGENTS.md` into seven repository skills. They live in `.agents/skills/`, where Codex reads them, and `.claude/skills/` symlinks each one so Claude Code reads them too:

| Skill | Covers |
| --- | --- |
| `open-pr` | Verify, commit, push and open a PR, with title, label and PR body conventions |
| `review-pr` | Review a PR against recurring review feedback and draft inline comments for approval |
| `add-module` | Conventions for a new module: container class, tests, image pin, docs |
| `triage-issue` | Check what's missing, search the source, issues, PRs and docs for an existing answer, verify claims, reproduce, write the failing test, draft a reply |
| `diagnose-ci` | Read the job-matrix pattern, separate flakes from regressions, fix flaky tests |
| `update-dependencies` | Known Dependabot failure shapes, moved or deleted images, npm audit passes |
| `review-release` | Read-only review of the draft release before a maintainer publishes it: labels, version bump, titles, hidden breaking changes |

The skill content comes from:

- review feedback on about 60 past PRs
- about 25 issues
- the Dependabot, npm audit and release history

`triage-issue` deliberately has no list of known causes. Such lists go stale, as the Bun/Ryuk workaround already had, so the skill sends the agent to the source, past issues and PRs, and `docs/` instead.

`AGENTS.md` now holds only the rules that apply to every task:

- PR process, labels and review style moved to `open-pr` and `review-pr`.
- Removed "Instruction precedence" and the branch-prefix rule.
- Added "Verification" and "Git and GitHub" sections. The second keeps the approval gate, signing and force-push rules. `open-pr` and `update-dependencies` repeat the signing and force-push rules where they commit.
- Added a "Releases" section: agents never publish, never dispatch `npm-publish.yml` (including its dry run), and never edit releases. A maintainer releases by publishing the draft. `open-pr` asks the author to flag changes that need a maintainer dry run.
- Added the module image-pinning rule, including the catch that Dependabot collapses `FROM` lines for the same image.
- Added the rule that runtime dependencies must load from CommonJS.
- Fixed the Vitest guidance: Vitest 5 has no `.sequential` modifier, so it now says `{ concurrent: false }`.

The bug report template now asks for:

- `DEBUG=testcontainers*` logs, and how to collect them
- the container runtime and its version
- the test runner, and whether the project is CJS or ESM
- the module and image
- the last working version

## Verification

**Skill format.** Checked against Claude's skill authoring best practices:

- Each name matches its folder. The original seven frontmatters parse with js-yaml. `review-release` was added during review and checked by hand.
- Names are verb-noun throughout.
- Descriptions are third person, 280–450 characters, with no XML tags.
- Files are 30–65 lines.

**Symlinks.** Claude Code's skills docs say a `.claude/skills/<name>` entry can be a symlink to a directory elsewhere. The symlinks are committed as git symlinks (mode `120000`). Codex reads `.agents/skills` directly.

**Test runs.** Fresh subagents ran two skills, read-only, using the first version of each. The skills were then tightened from what they reported:

- `review-pr` on PR 1447 independently raised the points from the maintainer's own review:
  - the `restart()` path is untouched
  - a test that fails without the fix is needed

  It also flagged:
  - lower timeouts are a breaking change
  - an exited container makes the port wait hang until the timeout
  - fork CI that is waiting for approval looks green
- `triage-issue` on issue 1442 reproduced the leak with testcontainers-python 4.15.0 alongside a Node suite. It traced the cause to the Python binding force-removing its Ryuk, which corrects the session-id explanation in the report. It also checked a one-line `lang=node` filter red-green in `reaper.test.ts`, then reverted it.

**CI.** `changed-modules.mjs` selects no packages for these paths, so Checks runs no package jobs.

**Not yet verified:** that a fresh Claude Code session lists the skills. The session that wrote them started before `.claude/skills` existed, and `/reload-skills` didn't pick them up.

## Not breaking

This only touches docs, agent configuration and the issue template. No package source, manifest or lockfile changed.

· [Branch `claude/repo-skills-audit-83c819`](https://github.com/testcontainers/testcontainers-node/tree/claude/repo-skills-audit-83c819)