Claude Skill

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.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download markoblogo-abvx-agent-skills-skills_agent-tool-contract-review-37a7146.zip · 3 KB

Install

skills CLI npx skills add https://github.com/markoblogo/abvx-agent-skills/tree/main/skills/agent-tool-contract-review
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install markoblogo-abvx-agent-skills@llmmart
Git 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

  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.

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.

No comments yet.

Reviews (0)

No reviews yet.