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

| Unit | Definition | Scale |
|------|-----------|-------|
| **Round** | One tool-call cycle: think → write code → execute → verify → fix | ~2-4 min wallclock |
| **Module** | A functional unit built from multiple rounds until usable | 2-15 rounds |
| **Project** | All modules + integration + debugging | Sum of modules × integration factor |

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:

| Pattern | Typical Rounds | Examples |
|---------|---------------|----------|
| **Boilerplate / known pattern** | 1-2 | CRUD endpoint, config file, standard API client |
| **Moderate complexity** | 3-5 | Custom UI layout, state management, data pipeline |
| **Exploratory / under-documented** | 5-10 | Unfamiliar framework, platform-specific APIs, complex integrations |
| **High uncertainty** | 8-15 | Undocumented behavior, novel algorithms, multi-system debugging |

Key calibration rules:
- If you can...

# Agent Work Estimation Skill

An [Agent Skill](https://agentskills.io) 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](https://github.com/vercel-labs/skills) is the standard package manager for the open agent skills ecosystem. It works with Claude Code, Cursor, Codex CLI, and [35+ other agents](https://skills.sh).

```bash
# 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:

```bash
# 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 a...