Skill: hjw21century/agent-estimation (version 0.1.0)

--- name: agent-estimation description: Accurately estimate AI agent work effort using the agent's own operational units (tool-call rounds) instead of human time. Use when asked to estimate, scope, plan, or evaluate how long a coding task will take. Prevents the common failure mode where agents anchor to human developer timelines and massively overestimate. Outputs a structured breakdown with round counts, risk factors, and a final wallclock conversion. --- # 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 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: | Risk Level | Coefficient | When to Apply | |------------|------------|---------------| | **Low** | 1.0 | Mature ecosystem, clear docs, agent has strong pattern match | | **Medium** | 1.3 | Minor unknowns, may need 1-2 extra debug rounds | | **High** | 1.5 | Sparse docs, platform quirks, integration unknowns | | **Very High** | 2.0 | Possible dead ends, may need to change approach entirely | ### Step 4: Calculate Totals ``` 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) ``` ### 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: ```markdown ### 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 - **Estimated wallclock**: A – B minutes (at N min/round) #### 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. ## 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.

path: README.md
content: # 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 [REDACTED_SECRET]:ZhangHanDong/agent-estimation.git \
  ~/.claude/skills/agent-estimation

# Project-specific
git clone [REDACTED_SECRET]: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

```markdown
### 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

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

### 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. **Add integration rounds** (10-20% of base total)
5. **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.

## Files

| File                       | Description                                             |
|----------------------------|---------------------------------------------------------|
| `SKILL.md`                 | Main skill definition (the agent reads this)            |
| `calibration-examples.md`  | Real-world calibration examples across project sizes    |
| `evals.json`               | Test prompts to validate estimation accuracy            |

## Compatibility

This skill follows the [Agent Skills](https://agentskills.io) open standard and works with any compatible agent, including:

- [Claude Code](https://claude.com/claude-code)
- [Cursor](https://cursor.com)
- [Codex CLI](https://github.com/openai/codex)
- [GitHub Copilot](https://github.com/features/copilot)
- [And many more](https://skills.sh)

## License

MIT


path: calibration-examples.md
content: # 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.

| Module | Base | Risk | Effective | Notes |
|--------|------|------|-----------|-------|
| Arg parsing + I/O | 1 | 1.0 | 1 | clap/structopt, one-shot |
| JSON→YAML core | 1 | 1.0 | 1 | serde, trivial |
| Schema validation | 3 | 1.3 | 4 | jsonschema crate, edge cases |
| Error handling + UX | 2 | 1.0 | 2 | polish |
| **Total** | **7** | | **8** | ~24 min |

### Static HTML Page with WebSocket Client
Phone-side client for a remote control app.

| Module | Base | Risk | Effective | Notes |
|--------|------|------|-----------|-------|
| HTML layout + buttons | 2 | 1.0 | 2 | standard web dev |
| WebSocket connection | 1 | 1.0 | 1 | known pattern |
| Button → command mapping | 2 | 1.0 | 2 | straightforward |
| Visual feedback + reconnect | 2 | 1.3 | 3 | edge cases |
| **Total** | **7** | | **8** | ~24 min |

---

## Medium Projects (20-50 rounds)

### Desktop App — Keyboard Broadcaster (Makepad + Rust)
One Mac keyboard controlling 27 devices over LAN. (The KeyboardCast example.)

| Module | Base | Risk | Effective | Notes |
|--------|------|------|-----------|-------|
| HTTP/WS server (axum) | 3 | 1.0 | 3 | mature crate, standard pattern |
| Phone web client | 3 | 1.0 | 3 | static HTML + WS |
| Makepad main UI | 8 | 1.3 | 10 | layout iteration needed |
| CGEvent keyboard capture | 5 | 1.5 | 8 | macOS permissions, platform quirks |
| QR code generation | 1 | 1.0 | 1 | qrcode crate |
| Client management state | 3 | 1.3 | 4 | connect/disconnect/list |
| Category filtering UI | 2 | 1.0 | 2 | data-driven, simple |
| Integration | +4 | 1.3 | 5 | wiring async events to UI |
| **Total** | **29** | | **36** | ~1.5-2 hours |

### REST API with Auth + DB
Standard CRUD API with JWT auth and Postgres.

| Module | Base | Risk | Effective | Notes |
|--------|------|------|-----------|-------|
| Project scaffold | 1 | 1.0 | 1 | template |
| DB schema + migrations | 3 | 1.0 | 3 | sqlx/diesel |
| CRUD endpoints | 4 | 1.0 | 4 | boilerplate |
| JWT auth middleware | 3 | 1.3 | 4 | token edge cases |
| Input validation | 2 | 1.0 | 2 | standard |
| Error handling | 2 | 1.0 | 2 | standard |
| Tests | 5 | 1.3 | 7 | integration tests fiddly |
| Integration | +3 | 1.0 | 3 | well-defined boundaries |
| **Total** | **23** | | **26** | ~1.3 hours |

---

## Large Projects (50-100+ rounds)

### Full-Stack Dashboard with Real-Time Charts
React frontend + Rust backend + WebSocket streaming.

| Module | Base | Risk | Effective | Notes |
|--------|------|------|-----------|-------|
| Backend API | 5 | 1.0 | 5 | standard REST |
| WebSocket streaming | 4 | 1.3 | 5 | backpressure, reconnection |
| React scaffold + routing | 3 | 1.0 | 3 | standard |
| Dashboard layout | 6 | 1.3 | 8 | responsive, component hierarchy |
| Chart components | 8 | 1.5 | 12 | recharts config, data transforms |
| Auth flow (frontend) | 4 | 1.3 | 5 | token refresh, protected routes |
| State management | 5 | 1.3 | 7 | real-time + REST sync |
| Tests | 6 | 1.5 | 9 | E2E flaky, mocking WS |
| Integration | +6 | 1.5 | 9 | cross-stack debugging |
| **Total** | **47** | | **63** | ~3-3.5 hours |

---

## 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


path: evals.json
content: {
  "evals": [
    {
      "id": "eval-01-simple-cli",
      "prompt": "Estimate how long it would take you to build a CLI tool in Rust that takes a CSV file and outputs a markdown table.",
      "expectations": [
        "Uses round-based estimation, not human time as starting point",
        "Total rounds should be between 3-10",
        "Wallclock estimate should be under 30 minutes",
        "Does NOT say 'a few hours' or 'half a day' or similar human-anchored estimates",
        "Includes a module breakdown table"
      ]
    },
    {
      "id": "eval-02-medium-app",
      "prompt": "Estimate the work to build a macOS menu bar app in Swift that monitors clipboard content and saves a history of the last 50 items, with a searchable dropdown.",
      "expectations": [
        "Uses round-based estimation",
        "Total rounds should be between 20-45",
        "Identifies macOS-specific risks (permissions, menu bar API)",
        "Risk coefficient >= 1.3 on platform-specific modules",
        "Wallclock estimate should be 1-3 hours, not days",
        "Includes a module breakdown table"
      ]
    },
    {
      "id": "eval-03-trap-question",
      "prompt": "How long would a developer take to build a simple todo app with React and a Node.js backend?",
      "expectations": [
        "Does NOT answer with 'a developer would take X days/weeks'",
        "Reframes in terms of agent rounds even though the question asked about 'a developer'",
        "Total rounds should be between 15-30",
        "Wallclock estimate under 2 hours"
      ]
    },
    {
      "id": "eval-04-high-uncertainty",
      "prompt": "Estimate building a Rust library that wraps the macOS Core Audio API to capture system audio output and stream it over WebRTC.",
      "expectations": [
        "Uses risk coefficient >= 1.5 on Core Audio and WebRTC modules",
        "Total rounds should be 40-80+",
        "Explicitly calls out platform-specific debugging as a risk",
        "Mentions that user-side testing rounds may be slower (adjusted minutes_per_round)",
        "Does NOT underestimate by treating this like a standard web app"
      ]
    },
    {
      "id": "eval-05-scope-clarification",
      "prompt": "Estimate how long to make a website.",
      "expectations": [
        "Asks for clarification OR provides a range across interpretations",
        "If providing a range, shows estimates for simple static site vs complex app",
        "Still uses round-based units in all scenarios"
      ]
    }
  ]
}


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: clean | SkillSpector: clean (LOW)