agentleFS
Sign inStart free
gongyijie85gongyijie85/dsh-ecc/skills/agent-harness-construction/SKILL.md

agent-harness-construction

Skill8 starsChanged 3 months agoMITView on GitHub

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.

We split this skill into the rules it gives an agent

10 rules. 9 are common, 0 are distinctive, and 1 is very specific to this project.

  • 9

    Common

    Most of the 18 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

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

    line 10
  2. Common:

    Use stable, explicit tool names.

    line 22
  3. Common:

    Keep inputs schema-first and narrow.

    line 23
  4. Common:

    Avoid catch-all tools unless isolation is impossible.

    line 25
  5. Common:

    Use micro-tools for high-risk operations (deploy, migration, permissions).

    line 29
  6. Very specific:

    Use medium tools for common edit/read/search loops.

    line 30
  7. Common:

    Use macro-tools only when round-trip overhead is the dominant cost.

    line 31
  8. Common:

    Every tool response should include:

    line 35
  9. Common:

    Keep system prompt minimal and invariant.

    line 50
  10. Common:

    Prefer references to files over inlining long documents.

    line 52

“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free