agentic-engineeringclaude-codecodexcursorEvidence not reviewed

Agent harness construction: action spaces, tools, observations

Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.

Upstream publishes this file as a Claude skill (SKILL.md). Cursor reads the same SKILL.md shape. This page does not claim either product ships the file.

Copy agent prompt Get SKILL.md Source ↗

What the research says

Evidence not reviewed

Nobody has reviewed the evidence for this skill yet.

Let your agent do it

Copy a prompt for Claude Code, Codex, or Cursor.

Paste it into your coding agent in this repo. It does the setup and asks before anything leaves your machine.

Runs the same job in your agent session, on the plan you are signed in with. No API key, no Action.

Install the "Agent harness construction: action spaces, tools, observations" agent skill from AgentFlows (https://agentflows.sh/skills/affaan-m-agent-harness-construction) and use it with the plan I'm signed in with. No API key needed.

Install these agent skills first. Download each SKILL.md from its source (respect its license) into .claude/skills/<name>/SKILL.md, or wherever this agent loads skills from:
- Agent harness construction: action spaces, tools, observations: https://github.com/affaan-m/everything-claude-code/tree/main/skills/agent-harness-construction (MIT), notes at https://agentflows.sh/skills/affaan-m-agent-harness-construction

Then confirm the skill loaded, tell me in two lines when it kicks in, and offer to run it now on this repo.

The file

SKILL.md

Copy the upstream file, including its own frontmatter, into .claude/skills/affaan-m-agent-harness-construction/SKILL.md.

.claude/skills/affaan-m-agent-harness-construction/SKILL.md

---
name: agent-harness-construction
description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates. Use when defining or revising an agent's tool set, action space, or observation format.
metadata:
origin: ECC
---

# Agent Harness Construction

Use this skill when you are improving how an agent plans, calls tools, recovers from errors, and converges on completion.

## Core Model

Agent output quality is constrained by:
1. Action space quality
2. Observation quality
3. Recovery quality
4. Context budget quality

## Action Space Design

1. Use stable, explicit tool names.
2. Keep inputs schema-first and narrow.
3. Return deterministic output shapes.
4. Avoid catch-all tools unless isolation is impossible.

## Granularity Rules

- Use micro-tools for high-risk operations (deploy, migration, permissions).
- Use medium tools for common edit/read/search loops.
- Use macro-tools only when round-trip overhead is the dominant cost.

## Observation Design

Every tool response should include:
- `status`: success|warning|error
- `summary`: one-line result
- `next_actions`: actionable follow-ups
- `artifacts`: file paths / IDs

## Error Recovery Contract

For every error path, include:
- root cause hint
- safe retry instruction
- explicit stop condition

## Context Budgeting

1. Keep system prompt minimal and invariant.
2. Move large guidance into skills loaded on demand.
3. Prefer references to files over inlining long documents.
4. Compact at phase boundaries, not arbitrary token thresholds.

## Architecture Pattern Guidance

- ReAct: best for exploratory tasks with uncertain path.
- Function-calling: best for structured deterministic flows.
- Hybrid (recommended): ReAct planning + typed tool execution.

## Benchmarking

Track:
- completion rate
- retries per task
- pass@1 and pass@3
- cost per successful task

## Anti-Patterns

- Too many tools with overlapping semantics.
- Opaque tool output with no recovery hints.
- Error-only output without next steps.
- Context overloading with irrelevant references.