efficient-calls

name	efficient-calls
description	以最少 API 调用次数完成编码任务，为按次计费（per-call）场景省钱。 Use when starting a non-trivial coding task and API is billed per call. Triggers: minimize calls, save API calls, per-call billing, reduce round-trips.
version	3.0.0
author	AtomCode <[e-mail]>
license	MIT
tags	["cost-optimization","billing","efficiency","per-call"]
compatibility	Cross-tool (Claude Code, Codex, Gemini CLI, Cursor, OpenCode)

efficient-calls — 按次计费场景的省钱 skill

本 skill 主要适用于「按次计费」的调用场景，核心目的就是省钱。 按次计费下：账单 = 单价 × 调用次数。每条规则都在帮你减少计费次数。 按 token 计费请谨慎采纳（部分规则是反向建议）。采纳前先确认计费方式。

工具无关：本 skill 遵循 agentskills.io 跨工具标准，兼容 Claude Code、 Codex、Gemini CLI、Cursor、OpenCode 等支持 Agent Skills 的编码代理。 文中工具名（读取/写入/编辑/符号列表）是你所用代理的对应工具。

何时使用

在以下情况自动启用本 skill：

• 开始一个非平凡的编码任务（多文件改动、新功能、重构），且 API 按调用次数计费
• 用户明确要求"少调用几次 / 省点调用 / 别那么多轮"
• 任务涉及读取多个文件、写长文件、并行验证等可合并的调用模式

不适合的场景：纯问答、一次性命令、按 token 计费且无省钱诉求。

Instructions

预算控制

1. 先定调用预算：开始任务前，先确认本次任务允许的调用次数上限（如"≤ 30 次"）。预算用完后停下来汇报，不硬撑。
2. 记录实际调用数：任务结束时对比预算与实际，超支原因写进结果。这是后续优化省钱的依据。

读取

3. 优先整文件读取：600 行以内文件用一次读取工具读完，不逐段读。按次计费下整读 1 次 = 分段读 N 次的成本。
4. 并行读取：无数据依赖的多个文件读取必须在同一轮发出。改 3 个模块前一次发 3 个读取调用。
5. 未知结构先取元信息：不熟悉的函数/类/API 先用符号列表/签名工具看结构，不猜参数。猜错一次 = 多花 2-3 次修复调用。

写入

6. 不读刚刚写入的内容：写入/编辑后不立即读取确认，编译/类型检查通过就是证据。
7. 占位符分块写长文件：新文件超过 200 行时，先写第一段 + 占位符，后续用编辑工具逐段追加（多段编辑同消息顺序生效，实测结论）。

执行

8. 不做中间叙述：工具调用之间不输出推理过程或计划说明，只输出一行 ≤12 字进展标识。
9. 后台并行：独立的耗时操作（编译、测试、构建）后台并行启动，不串行等待。
10. 判活两判据：进程存活看两条独立信息——os 级 pid 检查 + 应用级心跳。只看 pid 会误判（pid 复用、进程卡死）。

质量

11. 先想清楚再动手：第一次写对比写错修 3 次便宜得多。模糊需求先问清楚（1 次提问），不要边做边猜（3-5 次返工）。
12. 结果要有证据：每次改动后跑一次编译/测试收尾验证，这 1 次调用能阻止 3-5 次追问。

Examples

反例（按次计费下最贵的写法）

读取 a.py        → 第 1 轮
读取 b.py        → 第 2 轮（可以并行，却串行了）
读取 c.py        → 第 3 轮
编辑 a.py        → 第 4 轮
读取 a.py        → 第 5 轮（刚写完就读，浪费）

5 轮调用，其中 2 轮完全没必要。

正例（按次计费下最省的写法）

读取 a.py 与 b.py 与 c.py   → 第 1 轮（并行整读）
编辑 a.py 与 b.py 与 c.py   → 第 2 轮（同一轮改完）
跑编译/测试                 → 第 3 轮（1 次验证全部）

3 轮调用完成同样的事，省 40%。

Guidelines

执行前检查清单（每一项都违反 = 一次不必要的调用）：

• 任务预算已定（≤ N 次调用）
• 需要读取的文件已列全，准备同一轮并行发出
• 不需要读取刚写入的内容
• 长文件写入已规划占位符分块
• 已确认计费方式是按次（按 token 则选择性采纳）

执行后检查清单：

• 实际调用次数已记录，与预算对照
• 与"按直觉做"的估算对照（目标省 30%+）
• 结果有证据（编译/测试通过）
• 超支原因已写进结果

参考文件

• 台账模板：见 ${SKILL_DIR}/LOG.template.md
• 项目 overlay 示例：见 ${SKILL_DIR}/OVERLAY.example.md
• 高级模式（预算跟踪/批量规划/成本账本/失败回退）：见 ${SKILL_DIR}/references/patterns.md
• 常见问题排查：见 ${SKILL_DIR}/references/troubleshooting.md
• 详细示例：见 ${SKILL_DIR}/../examples/batching.md 与 chunked-write.md