Design Agent Action Spaces
Improve how your AI plans and calls tools by defining stable action spaces and clear observation formats. It structures tool inputs and outputs, error recovery, and context budgeting for better completion rates and fewer failures.
affaan-m on GitHub
Curated by PromptsEdge from a public repo · MIT license. All credit goes to the author.
What is this skill?
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:
- Action space quality
- Observation quality
- Recovery quality
- Context budget quality
Action Space Design
- Use stable, explicit tool names.
- Keep inputs schema-first and narrow.
- Return deterministic output shapes.
- 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|errorsummary: one-line resultnext_actions: actionable follow-upsartifacts: file paths / IDs
Error Recovery Contract
For every error path, include:
- root cause hint
- safe retry instruction
- explicit stop condition
Context Budgeting
- Keep system prompt minimal and invariant.
- Move large guidance into skills loaded on demand.
- Prefer references to files over inlining long documents.
- 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.
Install this skill
- 1
Get the skill — it’s free
Use the Get this skill panel. Unlocked skills stay in My skills. - 2
Download or clone the files
Download the zip, or clone the repo and copy theskills/agent-harness-constructionfolder. - 3
Put it where your agent looks for skills
For Claude Code, use your personal skills folder (every project) or a project’s own folder:~/.claude/skills/agent-harness-construction/SKILL.md # all projects .claude/skills/agent-harness-construction/SKILL.md # this project only
- 4
Just ask
No command needed. The agent reads the skill’s description and loads it on its own when your request matches.
SKILL.md frontmatter
What your agent reads to decide when to load this skill.
--- 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. ---
Files
Open any Markdown file to read it here.
Related skills
View all →- Create and Improve SkillsFreeYour AI helps you create new skills or improve existing ones by drafting, testing, evaluating, and rewriting them. It runs test prompts, analyzes results quantitatively and qualitatively, and guides you through iterative refinement.
- Create and Evaluate SkillsFreeTurn manual workflows into agent skills, improve existing skills, or evaluate their quality. Your AI guides you through skill creation, benchmarking, and targeted improvements using best-practice patterns.
- Audit Workspace CapabilitiesFreeYour AI audits your repo, servers, plugins, and environment to reveal current capabilities and recommend next steps. It identifies available skills, hooks, agents, and missing integrations without exposing secrets.
- Verify Claude Code SessionsFreeYour AI runs a multi-step verification for Claude Code projects before completion. It checks builds, types, linting, tests, security scans, and code diffs to ensure quality and readiness for pull requests.