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: Covers all current Claude models. Its model-specific guidance table links each per-model prompting page.
• OpenAI latest-model guide: 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.
• After editing Python, run just python-fix <changed files> then just python-check <changed files>, in that order. Both run ruff through uvx, so no global install is needed, and ruff.toml is the only configuration. Without paths, they cover every Python file in the repository. Fix remaining findings by hand or narrow the code. For a known false positive, add the narrowest per-file-ignores entry in ruff.toml with a comment. Use an inline suppression only for a one-off, with a reason.
• 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.

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 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>/. 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 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 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.
• Run just bats-test tests/shell-compat.bats to check production helpers with system Bash syntax parsing. This does not prove full Bash 3.2 compatibility.
• 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.