agent-harness-construction
affaan-m/everything-claude-code
Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
What is agent-harness-construction?
This skill helps you architect agent harnesses by defining clear action spaces, structuring tool outputs, and implementing error recovery patterns. Use it when building or improving agents that need to reliably plan, execute tools, and converge on task completion.
- Design stable, explicit tool definitions with schema-first inputs and deterministic outputs
- Structure observation responses with status, summary, next_actions, and artifacts fields
- Implement error recovery contracts with root cause hints, retry instructions, and stop conditions
- Apply granularity rules to choose between micro-tools, medium tools, and macro-tools based on risk and overhead
- Budget context by keeping system prompts minimal and loading large guidance on demand
- Select architecture patterns (ReAct, function-calling, or hybrid) based on task structure
How to install agent-harness-construction
npx skills add https://github.com/affaan-m/everything-claude-code --skill agent-harness-constructionHow to use agent-harness-construction
- 1.Audit your current tool definitions against the action space design rules (stable names, schema-first inputs, deterministic outputs)
- 2.Restructure all tool responses to include status, summary, next_actions, and artifacts fields
- 3.Document error paths for each tool with root cause hints, safe retry instructions, and explicit stop conditions
- 4.Evaluate tool granularity: identify high-risk operations for micro-tools, common loops for medium tools, and overhead-heavy operations for macro-tools
- 5.Choose an architecture pattern (ReAct for exploration, function-calling for deterministic flows, or hybrid for both)
- 6.Set up metrics tracking: completion rate, retries per task, pass@1/pass@3, and cost per successful task
Use cases
- Building a code deployment agent with high-risk operation isolation and explicit recovery paths
- Optimizing a file search and edit loop by balancing tool granularity against round-trip overhead
- Improving agent completion rates by restructuring tool outputs to include actionable next steps
- Designing a multi-phase agent that compacts context at phase boundaries to stay within token limits
- Debugging agent failures by tracking completion rate, retries, and cost metrics
- AI engineers designing agent systems
- Backend developers building tool-calling integrations
- Teams optimizing agent reliability and cost
- Developers implementing ReAct or function-calling patterns
agent-harness-construction FAQ
Use micro-tools for high-risk operations (deploy, migration, permissions) where isolation and explicit control matter. Use macro-tools only when round-trip overhead is the dominant cost. Use medium tools for common edit/read/search loops.
Every tool response should include: status (success|warning|error), summary (one-line result), next_actions (actionable follow-ups), and artifacts (file paths/IDs).
For every error path, include a root cause hint, a safe retry instruction, and an explicit stop condition so the agent knows when to give up.
ReAct is best for exploratory tasks with uncertain paths. Function-calling is best for structured deterministic flows. A hybrid approach (ReAct planning + typed tool execution) is recommended for most cases.
Keep system prompts minimal and invariant, move large guidance into skills loaded on demand, prefer file references over inlining long documents, and compact at phase boundaries rather than arbitrary token thresholds.
Full instructions (SKILL.md)
Source of truth, from affaan-m/everything-claude-code.
name: agent-harness-construction description: Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates. 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:
- 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.
Related skills
More from affaan-m/everything-claude-code and the wider catalog.
security-review
Security checklist and patterns for authentication, input validation, secrets, and sensitive features.
golang-patterns
Idiomatic Go patterns, best practices, and conventions for building robust, efficient, and maintainable applications.
coding-standards
Baseline coding conventions for naming, readability, immutability, and quality across projects.
frontend-patterns
React and Next.js patterns for components, state management, performance, and modern frontend practices.
backend-patterns
REST/GraphQL API design, database optimization, and server-side patterns for Node.js, Express, and Next.js.
golang-testing
Go testing patterns: table-driven tests, subtests, benchmarks, fuzzing, and TDD methodology.