菜单
The Agent Tool Contract — 5 principles for designing tools agents call reliably: predictable signature, rich errors, token-efficient output, idempotency, graceful degradation. Includes anti-pattern table with 8 common mistakes.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/oimiragieo/agent-studio --skill agent-tool-design命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Agent frontmatter enhancements — disallowedTools, mcpServers scoping, fork_eligible field
Context management — pre-compact persistence, threshold alignment, microcompact/circuit breaker detection
Hook enhancements — updatedInput for bash safety prefixes, suppressOutput for verbose blocks, denial-based routing feedback
正在显示 SKILL.md
基于 SOC 职业分类
| name | agent-tool-design |
| description | The Agent Tool Contract — 5 principles for designing tools agents call reliably: predictable signature, rich errors, token-efficient output, idempotency, graceful degradation. Includes anti-pattern table with 8 common mistakes. |
| version | 1.2.0 |
| category | Development |
| agents | ["developer","architect","tool-creator"] |
| user_invocable | true |
| invoked_by | both |
| tools | ["Read","Write","Bash"] |
| verified | true |
| lastVerifiedAt | "2026-03-01T00:00:00.000Z" |
| tags | ["tools","design","api","contract","idempotency","errors","agent-tools"] |
| best_practices | ["Parameters are named not positional","Errors include machine-readable code plus human message plus context","Output is structured data only — no prose","Tools are idempotent (safe to retry)","Partial failure returns partial results rather than throws"] |
| error_handling | graceful |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 4e11dcf3976f7b80 |
The Agent Tool Contract — 5 principles for designing tools that agents call reliably.
Tools must have typed, named parameters with clear required/optional distinction. No positional ambiguity.
Good:
// Clear, named, typed
function searchCode({ query, limit = 20, type = 'semantic' }) { ... }
Bad:
// Positional, ambiguous
function searchCode(q, n, t) { ... }
Errors must include: error code (machine-readable), message (human-readable), context (debugging data).
Good:
throw {
code: 'FILE_NOT_FOUND',
message: `File not found: ${path}`,
context: { path, cwd: process.cwd() },
};
Bad:
throw new Error('not found'); // No context for agent to act on
Tools return structured minimal data. No prose explanations, no redundant wrapping, no verbose status messages. Agents format output themselves.
Good:
return { files: ['a.js', 'b.js'], total: 2 };
Bad:
return { status: 'success', message: 'Found 2 files successfully', data: { files: [...], metadata: {...} } };
Rule of thumb: If the output contains prose an agent would re-read to extract facts, it's too verbose.
Tools must be safe to retry. Running a tool twice should produce the same result as running it once.
Good:
// Upsert instead of insert
db.upsert({ id, ...data });
// mkdir -p instead of mkdir
fs.mkdirSync(path, { recursive: true });
Bad:
// Fails on retry
db.insert({ id, ...data }); // duplicate key error
fs.mkdirSync(path); // EEXIST error
Partial success > hard failure. Return what succeeded with a clear indication of what didn't.
Good:
return {
succeeded: ['file1.js', 'file2.js'],
failed: [{ file: 'file3.js', reason: 'PERMISSION_DENIED' }],
partial: true,
};
Bad:
// One file fails -> entire batch throws
throw new Error('Failed to process file3.js');
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Verbose status wrapping | Wastes tokens; agent re-parses to extract data | Return data directly |
| Positional args | Ambiguous; breaks on refactor | Named params with types |
| Swallowed exceptions | Agent thinks success; work is lost | Always surface errors explicitly |
| Non-idempotent mutations | Retry causes duplicate data or errors | Upsert semantics; check-then-set |
| Hard failures on partial input | One bad item breaks entire batch | Return partial results |
| Side-effect-heavy reads | Read tools that trigger writes confuse agents | Separate reads from writes |
| String error messages only | Agent can't programmatically handle errors | Include machine-readable error codes |
| Untyped return shape | Agent can't reliably destructure output | Document and enforce return schema |
Before shipping any tool:
[ ] Parameters are named (not positional)
[ ] Required vs optional params are explicit
[ ] All error paths return { code, message, context }
[ ] Output contains no prose — only structured data
[ ] Tool is idempotent (safe to retry)
[ ] Partial failure returns partial results, not throws
[ ] Return shape is documented in JSDoc or TypeScript types
[ ] Token budget for output estimated (< 500 tokens for standard tools)
{ code, message, context } to handle errors programmatically.mkdir -p patterns.{ succeeded, failed, partial: true }.tool-creator skill when designing new toolscode-reviewer agent during tool PRsdynamic-api-integration skill (consuming external tools)agent-evaluation skill (evaluating tool output quality)Before starting:
Read .claude/context/memory/learnings.md
After completing:
.claude/context/memory/learnings.md.claude/context/memory/issues.md.claude/context/memory/decisions.mdASSUME INTERRUPTION: If it's not in memory, it didn't happen.