Agent Harness Construction

1---2name: agent-harness-construction3description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.4origin: ECC5---6 7# Agent Harness Construction8 9Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.10 11## Core Model12 13Agent output quality is constrained by:141. Action space quality152. Observation quality163. Recovery quality174. Context budget quality18 19## Action Space Design20 211. Use stable, explicit tool names.222. Keep inputs schema-first and narrow.233. Return deterministic output shapes.244. Avoid catch-all tools unless isolation is impossible.25 26## Granularity Rules27 28- Use micro-tools for high-risk operations (deploy, migration, permissions).29- Use medium tools for common edit/read/search loops.30- Use macro-tools only when round-trip overhead is the dominant cost.31 32## Observation Design33 34Every tool response should include:35- `status`: success|warning|error36- `summary`: one-line result37- `next_actions`: actionable follow-ups38- `artifacts`: file paths / IDs39 40## Error Recovery Contract41 42For every error path, include:43- root cause hint44- safe retry instruction45- explicit stop condition46 47## Context Budgeting48 491. Keep system prompt minimal and invariant.502. Move large guidance into skills loaded on demand.513. Prefer references to files over inlining long documents.524. Compact at phase boundaries, not arbitrary token thresholds.53 54## Architecture Pattern Guidance55 56- ReAct: best for exploratory tasks with uncertain path.57- Function-calling: best for structured deterministic flows.58- Hybrid (recommended): ReAct planning + typed tool execution.59 60## Benchmarking61 62Track:63- completion rate64- retries per task65- pass@1 and pass@366- cost per successful task67 68## Anti-Patterns69 70- Too many tools with overlapping semantics.71- Opaque tool output with no recovery hints.72- Error-only output without next steps.73- Context overloading with irrelevant references.