Stop agents documenting helper exports and implementation details

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

@@ -12,6 +12,7 @@ Release Drafter turns PR titles into release notes and labels into the version b
 - Branch from an up-to-date `main`.
 - Run the checks in AGENTS.md "Verification". For bug fixes, keep the red-green output.
 - Check that `git diff --stat main...HEAD` shows only the files you intended, and that the lockfile changes only the entries you intended.
+- If the diff touches `docs/`, AGENTS.md or a skill, check it against AGENTS.md "API and docs": docs only for a user-facing change and only how to use it, and no lines about your own feature in AGENTS.md or a skill.
 
 ## Commit and push
 

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

@@ -35,7 +35,9 @@ gh pr checks <N>
 - **Concurrency:** no shared containers, `process.env` or spies without `{ concurrent: false }`. Use `await using`. No skipping when Docker is unavailable.
 - **Root cause:** a fix removes the cause of the failure. Added sleeps, retries or longer timeouts only make it less likely (AGENTS.md).
 - **Completeness:** a fix applied to one path is also applied to its siblings, for example `restart()` next to `start()`, or the reuse path next to the create path.
-- **Docs:** public API changes are documented, and module examples use `codeinclude`. Check that each marker name appears only once in its test file; CI can't catch a collision (AGENTS.md).
+- **Docs:**
+  - User-facing API changes are documented. Flag docs for helpers that only modules use, and docs that explain how a feature is implemented instead of how to use it (AGENTS.md "API and docs").
+  - Module examples use `codeinclude`. Check that each marker name appears only once in its test file; CI can't catch a collision (AGENTS.md).
 - **Design:**
   - 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).
@@ -45,6 +47,7 @@ gh pr checks <N>
   - 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.
   - Flag code comments that restate the code or describe the change (AGENTS.md).
+  - Flag lines added to AGENTS.md or a skill that only describe the PR's own feature (AGENTS.md "Purpose").
 - **Dependencies:** runtime dependencies load from CommonJS (AGENTS.md), and well-established libraries or built-ins are preferred.
 - **Breaking changes:** renamed exports, changed defaults and lowered timeouts all count. They need `major` or a non-breaking alternative.
 - **Claims:** check root-cause explanations, and claims about what another Testcontainers implementation does, against the actual code. AI-written PR descriptions are often confidently wrong.

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

@@ -16,7 +16,13 @@ Biome enforces the lint and formatting rules (`biome.json`). This skill covers w
 
 - 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.
+- 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. A helper exported for modules gets no docs.
+
+## Before touching docs
+
+- Change `docs/` only when what a user calls changes: a new option, method or module, or behaviour they have to account for (AGENTS.md "API and docs").
+- Show how to use it and stop. How it works and why it changed go in the PR body.
+- Don't add a line about your change to AGENTS.md or a skill.
 
 ## Use what core provides
 

AGENTS.md

@@ -7,6 +7,7 @@ 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 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.
+Wrong or incomplete means a rule misled you, or a mistake keeps recurring that no rule covers. Adding a feature, helper or option is not a reason to add a line about it here or in a skill.
 
 ## Repository Layout
 
@@ -22,7 +23,11 @@ If a skill or this file turns out to be wrong or incomplete, update it in the sa
 
 ### API and docs
 
-- If a public API changes, update the relevant docs in the same PR.
+- If a user-facing API changes, update the relevant docs in the same PR.
+  - User-facing means what someone testing against a container uses: containers, images, networks, Compose, wait strategies, and modules and their options.
+  - Don't document helpers that `index.ts` exports so that modules can import them (for example `log`, `RandomUuid`, `BoundPorts`). Being exported makes them public API, not a docs topic.
+- Docs tell a user how to use a feature: what to call, a short example, and anything they have to account for.
+  - Leave out how it is implemented: which Docker calls are made, timing and retry mechanics, and why the change was made. That belongs in the PR body.
 - If new types are made part of the public API, export them from the package's `index.ts` in the same PR.
 - Only what a package's `index.ts` exports is public API. `npm run knip` fails on any other export that no other file uses: drop the `export` keyword, or export it from `index.ts` if consumers need it.
 - In docs Markdown, keep `<!--codeinclude-->` blocks tight with no blank lines between the markers and the include line, or the rendered snippet will contain blank lines between code lines.