chore: update llm instructions, add skills, and multi-agent roles

.agents/skills/README.md

@@ -0,0 +1,34 @@
+# Repository Skills
+
+This directory contains repository-scoped Codex Skills for repeatable SDK workflows.
+
+These skills do not redefine policy. They orchestrate checks using the canonical contributor contracts in [`AGENTS.md`](../../AGENTS.md) and [`llm/README.md`](../../llm/README.md).
+
+## Available Skills
+
+1. `api-surface-gate`
+- Purpose: Prevent accidental public API breakage across exports, entrypoints, and exported types.
+- Trigger summary: Export map or API-entrypoint/type-surface changes.
+
+2. `adapter-parity-check`
+- Purpose: Keep ethers and viem adapter behavior aligned with core abstractions.
+- Trigger summary: Core changes or one-adapter-only behavior changes.
+
+3. `sdk-verification-matrix`
+- Purpose: Select required verification loops for each change scope.
+- Trigger summary: PR completion, CI failures, and test-debugging tasks.
+
+4. `contract-interaction-patterns`
+- Purpose: Enforce ABI-derived correctness for contract wrappers/clients and event/log decoding.
+- Trigger summary: ABI edits, calldata/method mapping changes, and contract-event decode updates.
+
+## Explicit Invocation
+
+Use explicit invocation when the diff spans multiple risk areas:
+
+- `$api-surface-gate`
+- `$adapter-parity-check`
+- `$sdk-verification-matrix`
+- `$contract-interaction-patterns`
+
+Implicit triggering is defined in each skill's `SKILL.md` and optional `agents/openai.yaml`.

.agents/skills/adapter-parity-check/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: adapter-parity-check
+description: Validate ethers and viem adapter parity for zksync-js when core or adapter behavior changes. Detect mismatches, enforce documented exceptions, and protect core-to-adapter contract consistency.
+metadata:
+  short-description: Detect and gate ethers/viem behavior drift
+---
+
+# Adapter Parity Check
+
+Use this skill to keep adapter behavior consistent with core abstractions.
+
+## Use This Skill When
+
+- Any change touches `src/core/**`
+- Only one adapter is modified under `src/adapters/ethers/**` or `src/adapters/viem/**`
+- A flow/resource change may alter user-visible behavior in adapters
+
+Use explicit invocation as `$adapter-parity-check` when parity risk is high.
+
+## Responsibilities
+
+1. Build a touched-resource map from the diff.
+2. Compare adapter parity for affected resources:
+
+- method availability
+- input/return shape expectations
+- error semantics
+- flow/status handling behavior
+
+3. Identify mismatches and whether they are intentional.
+4. Enforce explicit exception protocol when parity is intentionally divergent.
+
+## Exception Protocol
+
+If parity is intentionally not achieved, require an `Adapter Parity Exception` note with:
+
+1. Rationale
+2. Scope
+3. Consumer impact
+4. Follow-up issue or timeline
+5. Docs note when user-facing behavior differs
+
+## Guardrails
+
+- Keep `src/core` adapter-agnostic.
+- Do not accept one-adapter behavior changes without parity assessment.
+- Do not hide parity exceptions in code comments only; require PR-level declaration.
+
+## Output Format
+
+Provide:
+
+1. Parity matrix for touched resources
+2. Mismatches found
+3. Exception status (`none`, `required`, `provided`)
+4. Required follow-up actions
+
+## References
+
+- [`llm/architecture-adapters-and-core.md`](../../../llm/architecture-adapters-and-core.md)
+- [`llm/repo-context.md`](../../../llm/repo-context.md)
+- [`llm/change-playbook.md`](../../../llm/change-playbook.md)
+- [`AGENTS.md`](../../../AGENTS.md)

.agents/skills/adapter-parity-check/agents/openai.yaml

@@ -0,0 +1,20 @@
+interface:
+  display_name: 'Adapter Parity Check'
+  short_description: 'Flags ethers/viem behavior mismatches and parity exceptions.'
+  default_prompt: 'Run adapter-parity-check on this change. Produce a parity matrix, mismatch list, and required exception/docs actions.'
+
+activation:
+  aliases:
+    - '$adapter-parity-check'
+  when_file_paths_change:
+    - 'src/core/**'
+    - 'src/adapters/ethers/**'
+    - 'src/adapters/viem/**'
+  when_task_mentions:
+    - 'adapter parity'
+    - 'ethers vs viem'
+    - 'core change'
+    - 'behavior mismatch'
+    - 'consistency'
+
+instructions_source: '../SKILL.md'

.agents/skills/api-surface-gate/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: api-surface-gate
+description: Enforce zksync-js public API safety when diffs touch package exports, typesVersions, entrypoint barrels, or exported core types. Validate checklist, classify compatibility impact, and require docs/changelog alignment.
+metadata:
+  short-description: Guard export surface changes and API checklist compliance
+---
+
+# API Surface Gate
+
+Use this skill to prevent accidental public API drift.
+
+## Use This Skill When
+
+- `package.json` changes in `exports` or `typesVersions`
+- `src/index.ts` changes
+- `src/core/index.ts` changes
+- `src/adapters/ethers/index.ts` changes
+- `src/adapters/viem/index.ts` changes
+- `src/core/types/**` changes
+- Any change appears to add/remove/rename exported symbols
+
+Use explicit invocation as `$api-surface-gate` before merge for export-facing diffs.
+
+## Responsibilities
+
+1. Detect whether API Gate is triggered by touched files.
+2. Compare export deltas (added, removed, renamed, type-only changes).
+3. Require explicit API checklist acknowledgement:
+
+- `No API change`, or
+- `API change` with compatibility and docs/changelog context.
+
+4. Classify compatibility impact using current pre-1.0 release policy.
+5. Confirm docs/tests/changelog alignment for externally visible API changes.
+
+## Guardrails
+
+- Do not approve silent export removals or renames.
+- Do not allow adapter-specific types to leak into `src/core` entrypoints.
+- Do not treat entrypoint changes as internal-only without explicit evidence.
+
+## Output Format
+
+Provide a concise report with:
+
+1. Triggered API files
+2. API delta summary
+3. Compatibility classification (`non-breaking` or `breaking candidate`)
+4. Required follow-ups:
+
+- PR API checklist status
+- docs/changelog updates needed
+- test coverage updates needed
+
+## References
+
+- [`llm/public-api-contract.md`](../../../llm/public-api-contract.md)
+- [`llm/commit-and-pr.md`](../../../llm/commit-and-pr.md)
+- [`.github/pull_request_template.md`](../../../.github/pull_request_template.md)
+- [`llm/release-contract.md`](../../../llm/release-contract.md)
+- [`AGENTS.md`](../../../AGENTS.md)

.agents/skills/api-surface-gate/agents/openai.yaml

@@ -0,0 +1,23 @@
+interface:
+  display_name: 'API Surface Gate'
+  short_description: 'Checks export-surface diffs and API-checklist compliance.'
+  default_prompt: 'Run api-surface-gate for this diff. Report triggered API files, export/type deltas, compatibility impact, and required checklist/docs/changelog follow-ups.'
+
+activation:
+  aliases:
+    - '$api-surface-gate'
+  when_file_paths_change:
+    - 'package.json'
+    - 'src/index.ts'
+    - 'src/core/index.ts'
+    - 'src/adapters/ethers/index.ts'
+    - 'src/adapters/viem/index.ts'
+    - 'src/core/types/**'
+  when_task_mentions:
+    - 'api change'
+    - 'public api'
+    - 'exports'
+    - 'typesVersions'
+    - 'breaking change'
+
+instructions_source: '../SKILL.md'

.agents/skills/contract-interaction-patterns/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: contract-interaction-patterns
+description: Use this skill when changing ABI sources/registry, contract clients/wrappers, calldata construction, contract method calls, event/log decoding, or any SDK behavior directly derived from ABI definitions. Do not use this skill for unrelated utilities, docs formatting, CI/release config, or non-contract refactors.
+---
+
+# Contract Interaction Patterns
+
+Use this skill for ABI-facing SDK work only.
+
+## Activation Scope (Tight)
+
+Use this skill when the diff touches these paths and ABI-facing behavior is involved:
+
+- `src/core/internal/abis/**`
+- `src/core/abi.ts`
+- `src/adapters/*/client.ts`
+- `src/adapters/*/resources/contracts/**`
+- `src/adapters/**/*decoders*`
+- `src/adapters/**/*topics*`
+- `src/adapters/*/errors/revert.ts`
+- `src/core/utils/events.ts` (when event parsing logic changes)
+- `src/core/resources/**/logs.ts` (when log decode/index logic changes)
+
+Also use it when code changes do any of the following:
+
+- calls contract methods
+- builds calldata
+- decodes contract events/logs
+- maps ABI definitions into SDK methods/types
+
+Do not use this skill for incidental non-contract edits in nearby files.
+
+## Contract API Correctness Rules
+
+1. Never invent contract methods or events.
+
+- Verify symbol names against ABI files before proposing wrapper changes.
+
+2. Wrapper/API changes must reference exact ABI names.
+
+- Every proposed wrapper change must cite the ABI function/event name it maps to.
+
+3. ABI/interface changes require ripple mapping.
+
+- Evaluate impact across wrappers, types, tests, and docs.
+- If impact is none, state why explicitly.
+
+4. ABI-driven does not mean "expose everything."
+
+- If an ABI method exists but should not be exposed (admin-only, unsafe, out-of-scope), document rationale and policy alignment.
+
+## Call vs Transaction Patterns
+
+1. Follow established adapter-specific patterns in the closest analogous implementation.
+
+- Cite the file path used as precedent in your output.
+
+2. Read-only interactions:
+
+- Use adapter-native read mechanisms already used in that area.
+
+3. State-changing interactions:
+
+- Use adapter-native send/write flow used in adjacent code.
+- Include receipt/wait handling consistent with existing services.
+
+4. Avoid imposing one universal flow across the entire repo.
+
+- If local patterns vary, follow the local established variant and document it.
+
+5. Keep adapter mechanics inside adapters.
+
+- `src/core` remains adapter-agnostic.
+
+## Address, Chain, and Network Configuration
+
+1. Resolve addresses through existing client/resource flows (`ensureAddresses()`, `contracts()`).
+2. Use `src/core/constants.ts` for canonical system addresses unless explicit overrides are part of existing client initialization.
+3. Source chain IDs from existing provider/client methods used in current contexts.
+4. Reuse core address helpers when validating/normalizing external addresses.
+
+## Events and Logs
+
+1. Never duplicate decoding logic if a helper already exists.
+
+- Search for existing decoder/topic helpers first and extend them.
+
+2. If adding a new decoder/helper is necessary:
+
+- justify why existing helpers are insufficient
+- keep scope minimal and adapter-appropriate
+
+3. Keep topic/index assumptions aligned with existing constants and helper behavior.
+
+## Adapter Parity Requirements
+
+1. ABI-facing behavior added in one adapter requires parity assessment in the other adapter.
+2. Allowed exception must be explicit in PR notes with rationale, scope, and consumer impact.
+3. Document exceptions following existing contributor contracts in `llm/resource-patterns.md` and `llm/change-playbook.md`.
+
+## Generated Artifacts Rule
+
+1. Never hand-edit:
+
+- `src/adapters/ethers/typechain/**`
+- `typechain/**`
+
+2. If ABI changes affect ethers TypeChain inputs:
+
+- run `bun run types`
+- include generated diffs in the same PR
+
+3. If ABI changes do not require regeneration:
+
+- state why explicitly (for example: registry-only alias updates or viem/raw-ABI-only path)
+
+## Invocation Output Contract
+
+When invoked, always output:
+
+1. ABI files involved (full paths)
+2. Contract methods/events touched (exact names)
+3. Wrapper/API change summary
+4. Ripple map (wrappers, services, tests, docs)
+5. Adapter impact (`ethers`, `viem`, or both)
+6. Compatibility risk (`breaking`, `behavior-change`, `additive`, `internal-only`)
+7. Decoder/helper reuse:
+
+- existing helper reused (path), or
+- justification for new helper
+
+8. Verification commands (exact Bun commands)
+9. Required docs updates (or explicit `none`)
+
+## Verification Commands
+
+- `bun run lint`
+- `bun run format:check`
+- `bun run typecheck`
+- `bun run test`
+- `bun run test:e2e:ethers` (when ethers adapter behavior changed)
+- `bun run test:e2e:viem` (when viem adapter behavior changed)
+- `bun run docs:build` (when `AGENTS.md`, `llm/**`, or docs files changed)
+
+## References
+
+- `AGENTS.md`
+- `llm/architecture-adapters-and-core.md`
+- `llm/change-playbook.md`
+- `llm/testing-and-quality.md`
+- `llm/resource-patterns.md`
+- `llm/public-api-contract.md`
+- `src/core/internal/abis/**`
+- `src/core/abi.ts`

.agents/skills/contract-interaction-patterns/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: 'Contract Interaction Patterns'
+  short_description: 'ABI-safe wrapper and event decoding workflow.'
+  default_prompt: 'Use $contract-interaction-patterns to validate ABI mappings, adapter impact, ripple map, and verification steps for this change.'
+
+policy:
+  allow_implicit_invocation: false