agent-tool-contract-review
Review tools, MCP functions, CLI commands, SET inputs, and AGENTS.md generator outputs as agent-facing contracts. Use when a tool description, schema, workflow input, or generated instruction may be ambiguous, unsafe, noisy, or hard for agents to call correctly.
Install
npx skills add https://github.com/markoblogo/abvx-agent-skills/tree/main/skills/agent-tool-contract-review
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install markoblogo-abvx-agent-skills@llmmart
git clone https://github.com/markoblogo/abvx-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole markoblogo/abvx-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Agent Tool Contract Review
Use this skill to make a tool easier and safer for agents to call.
Use When
- designing or reviewing MCP tools, CLI wrappers, GitHub Actions inputs, or SET planner outputs;
- changing AGENTS.md generator templates that tell agents which commands or tools to use;
- a tool has ambiguous parameters, hidden side effects, noisy output, or weak error messages;
- agent runs repeatedly misuse a command or need human intervention after avoidable failures.
- adapting an external skill, contract, or workflow into the local skill network.
Adaptation Delta
Before writing an adapted external skill, classify each material source fragment in templates/adaptation-delta.yaml:
KEEP: retain source mechanics or schema without semantic change;ADAPT: change paths, tools, authority, terminology, or environment assumptions;ADD: introduce local guardrails, routing, verification, or project boundaries;REJECT: exclude a fragment and record the reason plus source reference.
Every entry requires a stable ID and source fragment reference. Present the complete delta to the owner before writing. Record APPROVED, REVISE, or REJECTED; silence is not approval. Preserve attribution and license constraints independently of the classification.
Review Dimensions
- purpose: what job the tool owns and what it does not own;
- schema: required fields, optional fields, enums, defaults, and validation;
- authority: read-only, proposal-only, write, destructive, external side effect;
- output: compact, structured, parseable, and stable enough for downstream agents;
- errors: actionable messages with the smallest useful recovery step;
- idempotency: safe retries, duplicate handling, and idempotency keys when needed;
- auditability: logs, dry-run mode, preview mode, and human approval boundary.
Workflow
- Identify the agent-facing tool surface and its intended caller.
- Classify the authority level:
read,plan,proposal,write, ordestructive. - Check whether the name, description, schema, and examples make the safe path obvious.
- Check whether the output can be consumed without reading a large log.
- Check error paths and retry semantics.
- Recommend the smallest contract change: rename, tighter schema, dry-run, better error, structured output, or approval gate.
Output Shape
Use:
- verdict:
CONTRACT_OK,CONTRACT_AMBIGUOUS, orCONTRACT_UNSAFE; - tool surface reviewed;
- authority level;
- contract findings;
- smallest contract changes;
- tests or smoke checks.
Guardrails
- Do not redesign the whole tool when a schema or description change is enough.
- Do not hide write or destructive behavior behind friendly wording.
- Do not require agents to infer defaults that can be encoded in schema.
- Do not make logs the primary machine interface when structured output is feasible.
- Do not silently omit or rewrite upstream behavior during adaptation.
Provenance
Adapted from tool-design patterns in muratcankoylan/Agent-Skills-for-Context-Engineering, plus MakerSkills' explicit keep/adapt/add porting report. Narrowed for SET, AGENTS.md generator, MCP, CLI, and provider-neutral skill adaptation, with an added REJECT disposition and owner gate.
Files (abvx-agent-skills)
-
agents
-
openai.yaml 271 B
Loading…
-
-
templates
-
adaptation-delta.yaml 632 B
Loading…
-
-
SKILL.md 3.6 KB
--- name: agent-tool-contract-review description: Review tools, MCP functions, CLI commands, SET inputs, and AGENTS.md generator outputs as agent-facing contracts. Use when a tool description, schema, workflow input, or generated instruction may be ambiguous, unsafe, noisy, or hard for agents to call correctly. license: MIT metadata: abvx_status: experimental abvx_origin: adapted --- # Agent Tool Contract Review Use this skill to make a tool easier and safer for agents to call. ## Use When - designing or reviewing MCP tools, CLI wrappers, GitHub Actions inputs, or SET planner outputs; - changing AGENTS.md generator templates that tell agents which commands or tools to use; - a tool has ambiguous parameters, hidden side effects, noisy output, or weak error messages; - agent runs repeatedly misuse a command or need human intervention after avoidable failures. - adapting an external skill, contract, or workflow into the local skill network. ## Adaptation Delta Before writing an adapted external skill, classify each material source fragment in `templates/adaptation-delta.yaml`: - `KEEP`: retain source mechanics or schema without semantic change; - `ADAPT`: change paths, tools, authority, terminology, or environment assumptions; - `ADD`: introduce local guardrails, routing, verification, or project boundaries; - `REJECT`: exclude a fragment and record the reason plus source reference. Every entry requires a stable ID and source fragment reference. Present the complete delta to the owner before writing. Record `APPROVED`, `REVISE`, or `REJECTED`; silence is not approval. Preserve attribution and license constraints independently of the classification. ## Review Dimensions - purpose: what job the tool owns and what it does not own; - schema: required fields, optional fields, enums, defaults, and validation; - authority: read-only, proposal-only, write, destructive, external side effect; - output: compact, structured, parseable, and stable enough for downstream agents; - errors: actionable messages with the smallest useful recovery step; - idempotency: safe retries, duplicate handling, and idempotency keys when needed; - auditability: logs, dry-run mode, preview mode, and human approval boundary. ## Workflow 1. Identify the agent-facing tool surface and its intended caller. 2. Classify the authority level: `read`, `plan`, `proposal`, `write`, or `destructive`. 3. Check whether the name, description, schema, and examples make the safe path obvious. 4. Check whether the output can be consumed without reading a large log. 5. Check error paths and retry semantics. 6. Recommend the smallest contract change: rename, tighter schema, dry-run, better error, structured output, or approval gate. ## Output Shape Use: - verdict: `CONTRACT_OK`, `CONTRACT_AMBIGUOUS`, or `CONTRACT_UNSAFE`; - tool surface reviewed; - authority level; - contract findings; - smallest contract changes; - tests or smoke checks. ## Guardrails - Do not redesign the whole tool when a schema or description change is enough. - Do not hide write or destructive behavior behind friendly wording. - Do not require agents to infer defaults that can be encoded in schema. - Do not make logs the primary machine interface when structured output is feasible. - Do not silently omit or rewrite upstream behavior during adaptation. ## Provenance Adapted from tool-design patterns in `muratcankoylan/Agent-Skills-for-Context-Engineering`, plus MakerSkills' explicit keep/adapt/add porting report. Narrowed for SET, AGENTS.md generator, MCP, CLI, and provider-neutral skill adaptation, with an added `REJECT` disposition and owner gate. -
SKILL_CARD.md 1.6 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.