Agent Estimation

Agent Work Estimation Skill

Problem

AI coding agents systematically overestimate task duration because they anchor to human developer timelines absorbed from training data. A task an agent can complete in 30 minutes gets estimated as "2-3 days" because that's what a human developer forum post would say.

Solution

Force the agent to estimate from its own operational units — tool-call rounds — and only convert to human wallclock time at the very end.

Core Units

A Round is the atomic unit. It maps directly to one iteration of: 1. Agent reasons about what to do 2. Agent writes/edits code 3. Agent runs the code or a test 4. Agent reads the output 5. Agent decides if it needs to fix something (if yes → next round)

Estimation Procedure

When asked to estimate a task, follow these steps in order:

Step 1: Decompose into Modules

Break the task into functional modules. Each module should be independently buildable and testable. Ask yourself: "What are the distinct pieces I would build one at a time?"

Step 2: Estimate Rounds per Module

For each module, estimate the number of rounds using these anchors:

Key calibration rules:

• If you can generate the code in one shot and it will likely run → 1 round
• If you'll need to generate, run, see an error, and fix → 2-3 rounds
• If the library/framework has sparse docs and you'll be guessing → 5+ rounds
• If it involves platform permissions, OS-level APIs, or environment-specific behavior the user must manually verify → add 2-3 rounds

Step 3: Assign Risk Coefficients

Each module gets a risk coefficient that inflates its round count:

Step 3.5: Construct Waves (Optional — for parallel / multi-agent scenarios)

If the task will be executed by multiple agents or the user asks for fastest completion:

1. Map dependencies: For each module, list which other modules it depends on 2. Group into waves:

• Wave 1: All modules with zero dependencies
• Wave 2: Modules whose dependencies are all in Wave 1
• Wave N: Modules whose dependencies are all in previous waves

3. Note agent count: How many agents can run in parallel within each wave

Skip this step for:

• Single-agent sequential execution
• Projects with < 3 modules
• Tightly coupled modules where parallelism gains are negligible

Step 4: Calculate Totals

Sequential mode (single agent, default):

Module effective rounds = base rounds × risk coefficient
Project rounds = Σ(module effective rounds) + integration rounds
Integration rounds = 10-20% of base total (for wiring modules together)

Wave mode (multi-agent):

Wave duration = max(effective rounds of modules in wave)
Project rounds = Σ(wave durations) + coordination rounds + integration rounds
Coordination rounds = 2-3 rounds upfront (contract definition between agents)

Step 5: Convert to Wallclock Time

Only at the very end, convert to human time:

Wallclock time = project rounds × minutes_per_round

Default minutes_per_round = 3 minutes (includes agent generation time + user review time).

Adjust this parameter based on context:

• Fast iteration, user barely reviews → 2 min/round
• Complex domain, user carefully reviews each step → 4 min/round
• User needs to manually test (mobile, hardware, permissions) → 5 min/round

Output Format

Always output the estimation in this exact structure:

### Task: [task name]

#### Module Breakdown

| # | Module | Base Rounds | Risk | Effective Rounds | Notes |
|---|--------|------------|------|-----------------|-------|
| 1 | ...    | N          | 1.x  | M               | why   |
| 2 | ...    | N          | 1.x  | M               | why   |

#### Summary

- **Base rounds**: X
- **Integration**: +Y rounds
- **Risk-adjusted total**: Z rounds
- **Sequential wallclock**: A – B minutes (at N min/round)

**Wave Execution** (if applicable):
- Wave 1: [modules] → max M rounds
- Wave 2: [modules] → max M rounds
- Coordination overhead: +C rounds
- **Parallel wallclock**: A – B minutes (at N min/round, K agents)
- **Speedup vs sequential**: ~X%

#### Biggest Risks
1. [specific risk and what could blow up the estimate]
2. [...]

Anti-Patterns to Avoid

These are the failure modes this skill exists to prevent:

1. Human-time anchoring: "A developer would take about 2 weeks..." → NO. Start from rounds. 2. Padding by vibes: Adding time "just to be safe" without specific risk rationale → NO. Use risk coefficients. 3. Confusing complexity with volume: 500 lines of boilerplate ≠ hard. One line of CGEvent API ≠ easy. Estimate by uncertainty, not line count. 4. Forgetting integration cost: Modules work alone but break together. Always add integration rounds. 5. Ignoring user-side bottlenecks: If the user must manually grant permissions, restart an app, or test on a device, that's extra round time. Adjust minutes_per_round, don't add phantom rounds. 6. Assuming parallelism is free: Multi-agent wave execution has coordination cost (contract definition, conflict resolution). Always add coordination rounds.

Calibration Reference

Here are example projects with known round counts to help calibrate:

See references/calibration-examples.md for detailed examples across project types.

Eval Prompts

See evals/evals.json for test cases to validate estimation accuracy.

Calibration Examples

Real-world project estimates using the round-based system. Use these to calibrate your estimates for similar tasks.

Small Projects (< 20 rounds)

CLI Tool — File Format Converter

Convert JSON to YAML with schema validation.

Static HTML Page with WebSocket Client

Phone-side client for a remote control app.

---

Medium Projects (20-50 rounds)

Desktop App — Keyboard Broadcaster (Makepad + Rust)

One Mac keyboard controlling 27 devices over LAN. (The KeyboardCast example.)

Wave Analysis (3 agents):

• Coordination overhead: +3 rounds (contract definition for server↔client protocol)
• Sequential wallclock: ~108 min (36 rounds × 3 min)
• Parallel wallclock: ~57 min (3 + 10 + 8 + 5 = 26 rounds × 3 min, minus overlap; effective ~19 wave rounds + 3 coordination + 5 integration = 27 rounds)
• Speedup vs sequential: ~47%

REST API with Auth + DB

Standard CRUD API with JWT auth and Postgres.

---

Large Projects (50-100+ rounds)

Full-Stack Dashboard with Real-Time Charts

React frontend + Rust backend + WebSocket streaming.

Wave Analysis (3 agents):

• Coordination overhead: +3 rounds (API contract, data schema alignment)
• Sequential wallclock: ~189 min (63 rounds × 3 min)
• Parallel wallclock: ~108 min (5 + 12 + 9 + 9 = 35 wave rounds + 3 coordination = 38 rounds × 3 min; with 3 agents effective ~36 rounds)
• Speedup vs sequential: ~43%

---

Estimation Accuracy Notes

These examples assume:

• The agent (Claude Code or similar) has access to the full codebase
• The user reviews but doesn't heavily rewrite agent output
• Standard development environment (no exotic toolchains)
• minutes_per_round = 3

Common sources of estimate blowup:

• Unfamiliar framework (e.g., first time with Makepad): +30-50% on UI modules
• Platform permissions (macOS accessibility, Android intents): +50-100% on that module
• Undocumented APIs: can 2x a module easily
• "One more thing" scope creep: user adds features mid-build, not captured in initial estimate

Common sources of estimate shrinkage:

• User provides existing code to extend: modules may drop to 1-2 rounds
• Agent has done this exact pattern before in the conversation: 1 round
• Copy-paste from a working sibling module: 1 round

Agent Work Estimation Skill

An Agent Skill that fixes how AI coding agents estimate task duration. Instead of anchoring to human developer timelines ("this would take 2-3 days"), the agent estimates from its own operational units — tool-call rounds — and converts to wallclock time only at the end.

The Problem

AI coding agents systematically overestimate task duration because they anchor to human developer timelines absorbed from training data. A task an agent can complete in 30 minutes gets estimated as "2-3 days" because that's what a human developer forum post would say.

The Solution

This skill forces the agent to think in rounds (one tool-call cycle: think → write code → execute → verify → fix), estimate round counts per module, apply risk coefficients, and only convert to human wallclock time at the very end.

Installation

Using npx skills (Recommended)

The skills CLI is the standard package manager for the open agent skills ecosystem. It works with Claude Code, Cursor, Codex CLI, and 35+ other agents.

# Install to your current project
npx skills add ZhangHanDong/agent-estimation

# Install globally (available across all projects)
npx skills add ZhangHanDong/agent-estimation -g

# Install for a specific agent
npx skills add ZhangHanDong/agent-estimation -a claude-code

# Non-interactive
npx skills add ZhangHanDong/agent-estimation -g -a claude-code -y

Manual Installation (Claude Code)

Clone the repo into your Claude Code skills directory:

# Personal (all projects)
git clone git@github.com:ZhangHanDong/agent-estimation.git \
  ~/.claude/skills/agent-estimation

# Project-specific
git clone git@github.com:ZhangHanDong/agent-estimation.git \
  .claude/skills/agent-estimation

Usage

Once installed, the skill activates automatically when you ask Claude (or another agent) to estimate, scope, or plan work. You can also invoke it directly:

/agent-estimation

Example Prompts

• "Estimate how long it would take to build a CLI tool that converts JSON to YAML"
• "How many rounds would it take to add JWT auth to this API?"
• "Scope out the work for adding dark mode to this app"

Example Output

### Task: CLI JSON-to-YAML Converter

#### Module Breakdown

| # | Module              | Base Rounds | Risk | Effective Rounds | Notes                      |
|---|---------------------|-------------|------|------------------|----------------------------|
| 1 | Arg parsing + I/O   | 1           | 1.0  | 1                | clap, one-shot             |
| 2 | JSON→YAML core      | 1           | 1.0  | 1                | serde, trivial             |
| 3 | Schema validation   | 3           | 1.3  | 4                | jsonschema crate, edge cases|
| 4 | Error handling + UX | 2           | 1.0  | 2                | polish                     |

#### Summary

- **Base rounds**: 7
- **Integration**: +1 round
- **Risk-adjusted total**: 8 rounds
- **Estimated wallclock**: ~24 minutes (at 3 min/round)

#### Biggest Risks
1. Schema validation edge cases with nested structures

How It Works

The skill teaches the agent a three-layer estimation framework:

Core Units

Estimation Procedure

1. Decompose the task into independently buildable modules 2. Estimate rounds per module using calibrated anchors (1-2 for boilerplate, 3-5 for moderate, 5-10 for exploratory, 8-15 for high uncertainty) 3. Apply risk coefficients (1.0 low → 2.0 very high) based on documentation quality, platform quirks, and integration unknowns 4. Construct waves (optional, for multi-agent): group modules by dependency into parallel batches, add coordination overhead 5. Add integration rounds (10-20% of base total) 6. Convert to wallclock only at the end (default: 3 min/round)

Anti-Patterns Prevented

• Human-time anchoring: "A developer would take about 2 weeks..." → Blocked
• Padding by vibes: Adding time "just to be safe" without rationale → Blocked
• Complexity ≠ volume: 500 lines of boilerplate ≠ hard; 1 line of CGEvent API ≠ easy
• Forgetting integration cost: Modules work alone but break together
• Ignoring user-side bottlenecks: Manual permission grants, device testing, etc.
• Assuming parallelism is free: Multi-agent coordination has real cost

Wave Execution Example

For multi-agent scenarios, the skill outputs both sequential and parallel estimates:

#### Summary

- **Base rounds**: 47
- **Integration**: +9 rounds
- **Risk-adjusted total**: 63 rounds
- **Sequential wallclock**: ~189 min (at 3 min/round)

**Wave Execution** (3 agents):
- Wave 1: [Backend API, React scaffold, Auth flow] → max 5 rounds
- Wave 2: [WebSocket streaming, Dashboard layout, Charts] → max 12 rounds
- Wave 3: [State management, Tests] → max 9 rounds
- Coordination overhead: +3 rounds
- **Parallel wallclock**: ~108 min (at 3 min/round, 3 agents)
- **Speedup vs sequential**: ~43%

Files

Compatibility

This skill follows the Agent Skills open standard and works with any compatible agent, including:

• Claude Code
• Cursor
• Codex CLI
• GitHub Copilot
• And many more

License

MIT