Agent tool contracts
Skill charlieviettq/awesome-agent-skill/.claude/skills/agent-tool-contracts
Design agent tools and CLI surfaces—schemas, naming, errors, idempotency, and discoverability for LLM callers. Use when defining tools for agents, SDKs, or AI-native CLIs.From its SKILL.md
npx -y skills add charlieviettq/awesome-agent-skill --skill agent-tool-contractsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 24 stars24 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
1.6 KB, 327 tokens by cl100k_base, as published. Nobody here has run it
Agent tool contracts
Tool design rules
- Verb-noun names —
search_issues,create_draft_pr(notdoStuff). - Minimal parameters — fewer required fields; sensible defaults in description.
- Explicit side effects — "Creates...", "Deletes...", "Read-only" in description.
- Bounded output — paginate or truncate; return summary + pointer for large data.
- Stable errors —
{ "code": "NOT_FOUND", "message": "..." }.
Schema quality
- Types and enums for categorical fields.
- Examples in parameter descriptions.
- Reject unknown enums at validation layer.
Idempotency and safety
| Operation | Pattern |
|---|---|
| Read | Safe to retry |
| Create | Idempotency key or dedupe by natural key |
| Update | Version or ETag when concurrent edits possible |
| Delete | Soft delete or two-step confirm in description |
AI-native CLI (when applicable)
--jsonfor machine output; stable field names.- Exit codes: 0 success, non-zero with stderr message.
--dry-runfor mutating commands.
Review checklist
- Description tells the model when NOT to use the tool
- Errors actionable (what to fix, not internal codes only)
- No overlapping tools with ambiguous choice
- Integration test with representative agent prompts
Related
mcp-builder for MCP-specific packaging; agent-evaluation for measuring tool accuracy.
What ships with it
Read from the repository
Just SKILL.md. No reference files, no scripts.