AGENTS.md git:20261005.de96c48A

Immutable. This exact content never changes and is served at /api/v1/blob/5a8328533b077bc5.

# Agent Skills

Collection of self-contained agent skills for Claude Code, Codex, and compatible agents. Keep `README.md` minimal and
human-facing; put maintainer and agent guidance here.

## Model Optimization

Optimize every skill and other agent-facing content for GPT-6.1 Sol and Claude Opus 5.5. The summaries below are
reminders, not substitutes for the live guides. Read both guides before complex, long-running, multi-tool, or
orchestration-heavy work because their recommendations may evolve.

- [GPT-6.1 Sol prompting guidance](https://developers.openai.com/api/docs/guides/latest-model#prompting-best-practices)
  (shared GPT-6 guide; evaluate its family-wide recommendations on Sol): Complete authorized work under stated
  assumptions; make user-instruction precedence over skills explicit; specify writing and delegation preferences; and
  keep verification proportional to the change.
- [Claude Opus 5.5 prompting guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5):
  Calibrate effort instead of prompting for more thinking; never ask for reasoning in response text; name the premature
  stops to avoid and the stops that are wanted; treat text-only turns as reports, not completion; request brief progress
  updates; explore relevant sources before acting; and name concrete patterns to avoid instead of generic style advice.

## User-Facing Communication

Treat visual structure as information architecture, not decoration.

- Use a small semantic status vocabulary consistently: `🔎` preview/read-only, `⏳` running, `✅` verified success, `⚠️`
  caveat/approval/risk, `⛔` blocked/not written, `❓` unknown, and `↩` reverted/rolled back. When a status icon is
  used, pair it with a status word; never make color or emoji the only carrier of meaning.
- Lead reports with one outcome line. Use at most one non-status domain icon per heading for identity, then add compact
  headings for changed artifacts, verification, and issues only when those sections are useful.
- Use `Issues and caveats` for report findings, grouped as `Resolved` (verified fixes) and `Open` (remaining problems,
  limitations, or unverified assumptions). State resolution evidence or the remaining impact and next step; omit empty
  groups and report each item once. Reserve `blocker` for something preventing required work and `risk` for a specific
  potential adverse outcome. Put neutral context and agreed decisions under changes or scope.
- Use tables for repeated fields, trees for real hierarchy or file structure, and progress bars only when a measured
  numerator and denominator exist. Never imply progress from elapsed time, activity, or guesswork.
- Keep JSON, JSONL, DOT, CSV/TSV, exact commands, confirmation tokens, identifiers, addresses, hashes, signatures,
  diagnostics, logs, copied prompts, and other machine-consumed or verbatim content undecorated. Keep safety and
  rollback wording direct.
- Decoration belongs to the agent's status wrapper. Do not add emoji or ASCII ornament to source code, generated
  artifacts, product UI copy, GitHub contributions, spreadsheet data, or user-authored content unless the task itself
  calls for it.

## Evidence and Disclosure

- Internal agent communication includes task reports, tool output, current-project transcript inspection, and material
  evidence sent to the configured model provider. Prefer efficient, complete, direct evidence; do not require redaction,
  local-only handling, or excerpt suppression solely because the provider can see it.
- Before posting, uploading, publishing, emailing, releasing, or otherwise sending data outside the agent workspace,
  perform an external-disclosure review. Remove credentials and secrets, unrelated personal or customer data, unsuitable
  private paths or repository names, and unrelated transcript material.
- This distinction never relaxes secret handling or the no-personal-EVM-address rule under **Rules**.

## Structure

- `skills/<name>/SKILL.md` is the skill entrypoint.
- `skills/<name>/references/` contains skill-local reference docs.
- `skills/<name>/scripts/` contains executable helpers.
- `skills/<name>/agents/openai.yaml` contains Codex-specific metadata, including for skills not installed into Codex.
- `skills/<name>/examples/` contains sample files.
- `skills/<name>/assets/` contains bundled media or other static assets.
- `.agents/internal-skills/<name>.md` contains repo-private internal skills referenced with `@`.
- `tests/<name>/` contains tests for that skill's helpers; `scripts/` contains catalog tooling.
- `toolkit/` is the Rust workspace and Bun apps that own the `ai-*` CLIs the skills and the global coordination workflow
  rely on; follow `toolkit/AGENTS.md` there.
- `README.md` lists every skill and stays minimal.
- Claude Code reads `AGENTS.md` directly; do not add a `CLAUDE.md`.

## Commands

Run `just` to list every recipe with its description; the `justfile` is authoritative. Notable, non-obvious facts:

- After editing Markdown, run `just prettier-write <changed files>` then `just prettier-check <changed files>`, in that
  order; if `prettier-check` fails, fix only the files you changed.
- The root `package.json` exists only for local formatting, type-checking, and hook wiring; there is no build step.
- CLI changes go live only via `just toolkit::install-cli`, under the install-authorization rules in
  `toolkit/AGENTS.md`.

## Local Verification

All checks run locally. Do not add CI workflows or rely on remote checks for completion.

- During iteration, run focused checks for the changed behavior. Before committing, run the affected owner's complete
  local gate below, including dependent consumers when an interface or shared configuration changes.
- Run the final gate once after completing edits; repeat only after further changes, a failure, or an unresolved
  concern. Documentation-only changes need formatting and verification of changed commands, paths, and claims, not
  unrelated runtime suites.
- Formatting, pre-commit hooks, successful installation, and live smoke checks do not replace required tests,
  type-checks, linting, or builds. Add regression coverage when changing behavior; keep tests proportional to the
  change.
- Keep formatters and fixers scoped to files edited in this session. Attribute failures before debugging; if an
  aggregate fails only in untouched concurrent work, verify your own scope and report the limitation.
- Report the exact check commands and outcomes, including failures and skipped checks. Do not claim verification from an
  unrun command or finish while a required check is still running.

| Change scope                               | Required local verification                                                                                          |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Skill metadata, dependencies, README table | `just skill-check`; verify referenced files and documented commands for changed skills.                              |
| Shell helpers or tests                     | `just shell-check <changed files>` and the affected shell tests; use `just bats-test tests/<skill>` for Bats suites. |
| Python helpers or tests                    | Run the affected `tests/<skill>/test*.py` scripts with `uv run`.                                                     |
| Root Bun TypeScript helpers                | `just typescript-check` and the affected tests (`just publish-skills-test` or `just evm-atlas-test`).                |
| evm-atlas generated inputs or references   | `just evm-atlas-check`; change canonical inputs and regenerate derivatives rather than editing generated files.      |
| Shared catalog tooling or test wiring      | `just test` and `just skill-check`, plus shell linting for changed shell files.                                      |
| Toolkit Rust or Bun applications           | Follow `toolkit/AGENTS.md` and the owning package's validation rules.                                                |

Skill prose changes also require checking affected reference links, helper usage, and examples; run helper tests when
the instructions change how a helper is used. Markdown changes always follow the formatting sequence under **Commands**.

## Resource-Safe Search

- Scope `fd`, `rg`, `grep`, and similar searches to the narrowest useful root. Exclude known dependency, build, cache,
  generated, and state directories before broadening; plain bounded searches with these tools are appropriate.
- Do not run per-result commands over unknown or high-cardinality sets with `fd -x`/`--exec`, `find -exec`, parallel or
  unbounded `xargs`, or shell loops that launch one tool per path. Prefer native predicates or metadata output; preview
  or sample cardinality, then use a bounded batch when downstream execution is necessary.
- Stream and bound large search results instead of capturing arbitrary full lines, JSON events, or generated-file output
  in memory or repeatedly rescanning it. Long-running helpers must propagate cancellation and terminate or clean up
  child processes.

## Rules

- In this repository, an unqualified request to create, scaffold, or initialize a skill means an installable catalog
  skill under `skills/<name>/`. Never route it to `.agents/skills/` or the `skill-writing` workflow.
- Create a repo-private internal skill under `.agents/internal-skills/<name>.md` only when the user explicitly requests
  an internal skill.
- Edit or remove installable catalog skills under `skills/` here, regardless of the session's starting repository;
  installed copies belong to the publish workflow.
- Changes here are not live until installed into every target declared by the skill. By default, `publish-skills`
  reconciles all current source-owned drift; an explicit commit range or automatic continuous skill maintenance narrows
  reconciliation to the affected skill names (scope rules: `@publish-skills`).
- After validating edits to installable catalog skills, run the `publish-skills` internal skill on the user's behalf,
  including for independent repairs made during a blocked main task. Complete publication unless a concrete blocker
  prevents it; task complexity and unrelated dirty files are not reasons to leave validated repairs unpublished.
- Before publication, inspect `ai-coord status --json` and consider every active work row. Commit and push catalog
  source changes under the source-repository claim, then release that claim before acquiring targets: home-directory
  targets sort before this source repository. If another agent has a queued claim overlapping any active claim, resolve
  or wait out that conflict before publishing. Require `READY` for the complete target claim set in `@publish-skills`.
  This source-then-target sequence is the documented exception to the global rule that multi-root writes take one
  `ai-coord bundle start`; the target set itself still uses one bundle when it spans two or more roots.
- When creating, renaming, or deleting a catalog or internal skill, follow `@skill-lifecycle`. For catalog creation,
  also follow `@skill-authoring`. `just skill-check` must pass.
- Before creating or editing `SKILL.md` frontmatter, `agents/openai.yaml`, `metadata.install-targets`, or
  `skill-dependencies`, read `@skill-authoring` — it is the authoritative metadata reference; do not guess field
  semantics.
- Internal skills are special repo-private runbooks. Place them under `.agents/internal-skills/<name>.md`, not under
  `skills/`. Do not add them to `README.md`, do not create `agents/openai.yaml`, and do not treat them as installable
  catalog skills.
- After editing skills that must stay aligned, run the `sync-skills` internal skill to check coupled skills and helper
  data.
- Claude Code slash commands under `~/.claude/commands/<skill>/*.md` are thin wrappers over catalog skills (currently
  `agents-brain` and `yeet`). After changing a skill's workflows, argument forms, context requirements, or reference
  file names, update the matching commands in the same session: argument hints, descriptions, `## Context` reads, and
  reference paths must match the skill, and every user-facing workflow needs a command. Commit them in `~/.claude`.
- Keep skills self-contained. Do not de-duplicate content across skills by extracting shared references or canonical
  files; users install skills individually.
- Keep globally installed skills self-contained. Do not refer to or depend on another repository; put reusable guidance
  directly in the owning skill and discover target-project conventions at runtime. Refer to an external repository only
  when it is genuinely required to perform the skill's task.
- Write skill content for end users and other repos, not for this repo. Skills must not assume this repo's own tooling
  (e.g. `just prettier-write`, `just skill-check`) is present elsewhere; have skills detect and use whatever the target
  repo provides instead of naming this repo's recipes.
- Resolve `references/`, `scripts/`, `examples/`, and `assets/` paths relative to the owning skill directory.
- Bash scripts must be compatible with Bash v3.2 (`/bin/bash`) because macOS ships that system version and skills may
  run in Bash-based environments.
- Keep generated docs terse, imperative, and expert-to-expert.
- Never leak personal crypto (EVM) addresses in any skill. Use well-known public addresses or the standard Etherscan doc
  example (`0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe`); never a real user, maintainer, or personal wallet address.
  Same for private keys, mnemonics, and API keys — use env-var placeholders (`$ETH_PRIVATE_KEY`), never literal secrets.