predictable-behavior-first

A set of rules for handling fallback, compatibility, retry, default, and legacy behavior in software. Fallback means trying another path when the main path does not work.

In plain words
What is it for?
It guides decisions about when to fail immediately, how to handle old interfaces, how to design explicit recovery paths, and how to keep read-only operations free of unexpected side effects.
Why use it?
It helps prevent hidden recovery paths from masking configuration or release problems and makes the same input behave predictably.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/peiiii/nextclaw/predictable-behavior-first
Any agent
npx skills add Peiiii/nextclaw --skill predictable-behavior-first
Clone the repo
git clone --depth 1 https://github.com/Peiiii/nextclaw

Made for: Claude Code, Codex.

Per session 49 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 786 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00049 $0.00786
Opus 5 $0.00024 $0.00393
Sonnet 5 $0.00010 $0.00157
Haiku 4.5 $0.00005 $0.00079

Measured 3d ago against content hash e9af47930c22, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

predictable-behavior-first scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.agents/skills/predictable-behavior-first/SKILL.md · 46 lines

What it actually says

可预测行为优先

目标是同一输入与安装状态产生同一行为:不靠隐藏环境状态意外成功,也不把发布、配置或协议缺陷伪装成健康。

默认立场

  • fail-fast 优于静默救援,单一事实源优于多级 fallback。
  • dev convenience 必须显式开启;发布产物不得借用 cwd、源码 checkout 或本机偶然资源。
  • 内部重构迁移所有已知调用方并删除旧入口,不为方便保留 alias、proxy、adapter 或双 manager。
  • 未发布中间态不是兼容合同;旧 route/API 只有在承载持久用户数据、已证明外部合同或不可避免的分阶段 rollout 时才保留。
  • 无效的 prompt、schema、协议或上游值应修 producer 并显式拒绝,不在下游用别名或归一化悄悄接受。
  • read/get/list/status/discover/report 必须纯读、可重复且无副作用;加载、注册、授权、写入和外部调用使用显式 action。
  • schema/tool 只表达自身合同,不承载动态 catalog、CLI 教程和 AI 工作流;发现与操作流程归对应 owner。

决策流程

  1. 写出主合同:发布包、桌面产物、公共 API、配置 schema、持久数据或 transport。
  2. 区分 shipped runtime 与显式 dev mode。
  3. 判断 fallback 是否掩盖 packaging/config/release/runtime 缺陷;若是,修源合同并增加相应交付 guard。
  4. 判断错误是否来自上游意图或协议;若是,修 producer,不在 consumer 宽容化。
  5. 判断 read-shaped path 是否会被页面加载、路由、轮询、重试、重连或 focus-refetch 自动调用;任何执行副作用都应拆成显式 action。
  6. 协议模式已知时第一次请求就使用正确 contract,不先发错误模式再按错误文本切换。
  7. 仍需兼容时,读取例外政策,证明外部必要性,并冻结触发、范围、信号、owner 和退出条件。

禁止的运行时补丁

除非用户明确授权短期事故止血且有删除条件,不得在 shipped runtime 中加入:

  • stderr/stdout.includes(...) 识别当前坏版本、打包事故或临时上游故障;
  • “latest release 已坏”等版本/事故签名特判;
  • 扫描多个无关目录直到找到可用资源;
  • 先发送错误 transport,再根据上游报错文本重试真实模式;
  • 自动触发的前端 read path 隐藏 load/register/install/write/external call;
  • 没有真实外部合同的旧 API 转发、双实现或永久 mode flag。

输出

说明主合同、观察/执行属性、自动调用副作用、fallback 是否掩盖缺陷、旧路径是否拥有持久数据或外部合同,以及结论属于:删除、fail-fast、显式 dev-only、或有退出条件的临时兼容。

允许兼容必须同时具备具体必要性、窄范围、可观察信号、cleanup owner 和明确退出事件;缺一项就不保留。

Files

What ships with it

1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 3d ago First seen · 46 lines · 49 tokens per session scan A e9af47930c22

Subscribe to this mod's changes

predictable-behavior-first is a skill published in the GitHub repository Peiiii/nextclaw (253 stars, last pushed 3d ago), licensed MIT. It adds 49 tokens to every session and 786 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

ha-skill-creator

Create, edit, improve, or audit Hope Agent skills. Use when the user wants to: (1) create a new skill from scratch, (2) edit or improve an existing skill, (3) review or clean up a SKILL.md file, (4) run evaluations to test skill effectiveness, (5) optimize skill descriptions for better trigger accuracy. Trigger…

shiwenwen/hope-agent · 106 tokens

ha-mac-control

Hope Agent native macOS desktop control — the standard maccontrol status / diagnostics / apps / dock / spaces / snapshot / visual / windows / menu / clipboard / dialog loop, target-first action rules, no-blind-coordinate policy, and recovery for stale AX/window/menu/dialog state. Load whenever using maccontrol, or…

shiwenwen/hope-agent · 139 tokens

ha-browser

Hope Agent browser automation — the standard status → tabs → snapshot → act loop, stale-ref recovery rules, and what to do when login / 2FA / captcha / camera-prompt / dialog blocks progress. Load this skill whenever you reach for the browser tool. Trigger on: user asks the agent to open / control / click / scrape /…

shiwenwen/hope-agent · 140 tokens

ha-logs

Self-service diagnostics — query Hope Agent's local SQLite databases (logs / sessions / background jobs) directly via the exec tool to investigate problems, analyze usage, and locate root causes. Trigger on: user reports something broken / failing / slow / stuck / not responding ('X 不工作', 'X 报错', 'X 卡住', '为什么 X 失败'…

shiwenwen/hope-agent · 183 tokens

ha-pet-import

Safely import, select, switch, or enable a compatible desktop pet in Hope Agent. Resolve packages from any origin, including local folders, zip archives, pet.json plus a sprite, PNG/WebP atlases, chat attachments, repository or cloud files, direct HTTPS artifact URLs, and download pages. Use whenever a user asks to…

shiwenwen/hope-agent · 109 tokens

ha-data-analytics

Hope-native local-first data analysis and Artifact reporting. Use for CSV/XLSX analysis, KPI readouts, metric diagnosis, product/business analysis, data-quality review, dashboards, charts, analytical reports, 数据分析, 指标诊断, 数据质量, 分析报告, or when the user wants a shareable offline HTML/ZIP/Markdown/PDF result. Produces the…

shiwenwen/hope-agent · 106 tokens