charlieviettq/awesome-agent-skill / .claude/skills/agent-tool-contracts
agent-tool-contracts
VerifiedDesign 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.6 KB |
SKILL.md
View on GitHub---
name: agent-tool-contracts
description: "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."
allowed-tools: Read, Glob, Grep
---
# Agent tool contracts
## Tool design rules
1. **Verb-noun names** — `search_issues`, `create_draft_pr` (not `doStuff`).
2. **Minimal parameters** — fewer required fields; sensible defaults in description.
3. **Explicit side effects** — "Creates...", "Deletes...", "Read-only" in description.
4. **Bounded output** — paginate or truncate; return summary + pointer for large data.
5. **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)
- `--json` for machine output; stable field names.
- Exit codes: 0 success, non-zero with stderr message.
- `--dry-run` for 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |