Non-negotiable rules:
- Use the helper scripts under
.agents/skills/cost-estimate/helpers/ instead of redoing LOC,
session, or cost math manually.
- Keep scope explicit: full repo,
branch:<name>, or commit:<hash>.
- Separate raw engineering hours from organizational overhead and team multipliers.
- Keep the pricing rubric and report schema in references, not inline in the invocation path.
- Treat external market-rate research as optional. Use built-in rates unless the user explicitly
requests a different market or region.
Cost Estimate
Inputs
$request: Optional scope or estimation guidance such as branch:feat/foo, commit:abc1234,
region hints, or desired audience
Goal
Produce a credible estimate that:
- measures the requested code scope with the helper scripts
- classifies code into the right productivity buckets
- computes engineering hours and costs without double-counting overhead
- translates that estimate into realistic calendar and team-cost views
- reports assumptions, confidence, and Claude ROI clearly
Step 0: Resolve scope and mode
Parse the request into one of:
- full repository
branch:<name>
commit:<hash>
If the request is ambiguous, infer full repository by default. If the user supplied region or
market hints, carry them into the final rate discussion. Otherwise use the built-in baseline rates.
Success criteria: The estimation target and pricing basis are explicit before running scripts.
Step 1: Measure the real code surface with the helper scripts
Use the helper toolchain in .agents/skills/cost-estimate/helpers/:
loc_counter.py
git_session_analyzer.py
cost_calculator.py
report_generator.py
Run loc_counter.py for the resolved scope to capture:
- total lines
- file counts
- language breakdown
- directory breakdown
- source vs test vs config vs docs
- per-file category candidates from
all_files
Run git_session_analyzer.py when git history is available so Claude ROI can use actual session
estimates rather than LOC fallback.
Rules:
- prefer the script output over ad hoc
find, wc, or inline arithmetic
- if scope is a branch or commit, measure the diff rather than the full repository
- if git history is missing or unhelpful, fall back to LOC-based Claude hour estimates later
Success criteria: You have structured JSON for scope size and, when possible, active-session estimates.
Step 2: Classify the code into productivity buckets
Review the loc_counter.py output and map every relevant source line into exactly one category.
Use references/estimation-rates.md for:
- category keys
- productivity ranges
- overhead ranges
- market-rate baselines
- role multipliers
- organizational efficiency constants
- Claude ROI constants
Classification rules:
- assign each source line once
- keep tests, config/build, and documentation separate from product code
- detect specialized work such as GPU, native interop, audio/video, system extensions, or on-device ML
- do not inflate complexity without file-level evidence
- group files when a directory clearly shares one category, but call out exceptional files separately
Success criteria: There is a complete category-to-line-count JSON payload for the calculator.
Step 3: Run the calculator and sanity-check the output
Pipe the category totals into cost_calculator.py.
The calculator should produce:
- base coding hours
- overhead hours
- total estimated hours
- sanity-check effective lines/hour
- calendar-time tables
- engineering-only cost
- full-team cost
- Claude ROI fields when Claude hours are available
Rules:
- do not bake overhead into the category assignment; the calculator already adds overhead
- if the sanity check falls outside the target range, adjust category assignments or explain why this repo is legitimately outside the norm
- use built-in market rates by default unless the user explicitly requested a different market basis
Success criteria: The calculator output is internally consistent and the sanity check has been reviewed.
Step 4: Refine Claude ROI and confidence
If session data exists, inspect it and adjust only when the default commit-density heuristic is
obviously understating large-scope work. If session data is missing, use the fallback Claude
productivity constant from references/estimation-rates.md.
Report:
- estimated Claude active hours
- speed multiplier vs the baseline human rate
- value per Claude hour
- headline ROI and savings
Also state confidence:
- high when scope, category mix, and history are clean
- medium when history or categorization is incomplete
- low when the request is intentionally approximate or the repo is only partially available
Success criteria: The ROI story is explicit, bounded, and not overstated.
Step 5: Generate the report body
Use report_generator.py to generate the markdown backbone, then refine the narrative where needed.
Load references/report-contract.md for the required report structure and minimum sections.
The final estimate should cover:
- executive summary
- codebase metrics
- development-time estimate
- calendar-time view
- engineering-only cost
- full-team cost
- Claude ROI
- assumptions and caveats
Rules:
- lead with the executive summary and Claude ROI
- keep the report stakeholder-readable, not tool-dump heavy
- mention the scope basis explicitly
- preserve escaped currency formatting when editing prose manually
Success criteria: The estimate is readable, structured, and aligned with the report contract.
Guardrails
- Do not add
disable-model-invocation; this is a read-heavy analysis workflow.
- Do not add
paths:; this is a generic estimation skill.
- Do not keep pricing tables, role matrices, or full report templates inline in
SKILL.md.
- Do not replace helper-script output with manual math unless the helper chain is unavailable.
- Do not present a cost number without the scope, assumptions, and confidence level.
- Do not claim region-specific market validation unless the user explicitly requested it and that research was actually performed.
When To Load References
references/estimation-rates.md
Use for the productivity buckets, overhead rates, market-rate baselines, team multipliers,
efficiency constants, and Claude ROI fallback constants.
references/report-contract.md
Use for the mandatory section order, reporting contract, and required caveats.
Helper Scripts
.agents/skills/cost-estimate/helpers/loc_counter.py
- full repo: no flags
- branch diff:
--branch <name> (optionally --base <base>)
- single commit:
--commit <hash>
- output: JSON with
totals, by_language, by_directory, all_files
.agents/skills/cost-estimate/helpers/git_session_analyzer.py
- all commits: no flags
- specific branch:
--branch <name>
- output: JSON with
total_commits, total_sessions, estimated_active_hours, sessions[]
.agents/skills/cost-estimate/helpers/cost_calculator.py
- input: pipe category JSON on stdin
- flags:
--rate <hourly>, --claude-hours <N>
- valid category keys:
simple_crud_ui_boilerplate, standard_views, complex_ui, business_logic, database_persistence, audio_video_processing, gpu_shader, native_interop, system_extensions, on_device_ml, tests, config_build, documentation
- output: JSON with
base_coding, overhead, total_estimated_hours, sanity_check, calendar_time, engineering_cost, team_costs, claude_roi
.agents/skills/cost-estimate/helpers/report_generator.py
- flags:
--calc <costs.json>, --sessions <sessions.json>, --project <name>, --scope <desc>
- single section:
--section <name>
- available sections:
executive_summary, development_time, calendar_time, engineering_cost, team_cost, grand_total, claude_roi, assumptions
- output: ready-to-paste markdown
Use these directly. The judgment work in this skill is classification, calibration, and explanation,
not reimplementing the scripts.
Output Contract
Report:
- resolved scope and pricing basis
- key repo metrics and complexity drivers
- engineering hours and sanity-check result
- engineering-only and team-cost ranges
- Claude ROI and confidence level
- assumptions, caveats, and any missing-data limitations
1---
2name: cost-estimate
3version: 2.0.0
4description: |
5 Estimate what a codebase, branch diff, or single commit would COST to build — evidence-driven, not a
6 guess: measure the real scope with the helper scripts (LOC counter + git session analyzer), classify
7 every source line into one productivity bucket, run the cost calculator for engineering hours,
8 organizational overhead, calendar and team-cost views plus Claude ROI, and sanity-check the effective
9 lines/hour — runs as a forked analysis workflow with its own reasoning budget, isolated from the main
10 flow. Keeps raw engineering hours separate from overhead and team multipliers, never presents a number
11 without scope, assumptions, and a confidence level, and never claims region-specific market rates
12 unless the user asked and that research was actually done. Use when the user asks to estimate
13 development cost, effort, engineering hours, or ROI.
14allowed-tools:
15 - Bash
16 - Read
17 - Glob
18 - Grep
19context: fork
20agent: general-purpose
21effort: high
22argument-hint: "[full|branch:<name>|commit:<hash>]"
23arguments:
24 - request
25when_to_use: |
26 Use when the user asks to estimate development cost, effort, engineering hours, or ROI for the
27 current repository, a branch diff, or a specific commit. Examples: "estimate cost", "how much
28 would this codebase cost to build", "/cost-estimate branch:feat/foo", or "estimate this commit".
29 Do NOT use to budget hosted infrastructure, price SaaS plans, or to generate a project execution DAG
30 (that's plan-to-task-list-with-dag) — this prices building the code, nothing else.
31metadata:
32 source: https://skillmd.com/skills/ulpi-io/cost-estimate
33---
34
35<EXTREMELY-IMPORTANT>
36This skill is an evidence-driven estimation workflow.
37
38Non-negotiable rules:
391. Use the helper scripts under `.agents/skills/cost-estimate/helpers/` instead of redoing LOC,
40 session, or cost math manually.
412. Keep scope explicit: full repo, `branch:<name>`, or `commit:<hash>`.
423. Separate raw engineering hours from organizational overhead and team multipliers.
434. Keep the pricing rubric and report schema in references, not inline in the invocation path.
445. Treat external market-rate research as optional. Use built-in rates unless the user explicitly
45 requests a different market or region.
46</EXTREMELY-IMPORTANT>
47
48# Cost Estimate
49
50## Inputs
51
52- `$request`: Optional scope or estimation guidance such as `branch:feat/foo`, `commit:abc1234`,
53 region hints, or desired audience
54
55## Goal
56
57Produce a credible estimate that:
58
59- measures the requested code scope with the helper scripts
60- classifies code into the right productivity buckets
61- computes engineering hours and costs without double-counting overhead
62- translates that estimate into realistic calendar and team-cost views
63- reports assumptions, confidence, and Claude ROI clearly
64
65## Step 0: Resolve scope and mode
66
67Parse the request into one of:
68
69- full repository
70- `branch:<name>`
71- `commit:<hash>`
72
73If the request is ambiguous, infer full repository by default. If the user supplied region or
74market hints, carry them into the final rate discussion. Otherwise use the built-in baseline rates.
75
76**Success criteria**: The estimation target and pricing basis are explicit before running scripts.
77
78## Step 1: Measure the real code surface with the helper scripts
79
80Use the helper toolchain in `.agents/skills/cost-estimate/helpers/`:
81
82- `loc_counter.py`
83- `git_session_analyzer.py`
84- `cost_calculator.py`
85- `report_generator.py`
86
87Run `loc_counter.py` for the resolved scope to capture:
88
89- total lines
90- file counts
91- language breakdown
92- directory breakdown
93- source vs test vs config vs docs
94- per-file category candidates from `all_files`
95
96Run `git_session_analyzer.py` when git history is available so Claude ROI can use actual session
97estimates rather than LOC fallback.
98
99Rules:
100
101- prefer the script output over ad hoc `find`, `wc`, or inline arithmetic
102- if scope is a branch or commit, measure the diff rather than the full repository
103- if git history is missing or unhelpful, fall back to LOC-based Claude hour estimates later
104
105**Success criteria**: You have structured JSON for scope size and, when possible, active-session estimates.
106
107## Step 2: Classify the code into productivity buckets
108
109Review the `loc_counter.py` output and map every relevant source line into exactly one category.
110
111Use `references/estimation-rates.md` for:
112
113- category keys
114- productivity ranges
115- overhead ranges
116- market-rate baselines
117- role multipliers
118- organizational efficiency constants
119- Claude ROI constants
120
121Classification rules:
122
123- assign each source line once
124- keep tests, config/build, and documentation separate from product code
125- detect specialized work such as GPU, native interop, audio/video, system extensions, or on-device ML
126- do not inflate complexity without file-level evidence
127- group files when a directory clearly shares one category, but call out exceptional files separately
128
129**Success criteria**: There is a complete category-to-line-count JSON payload for the calculator.
130
131## Step 3: Run the calculator and sanity-check the output
132
133Pipe the category totals into `cost_calculator.py`.
134
135The calculator should produce:
136
137- base coding hours
138- overhead hours
139- total estimated hours
140- sanity-check effective lines/hour
141- calendar-time tables
142- engineering-only cost
143- full-team cost
144- Claude ROI fields when Claude hours are available
145
146Rules:
147
148- do not bake overhead into the category assignment; the calculator already adds overhead
149- if the sanity check falls outside the target range, adjust category assignments or explain why this repo is legitimately outside the norm
150- use built-in market rates by default unless the user explicitly requested a different market basis
151
152**Success criteria**: The calculator output is internally consistent and the sanity check has been reviewed.
153
154## Step 4: Refine Claude ROI and confidence
155
156If session data exists, inspect it and adjust only when the default commit-density heuristic is
157obviously understating large-scope work. If session data is missing, use the fallback Claude
158productivity constant from `references/estimation-rates.md`.
159
160Report:
161
162- estimated Claude active hours
163- speed multiplier vs the baseline human rate
164- value per Claude hour
165- headline ROI and savings
166
167Also state confidence:
168
169- high when scope, category mix, and history are clean
170- medium when history or categorization is incomplete
171- low when the request is intentionally approximate or the repo is only partially available
172
173**Success criteria**: The ROI story is explicit, bounded, and not overstated.
174
175## Step 5: Generate the report body
176
177Use `report_generator.py` to generate the markdown backbone, then refine the narrative where needed.
178
179Load `references/report-contract.md` for the required report structure and minimum sections.
180
181The final estimate should cover:
182
183- executive summary
184- codebase metrics
185- development-time estimate
186- calendar-time view
187- engineering-only cost
188- full-team cost
189- Claude ROI
190- assumptions and caveats
191
192Rules:
193
194- lead with the executive summary and Claude ROI
195- keep the report stakeholder-readable, not tool-dump heavy
196- mention the scope basis explicitly
197- preserve escaped currency formatting when editing prose manually
198
199**Success criteria**: The estimate is readable, structured, and aligned with the report contract.
200
201## Guardrails
202
203- Do not add `disable-model-invocation`; this is a read-heavy analysis workflow.
204- Do not add `paths:`; this is a generic estimation skill.
205- Do not keep pricing tables, role matrices, or full report templates inline in `SKILL.md`.
206- Do not replace helper-script output with manual math unless the helper chain is unavailable.
207- Do not present a cost number without the scope, assumptions, and confidence level.
208- Do not claim region-specific market validation unless the user explicitly requested it and that research was actually performed.
209
210## When To Load References
211
212- `references/estimation-rates.md`
213 Use for the productivity buckets, overhead rates, market-rate baselines, team multipliers,
214 efficiency constants, and Claude ROI fallback constants.
215
216- `references/report-contract.md`
217 Use for the mandatory section order, reporting contract, and required caveats.
218
219## Helper Scripts
220
221- `.agents/skills/cost-estimate/helpers/loc_counter.py`
222 - full repo: no flags
223 - branch diff: `--branch <name>` (optionally `--base <base>`)
224 - single commit: `--commit <hash>`
225 - output: JSON with `totals`, `by_language`, `by_directory`, `all_files`
226
227- `.agents/skills/cost-estimate/helpers/git_session_analyzer.py`
228 - all commits: no flags
229 - specific branch: `--branch <name>`
230 - output: JSON with `total_commits`, `total_sessions`, `estimated_active_hours`, `sessions[]`
231
232- `.agents/skills/cost-estimate/helpers/cost_calculator.py`
233 - input: pipe category JSON on stdin
234 - flags: `--rate <hourly>`, `--claude-hours <N>`
235 - valid category keys: `simple_crud_ui_boilerplate`, `standard_views`, `complex_ui`, `business_logic`, `database_persistence`, `audio_video_processing`, `gpu_shader`, `native_interop`, `system_extensions`, `on_device_ml`, `tests`, `config_build`, `documentation`
236 - output: JSON with `base_coding`, `overhead`, `total_estimated_hours`, `sanity_check`, `calendar_time`, `engineering_cost`, `team_costs`, `claude_roi`
237
238- `.agents/skills/cost-estimate/helpers/report_generator.py`
239 - flags: `--calc <costs.json>`, `--sessions <sessions.json>`, `--project <name>`, `--scope <desc>`
240 - single section: `--section <name>`
241 - available sections: `executive_summary`, `development_time`, `calendar_time`, `engineering_cost`, `team_cost`, `grand_total`, `claude_roi`, `assumptions`
242 - output: ready-to-paste markdown
243
244Use these directly. The judgment work in this skill is classification, calibration, and explanation,
245not reimplementing the scripts.
246
247## Output Contract
248
249Report:
250
2511. resolved scope and pricing basis
2522. key repo metrics and complexity drivers
2533. engineering hours and sanity-check result
2544. engineering-only and team-cost ranges
2555. Claude ROI and confidence level
2566. assumptions, caveats, and any missing-data limitations