AGENTS.md git:20261015.b6635faA

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

# Agent Skills

This repository contains self-contained agent skills for Claude Code, Codex, and compatible agents. Keep `README.md`
minimal and human-facing. Put maintainer and agent guidance here.

## Prompting Guidance

Write every skill and other agent-facing content for current Claude and GPT agent models, not for one model. Do not name
a model, a model version, or a model-specific default in that prose. Content that selects, configures, or attributes a
model is the exception, for example routing tables, `model:` frontmatter, and API parameters.

Base the guidance on the official vendor guides. Read both guides before complex, long-running, multi-tool, or
orchestration-heavy work. Their recommendations may change.

- [Anthropic prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices):
  Covers all current Claude models. Its model-specific guidance table links each per-model prompting page.
- [OpenAI latest-model guide](https://developers.openai.com/api/docs/guides/latest-model#prompting-best-practices):
  Covers the current GPT model family. Its prompting recommendations come from tests on one model in that family.

Treat advice that names a model as measured on that model. Apply it to other models only when the cross-model guidance
supports it. When the guides give opposite corrections for different models, state the wanted behavior directly. Do not
write a correction to one model's default, such as "be brief" or "write more".

The summaries below remind you of guidance that holds across current models. They do not replace the guides.

- State that user instructions take precedence over skills.
- Complete authorized work under stated assumptions. Name the premature stops to avoid and the stops that are wanted.
  Treat text-only turns as reports, not completion.
- Explore relevant sources before acting.
- Specify writing style, progress updates, and delegation preferences. Do not rely on model defaults for them.
- Name concrete patterns to avoid instead of giving generic style advice.
- Keep verification proportional to the change.
- Calibrate effort instead of prompting for more thinking. Never ask for reasoning in response text.

## 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. 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.
- `mcp/` contains MCP server launchers that `~/.claude.json` and `~/.codex/config.toml` run from this checkout. Edits
  take effect at the next server start, without publication. Put a launcher that a skill requires in that skill's
  `scripts/` directory instead.
- `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.
- Keep the `README.md` skills table complete when skills are added, renamed, removed, or change purpose. Assign one
  primary category per skill, reusing an existing category when it fits. Sort rows by category, then skill name.
- 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. These command details are not
obvious:

- 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 | Run `just skill-check`. Verify referenced files and documented commands for changed skills.                              |
| Shell helpers or tests                     | Run `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   | Run `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. When downstream execution is necessary, use a bounded batch.
- 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

- Before writing or changing agent-facing prose, read
  [the STE authoring profile](skills/agents-brain/references/asd-ste100.md) completely. Apply the profile during
  writing. Complete its meaning and style review before finishing. Preserve obligation strength and protected technical
  content. This review does not establish official ASD dictionary compliance.
- In this repository, an unqualified request to create, scaffold, or initialize a skill means an installable catalog
  skill under `skills/<name>/`. Follow `@skill-lifecycle` and `@skill-authoring`. Do not use the project-local
  scaffolding in `agents-brain create-skill` here.
- Create a repo-private internal skill under `.agents/internal-skills/<name>.md` only when the user explicitly requests
  an internal skill.
- Run [`@rebase-skill`](.agents/internal-skills/rebase-skill.md) only when the user explicitly requests an upstream
  rebase of a selected skill, or for Circadian's weekly scheduled rebase. Never invoke it autonomously or through other
  routine maintenance.
- When importing or forking a whole external skill, add its upstream URL to the README's "Forked Skills" table. In the
  same change, create `.agents/skill-upstreams/<name>.md` and add its provenance index entry. Follow
  [`@skill-lifecycle`](.agents/internal-skills/skill-lifecycle.md#external-provenance) for required evidence and
  enrollment checks. Track borrowed components and inspiration in provenance without labeling them as whole-skill forks.
- Circadian's `~/projects/circadian/jobs/rebase-upstream-skills.sh` discovers the union of "Forked Skills" rows and
  active per-skill provenance records from fresh `origin/main`. It excludes the provenance index and deduplicates skill
  names. No per-skill scheduler list needs an update. Discovery preserves each record's merge limits and does not
  authorize a new baseline.
- 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. See `@publish-skills` for scope rules.
- 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`. 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
  for that conflict to end 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, deleting, or shelving 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`. 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.
- When an installed CLI outpaces a `cli-*` skill's `references/version.txt`, refresh it with `@refresh-cli-skill`.
- 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. Every user-facing workflow needs a command. Commit them in `~/.claude`.
- Keep skills self-contained. Do not remove 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. Discover target-project conventions at runtime. Refer to an external repository only
  when it is 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.
- Do not leak personal crypto (EVM) addresses in any skill. Use well-known public addresses or the standard Etherscan
  doc example (`0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe`). Do not use a real user, maintainer, or personal wallet
  address. For private keys, mnemonics, and API keys, use env-var placeholders (`$ETH_PRIVATE_KEY`). Never use literal
  secrets.