agent-harness-builder-plus

Built on affaan-m/ECC by @affaan-m (239,509 stars, MIT). All credit for the original idea to them. This fork improves and repackages it; upstream license preserved in UPSTREAM_LICENSE.

A Claude Code skill for building safer, clearer AI agent tools, actions, and result formats.

🧠 Why

Agents fail when tools are vague.

They also fail when a tool hides what happened.

This skill helps you make small, clear tools. It shows agents how to report success, partial work, and errors.

Use it when you build or improve an agent harness.

⚡ Install

mkdir -p ~/.claude/skills/agent-harness-construction && curl -fsSL https://raw.githubusercontent.com/luke/agent-harness-builder-plus/main/SKILL.md -o ~/.claude/skills/agent-harness-construction/SKILL.md

🛠️ Usage

Ask Claude Code to use the skill while you design an agent or tool:

Use the agent-harness-construction skill. Design a safe publish_draft tool for my content app.

Expected result:

{
  "status": "warning",
  "summary": "The draft was prepared but needs approval before publishing.",
  "next_actions": ["Ask for approval, then call publish_draft once."],
  "artifacts": ["draft_482"]
}

📌 What it teaches

1. Give every tool one clear job.
2. Use clear names like read_file, search_code, and deploy_preview.
3. Make tool results use the same shape each time.
4. Show partial work when a step fails.
5. Limit retries and stop unsafe repeat actions.
6. Save key facts between work phases.
7. Keep large guides in skills or files, not every prompt.

🔁 What we changed vs upstream

• Translated the skill from Japanese to English and made the language more direct and instructional.
• Expanded abstract guidance with concrete tool-name, workflow, and JSON response examples.
• Added explicit status semantics, empty-list behavior, and partial-work reporting for tool results.
• Strengthened error recovery with retry limits, idempotency caution for risky actions, and a stop_condition example.
• Added more context-management guidance, including phase-boundary fact saving and avoiding compaction during risky actions.

📄 License

MIT. The upstream license is preserved in UPSTREAM_LICENSE.