Agent Harness Construction

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

Security Scan

This is an instruction-only skill that provides agent-design guidance and does not request credentials, install code, or perform actions outside its stated purpose.

Purpose & Capability

The name and description (designing agent action spaces, tool definitions, observation formatting) match the SKILL.md content. There are no unrelated requirements (no env vars, binaries, or install steps) that would be inconsistent with the stated purpose.

Instruction Scope

The instructions are high-level design guidance for building agent harnesses and do not instruct the agent to read specific system files, call external endpoints, or collect credentials. A mild caveat: the doc recommends 'prefer references to files over inlining long documents' and suggests loading skills on demand — these are reasonable design options but imply the agent may be directed to reference files or load other skills at runtime, so reviewers should ensure any referenced files/skills are vetted in their environment.

Install Mechanism

No install spec and no code files are present (instruction-only). Nothing will be written to disk or downloaded by the skill itself, which minimizes install-related risk.

Credentials

The skill declares no environment variables, credentials, or config paths. The guidance does not request secrets or cross-service credentials, so there is no disproportionate access requested.

Persistence & Privilege

always is false and model invocation is allowed (default). The skill does not request permanent presence or modify other skills or system settings. Autonomous invocation is normal for skills and does not raise additional concerns here.

Assessment

This skill is a coherent, read-only set of best practices for designing agent harnesses and does not itself access secrets or install code. Before using it in production, (1) review and vet any skills or files the agent will be instructed to load or reference (the guide encourages referencing files/on-demand skills), (2) enforce least privilege for any micro-tools you implement (especially for deploy/migration/permissions), and (3) monitor agent tool invocations and artifact paths to ensure sensitive data isn't exposed or written where it shouldn't be.

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.