AGENTS.md · diff
git:20261005.775784a to git:20261005.aec7204
71 added, 61 removed. Audit A to A.
# 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.
+ 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.
## 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.
+ Optimize every skill and other agent-facing content for GPT-6.1 Sol and Claude Opus 5.5. The summaries below remind you
+ of the live guidance. They do not replace the guides. Read both guides before complex, long-running, multi-tool, or
+ orchestration-heavy work. Their recommendations may change.
- [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.
+ (shared GPT-6 guide): Evaluate its family-wide recommendations on Sol. Complete authorized work under stated
+ assumptions. State that user instructions take precedence over skills. Specify writing and delegation preferences.
+ 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.
+ 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. Name concrete patterns to avoid instead of
+ giving 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
+ 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
+ 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,
+ 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.
+ - `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.
+ 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`.
+ - 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:
+ 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.
+ 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
+ - 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
+ 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
+ - 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. |
+ | 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
+ 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.
+ 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.
+ 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/skill-writing/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>/`. 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.
+ - 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`).
+ 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` 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.
+ 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
+ `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
+ `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, 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.
+ 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
+ (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.
+ example (`0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe`). Never 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.