diff --git a/.claude/skills/playwright-roll/SKILL.md b/.claude/skills/playwright-roll/SKILL.md
index 323a13926..7a37f386f 100644
--- a/.claude/skills/playwright-roll/SKILL.md
+++ b/.claude/skills/playwright-roll/SKILL.md
@@ -164,39 +164,3 @@ When you've identified a hanging test:
 1. Run it in isolation: `mvn -f playwright/pom.xml test -Dtest='TestClass#testMethod'`. If it passes alone, it's a parallel-load flake — note it but move on.
 2. If it still hangs in isolation, look for a recent fix in the upstream repo for the *same* test name. Use `git log --oneline tests/library/<spec>.spec.ts` in `~/playwright`. Upstream fixes for client-side hangs are often small and portable (e.g. `about:blank` → `server.EMPTY_PAGE` from microsoft/playwright#39840 fixed `route-web-socket.spec.ts` arraybuffer hangs — apparently some browser changed the WebSocket origin policy on `about:blank`).
 3. When porting an upstream fix, mirror the helper signature change rather than hard-coding workarounds. E.g. if upstream added a `server` parameter to `setupWS`, do the same in Java by injecting `Server server` via the JUnit fixture (`@FixtureTest` already wires up `ServerLifecycle`, so adding `Server server` to the test method signature is enough — no class-level boilerplate). Watch for local-variable shadowing when you add a `Server server` parameter to a method that already has a `WebSocketRoute server` local; rename the local.
-
-## Commit Convention
-
-Semantic commit messages: `label(scope): description`
-
-Labels: `fix`, `feat`, `chore`, `docs`, `test`, `devops`
-
-```bash
-git checkout -b fix-39562
-# ... make changes ...
-git add <changed-files>
-git commit -m "$(cat <<'EOF'
-fix(proxy): handle SOCKS proxy authentication
-
-Fixes: https://github.com/microsoft/playwright-java/issues/39562
-EOF
-)"
-git push origin fix-39562
-gh pr create --repo microsoft/playwright-java --head username:fix-39562 \
-  --title "fix(proxy): handle SOCKS proxy authentication" \
-  --body "$(cat <<'EOF'
-## Summary
-- <describe the change very! briefly>
-
-Fixes https://github.com/microsoft/playwright-java/issues/39562
-EOF
-)"
-```
-
-Never add Co-Authored-By agents in commit message.
-Never add "Generated with" in commit message.
-Branch naming for issue fixes: `fix-<issue-number>`
-
-## Tips & Tricks
-- Project checkouts are in the parent directory (`../`).
-- use the "gh" cli to interact with GitHub
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..1433460ef
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# Playwright Java
+
+The Java client is a port of the JavaScript client in `../playwright/packages/playwright-core/src/client/`. When implementing or changing a method, read the corresponding JS file first and mirror its logic.
+
+Project checkouts (including the upstream `playwright` repo) live in the parent directory (`../`). Use the `gh` cli to interact with GitHub.
+
+## Commit Convention
+
+Semantic commit messages: `label(scope): description`
+
+Labels: `fix`, `feat`, `chore`, `docs`, `test`, `devops`
+
+```bash
+git checkout -b fix-39562
+# ... make changes ...
+git add <changed-files>
+git commit -m "$(cat <<'EOF'
+fix(proxy): handle SOCKS proxy authentication
+
+Fixes: https://github.com/microsoft/playwright-java/issues/39562
+EOF
+)"
+# **Never `git push` without an explicit instruction to push.**
+git push origin fix-39562
+gh pr create --repo microsoft/playwright-java --head <user>:fix-39562 \
+  --title "fix(proxy): handle SOCKS proxy authentication" \
+  --body "$(cat <<'EOF'
+## Summary
+- <describe the change very! briefly>
+
+Fixes https://github.com/microsoft/playwright-java/issues/39562
+EOF
+)"
+```
+
+Never add Co-Authored-By agents in commit message.
+Never add "Generated with" in commit message.
+Never add test plan to PR description. Keep PR description short — a few bullet points at most.
+Branch naming for issue fixes: `fix-<issue-number>`.
+
+**Never amend commits.** Always create a new commit for follow-up changes, even when iterating on an open PR. Amending rewrites history and forces a force-push, losing the incremental review trail. Only amend if the user explicitly says so.
+
+**Never `git push` without an explicit instruction to push.** Applies even when a PR is already open for the branch — additional commits are immediately visible to reviewers. Commit locally, report what was committed, and wait. Only push when the user's message contains "push", "upload", "create PR", "ship it", or equivalent.
+
+## Skills
+
+- **playwright-roll** (`.claude/skills/playwright-roll/SKILL.md`) — roll Playwright Java to a new upstream version: bump the driver, regenerate the API, and port relevant upstream changes.
+- **playwright-java-release** (`.claude/skills/playwright-java-release/SKILL.md`) — prepare a release after the rolling PR merges: cut the release branch, mark the Maven version, and draft the GitHub release.