agent-harness-en

name

agent-harness-en

description

Design, diagnose, and improve a universal agent harness around actual usage context and task logic, decide whether an additional control layer is needed, and produce a minimum necessary structure or minimum correction with validation. Use when designing or reviewing agent architecture, analyzing long-running failures, deciding whether an issue belongs to the harness layer, or when user mentions harness, orchestration, state management, checkpoint, recovery, evaluation, human handoff, or observability.

Universal Agent Harness

Version: 1.1.0 Last Updated: 2026-03-26

Goal

This skill does one thing:

it works from actual usage context and real task logic to decide whether an additional harness layer is needed; if it is needed, it defines the minimum necessary structure; if an existing implementation is failing, it isolates the primary issue first, then proposes the smallest useful correction and a validation plan.

It does not exist to make systems look sophisticated, and it does not assume planning, long-term memory, checkpoints, evaluators, or human handoff by default.

Context First Principle

Harness structure serves the way a task is actually used in a real project, not an abstract task description alone.

The same task logic can justify very different harness decisions under different usage contexts.

At minimum, judge these dimensions before making harness decisions:

• who uses the system, or which upstream system calls it
• whether execution is synchronous, asynchronous, batch, event-driven, or human-triggered
• latency, throughput, and cost expectations
• tolerance for failure, delay, or degraded output
• real side effects, permission risk, or compliance needs
• whether human takeover is allowed and what it costs

If those dimensions are unclear, do not jump straight to harness conclusions.

File Roles

• SKILL.md: the main entry. Defines purpose, modes, workflow, output requirements, and hard constraints.
• TEMPLATE.md: the fixed output template. Both new-project design and existing-system review should use it.
• REFERENCE.md: the diagnostic library. Contains failure modes, observable signals, anti-patterns, thickness guidance, and recommended inspection order.
• ADVANCED.md: advanced judgment rules. Read it only when there are competing hypotheses, unclear ownership of the problem, or a real question about minimal fix versus structural redesign.

Default Read Order

1. Read this SKILL.md first.
2. Read TEMPLATE.md when you need a stable output shape.
3. Read REFERENCE.md when you need to classify the issue, inspect failure modes, or decide structure.
4. Read ADVANCED.md only for high-ambiguity or high-impact cases.

Supported Modes

Design Mode

Use for new project startup, pre-refactor structure design, or re-scoping after a task changes.

Main output:

• actual usage context
• task logic
• completion and stop conditions
• harness thickness judgment
• minimum necessary structure
• structures intentionally not introduced
• rollout and validation plan

Review Mode

Use for diagnosing an existing system, postmortem analysis, structural review, or remediation planning.

Main output:

• actual usage context
• current symptom
• evidence
• task logic and assumptions
• issue classification
• primary issue
• minimum correction
• validation plan
• validation status

When To Use It

• You need to decide whether an agent actually needs a thicker harness.
• You need to decide whether a failure comes from task definition, model, prompt, tool contract, or harness structure.
• You need to design structure for long-running, multi-step, side-effecting, or recovery-sensitive tasks.
• You need to review or minimally retrofit the harness of an existing system.
• You need to explain why one layer should be added and another should not.

When Not To Use It

• The task is a simple single-turn answer with low risk and no external action.
• The work is only about wording or prompt phrasing without structural judgment.
• The task goal, completion condition, and basic context are missing, so there is no reliable way to decide whether this is really a harness problem.

Required Inputs

Minimum for Design Mode

• actual usage context
• task goal
• primary inputs
• primary outputs
• completion condition
• main actions
• external dependencies
• side effects or risks

Minimum for Review Mode

• actual usage context
• symptom or failure pattern
• key facts about the current implementation
• known evidence
• task goal and completion condition
• recent failures, logs, metrics, or behavioral description

If the inputs are incomplete, do not pretend the issue is already located; write down your assumptions and the missing information explicitly.

Required Outputs

No matter which mode is used, the output must do all of the following:

• declare the current mode
• write actual usage context, task logic, and current assumptions first
• state whether the current architecture matches the usage context
• say whether the primary issue truly belongs to the harness layer
• focus on one primary issue or one primary structural decision
• attach evidence to each judgment, or state that evidence is missing
• propose a minimum necessary structure or minimum useful correction
• provide a validation plan
• avoid claiming improvement success before validation

Workflow

1. Identify whether the current task is design mode or review mode.
2. Judge the actual usage context, service target, trigger style, latency needs, risk, and tolerance boundaries.
3. Extract task logic, completion condition, stop condition, and key assumptions.
4. Decide whether the current architecture matches the context first, then decide whether the issue truly belongs to the harness layer rather than task definition, model capability, prompt organization, or tool contract.
5. Judge whether the harness should be thin, medium, or thick based on context and task logic.
6. Isolate one primary structural decision or one primary issue.
7. Propose the minimum necessary structure or smallest useful correction.
8. State which structures are intentionally not introduced and why.
9. Design validation and keep the conclusion conservative until validation exists.

Hard Constraints

• Do not build harness for the sake of having harness.
• Do not discuss architecture without grounding it in real usage context.
• Do not treat module completeness as the goal.
• Do not default to planning, long-term memory, checkpoints, independent evaluation, or human handoff.
• Do not infer a structural problem from a single failure by default.
• Do not treat retry as a complete recovery strategy.
• Do not confuse observed symptoms with root cause.
• Do not over-attribute when evidence is weak.
• Do not claim success without validation.

Default Loop

This skill works around the following loop:

1. identify one primary issue or one primary structural decision
2. provide evidence or clearly state evidence gaps
3. propose the minimum necessary change
4. provide a validation plan
5. do not claim success before validation succeeds

Output Rule

Use the matching template in TEMPLATE.md by default.

If the user does not want a long response, keep the answer compact, but do not omit:

• actual usage context
• task logic and assumptions
• context-to-architecture fit judgment
• primary judgment
• evidence
• minimum change
• validation plan
• current validation status

Boundary With Other Problem Types

When the problem looks more like one of the following, say so explicitly instead of forcing it into the harness layer:

• the real usage context has not been identified yet
• the task goal itself is unclear
• the model capability ceiling is too low
• the prompt structure is obviously wrong
• the tool interface itself is unstable
• the data source itself is broken

Only when the issue lives in state organization, stage boundaries, control points, recovery strategy, verification loop, human handoff, observability, or stopping conditions should it primarily be treated as a harness problem.

Exit Criteria

Only call the result an “improvement proposal” when all of these are true:

• actual usage context is explicit
• task logic and assumptions are explicit
• context-to-architecture fit is explicit
• one primary issue or one primary structural decision is explicit
• evidence or evidence gaps are explicit
• a minimum correction or minimum necessary structure is explicit
• a validation method is explicit

Only call the result “confirmed improvement” after real validation passes.