Add a write-code skill for code conventions

.agents/skills/add-module/SKILL.md

@@ -25,6 +25,7 @@ For the container class, tests and docs page, start from the module closest in s
 - Started-container getters call `getMappedPort()` when they're invoked. A restarted container can get different host ports.
 - Incompatible major versions (different ports, auth or startup) get separate classes, not image-tag parsing.
 - Keep it small: no getters that exist only for tests, and no speculative options.
+- Write the class following `write-code`.
 
 ## Tests
 

.agents/skills/review-pr/SKILL.md

@@ -40,6 +40,7 @@ gh pr checks <N>
   - Zero-config defaults work, and invalid or half-set config fails fast.
   - The wait strategy is set in the constructor, and waits are robust (listening ports, health check or HTTP rather than log regexes).
   - Images are pinned in the module `Dockerfile`.
+- **Style:** new code follows `write-code`.
 - **Scope:**
   - Flag new files for a few lines of logic, dead fallbacks, duplicated constants, getters that exist only for tests, and tests of third-party behaviour.
   - Flag unrelated dependency bumps; leave those to Dependabot.

.agents/skills/write-code/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: write-code
+description: Writes and refactors TypeScript in testcontainers-node by reusing what the project already has (existing helpers, shared functions, core's building blocks) instead of adding another copy. Use when writing, changing or refactoring code under packages/, e.g. "add an option to the Kafka module", "fix this bug", "add a wait for X", and when review feedback says code is duplicated or should be refactored.
+---
+
+# Write code
+
+Biome enforces the lint and formatting rules (`biome.json`). This skill covers what a linter can't see. The most common review finding is new code that repeats something the project already has.
+
+## Before adding code
+
+- Search for code that already does it: in the file, in the package, and in what `testcontainers` exports (`packages/testcontainers/src/index.ts`). If it exists, use it.
+- If something close exists, change it so it serves both callers. Don't copy it and adapt the copy.
+
+## When the same code is needed twice
+
+- In one file, extract a helper: a private method, or a function the file doesn't export. Define it below the first function that calls it.
+- Across files in a package, move it into a function in its own file.
+- Across modules, it belongs in core, exported from `testcontainers`, because modules can't import each other. That adds public API, so propose it instead of copying the code.
+
+## Use what core provides
+
+- Configure containers through the `with*` methods. Don't assign to `this.createOpts` or `this.hostConfig`.
+- Wait with a `WaitStrategy` run through `waitForContainer`. Don't call `waitUntilReady` on a strategy or write a polling loop.
+- A wait added after start gets what is left of the user's startup timeout, never a fresh one.

.claude/skills/write-code

@@ -0,0 +1 @@
+../../.agents/skills/write-code

AGENTS.md

@@ -5,7 +5,7 @@
 This is a working guide for contributors and coding agents in this repository.
 It captures practical rules that prevent avoidable CI and PR churn.
 
-This file holds the rules for every task. Workflows live in skills under `.agents/skills/`, which Claude Code reads through symlinks in `.claude/skills/`. They cover opening and reviewing PRs, adding modules, issue triage, CI and dependency maintenance, and release review.
+This file holds the rules for every task. Workflows live in skills under `.agents/skills/`, which Claude Code reads through symlinks in `.claude/skills/`. They cover writing code, opening and reviewing PRs, adding modules, issue triage, CI and dependency maintenance, and release review.
 If a skill or this file turns out to be wrong or incomplete, update it in the same PR.
 
 ## Repository Layout
@@ -30,6 +30,7 @@ If a skill or this file turns out to be wrong or incomplete, update it in the sa
 
 ### Code
 
+- Follow the `write-code` skill when writing or changing code under `packages/`.
 - Keep code comments to a minimum; the codebase has very few. Add one only when it tells the reader something they can't get from the code, the PR or the git history, such as why a non-obvious approach was needed, or a link to an upstream bug.
   - Don't narrate what the code does, describe the change you made, or reference the task or review that prompted it.
 - Fix the root cause. A change that only makes a failure less likely is not a fix.