<SYSTEM>This is the full developer documentation for HTMA Measure</SYSTEM>

# HTMA Measure

> Turn uncertain costs, risks, ROI, and market questions into sourced ranges you can act on.

Public and available

HTMA Measure is published at [`ThatGuySam/skills`](https://github.com/ThatGuySam/skills). The current plugin release is **0.1.1**, and the same skill works through the open Skills CLI, Codex plugins, Claude Code plugins, or a manual copy.

Ranges, not false precision

Every estimate includes a low bound, central estimate, high bound, and confidence level.

Decisions, not trivia

The workflow starts with the decision threshold and stops measuring when more information cannot change the action.

Evidence with provenance

Confirmed facts, assumptions, inference, source quality, and freshness stay visibly separate.

Human and machine output

Each memo ends with a validated `HTMA_RESULT` JSON appendix without replacing the written reasoning.

## Choose your path

[Section titled “Choose your path”](#choose-your-path)

[Install with npx skills ](/guides/installation/#open-skills-cli)The portable path for Codex and many other agents.

[Install as a Codex plugin ](/guides/installation/#codex-plugin)Add the marketplace, then add the plugin.

[Install in Claude Code ](/guides/installation/#claude-code-plugin)Use the same repository as a Claude plugin marketplace.

[Write your first prompt ](/guides/first-measurement/)Define the decision, threshold, quantity, and evidence.

## Machine-readable documentation

[Section titled “Machine-readable documentation”](#machine-readable-documentation)

Agents can read the entire documentation corpus in one request:

* [`/llms.txt`](/llms.txt) — a curated map.
* [`/llms-full.txt`](/llms-full.txt) — every documentation page concatenated.
* [`/llms-small.txt`](/llms-small.txt) — a compact variant.

# Data model

> The entities that connect decisions, evidence, component ranges, uncertainty, and the final HTMA_RESULT.

The skill is Markdown-driven, but its output follows a stable conceptual model.

## Decision context

[Section titled “Decision context”](#decision-context)

```ts
type DecisionContext = {
  decision: string
  quantity: string
  unit: string
  timeHorizon: string
  threshold: number | string | null
  costOfBeingWrong: string
  estimateMode: string
}
```

## Evidence

[Section titled “Evidence”](#evidence)

```ts
type Evidence = {
  label: string
  value: number | string
  sourceUrl?: string
  observedAt?: string
  classification: "confirmed" | "assumption" | "inference"
  quality: "high" | "medium" | "low"
  freshness: "current" | "aging" | "stale" | "unknown"
}
```

## Decomposition

[Section titled “Decomposition”](#decomposition)

```ts
type ComponentEstimate = {
  component: string
  low: number
  central: number
  high: number
  confidence: string
  basis: string
  whatWouldTighten: string
}
```

## Remaining uncertainty

[Section titled “Remaining uncertainty”](#remaining-uncertainty)

```ts
type MeasurementCandidate = {
  uncertainty: string
  measurement: string
  costOrEffort: string
  expectedDecisionImpact: string
  stopWhen: string
}
```

## Result relationships

[Section titled “Result relationships”](#result-relationships)

```text
Decision context
      │
      ├── Evidence ──> Component estimates
      │                    │
      │                    └──> Calibrated interval
      │                               │
      └── Threshold ──────────────────┤
                                      ├──> Decision implication
Remaining uncertainty ────────────────┘
              │
              └──> Next measurement step


All sections ──> Written memo + HTMA_RESULT
```

The written memo preserves reasoning and provenance. `HTMA_RESULT` preserves stable fields for scoring, automation, and later calibration review.

# Distribution model

> How one canonical skill reaches the Skills CLI, Codex, Claude Code, and manual consumers.

HTMA Measure publishes one source directory and points every installer at it.

## Canonical source

[Section titled “Canonical source”](#canonical-source)

```text
skills/htma-measure/
```

The folder contains the discovery metadata, core instructions, conditional references, output template, and UI metadata.

## Open Skills CLI

[Section titled “Open Skills CLI”](#open-skills-cli)

The CLI clones the repository, discovers `skills/htma-measure/SKILL.md`, and copies or links that directory into the selected agent’s skill location. It records the source, skill path, and content hash in a lock file.

## Codex

[Section titled “Codex”](#codex)

Codex first clones the repository as a marketplace snapshot. The marketplace catalog exposes `htma-measure`, and `.codex-plugin/plugin.json` points the installed plugin at `./skills/`.

## Claude Code

[Section titled “Claude Code”](#claude-code)

Claude clones the repository as a marketplace. The plugin entry uses `"source": "./"`, so Claude copies the plugin from the same checkout instead of cloning the public repository a second time.

## Manual consumers

[Section titled “Manual consumers”](#manual-consumers)

Any compatible agent can load `SKILL.md` directly and resolve its relative `references/`, `assets/`, and `agents/` paths.

## Versioning

[Section titled “Versioning”](#versioning)

* Codex and root plugin metadata currently report `0.1.1`.
* Plugin metadata changes bump the version so cached installations can update.
* The Open Skills CLI tracks the skill folder’s content hash independently.
* Documentation deploys do not duplicate or rewrite the canonical skill.

# Motivation

> Why an agent needs a decision-first measurement workflow instead of another estimation prompt.

A general-purpose agent can always produce a number. The hard part is producing a range that is honest enough to use and structured enough to improve.

## The problem

[Section titled “The problem”](#the-problem)

Two common approaches fail in opposite ways:

* **A quick point estimate** is cheap but hides the uncertainty that controls the decision.
* **Open-ended research** collects more facts but often lacks a threshold, source hierarchy, or stopping rule.

Both can create confident output without decision value. A third failure—simulation laundering—adds mathematical machinery to weak assumptions and makes the result look more trustworthy than it is.

## The mental model

[Section titled “The mental model”](#the-mental-model)

Measurement is valuable when it changes a decision. The workflow therefore begins with the decision threshold, decomposes the uncertain quantity, and buys information only where it can change the action.

A range is not an admission of failure. It is the honest shape of the available knowledge.

## Key design decisions

[Section titled “Key design decisions”](#key-design-decisions)

* **Decision before research.** A threshold determines which uncertainty matters. (Consequence: vague prompts sometimes require clarification before browsing.)
* **Ranges before simulation.** Calibrated inputs carry the real epistemic work. (Consequence: the skill refuses decorative Monte Carlo output.)
* **Source provenance in the memo.** Facts, assumptions, and inference remain distinguishable. (Consequence: the memo is longer than a bare answer.)
* **A structured appendix, not a structured substitute.** JSON supports reuse while the prose preserves reasoning. (Consequence: every output has two representations to keep aligned.)
* **Missing inputs stay missing.** Blocked estimates use null numeric fields and an explicit status. (Consequence: the workflow sometimes declines to estimate.)

## Alternatives considered

[Section titled “Alternatives considered”](#alternatives-considered)

* **A single reusable prompt.** Too easy for an agent to skip thresholds, source grading, or verification.
* **A calculator-only tool.** Reliable arithmetic, but no judgment about target mode, evidence quality, or decision relevance.
* **A simulation-first workflow.** Precise output cannot rescue uncalibrated inputs.
* **A full HTMA suite as a hard dependency.** More power, but worse portability. Companion skills remain optional.

## Non-goals

[Section titled “Non-goals”](#non-goals)

HTMA Measure is not:

* a guarantee that uncertain forecasts become accurate;
* a replacement for authoritative current data;
* a license to infer private financial facts;
* a full statistical software package; or
* a substitute for reviewing sources and assumptions.

# Design principles

> The rules that keep HTMA Measure portable, honest, and decision-relevant.

## Decision relevance first

[Section titled “Decision relevance first”](#decision-relevance-first)

Every estimate exists to support an action. If no plausible result can change the decision, further measurement has low value.

## Intervals over false precision

[Section titled “Intervals over false precision”](#intervals-over-false-precision)

A point estimate can appear in the center of a range, but never by itself. Bounds and confidence are part of the answer.

## Provenance over plausibility

[Section titled “Provenance over plausibility”](#provenance-over-plausibility)

The memo labels direct evidence, assumptions, reference classes, and inference. Current claims require current sources.

## Smallest useful method

[Section titled “Smallest useful method”](#smallest-useful-method)

Clarification, decomposition, calibrated ranges, small samples, value of information, and simulation are tools—not a ritual. Use only the smallest method that reduces decision-relevant uncertainty.

## Portable core, optional companions

[Section titled “Portable core, optional companions”](#portable-core-optional-companions)

The published skill works by itself. Other HTMA skills can deepen a step, but missing companion skills never break the core workflow.

## Refuse fabricated completeness

[Section titled “Refuse fabricated completeness”](#refuse-fabricated-completeness)

When a responsible number requires an identifier, effective period, jurisdiction, lookup, or private fact, numeric fields remain `null`. The status explains what is missing and how to unlock the estimate.

## Verification is part of the output

[Section titled “Verification is part of the output”](#verification-is-part-of-the-output)

Before finalizing, the agent checks units, interval consistency, source provenance, sensitive information, threshold implications, and JSON/prose agreement.

# Calibrated estimates

> Produce low, central, and high estimates tied to an explicit confidence level and decision threshold.

Calibrated estimates replace a precise-looking guess with a defensible interval and an explicit decision implication.

## Behavior

[Section titled “Behavior”](#behavior)

1. The user supplies an uncertain quantity and the decision it informs.
2. The agent identifies the unit, time horizon, threshold, and cost of being wrong.
3. The agent classifies the target mode: paid quote, market value, budget allowance, amount likely paid, official benchmark, or ambiguous.
4. The quantity is decomposed into smaller uncertain components.
5. Each component receives a low, central, and high value with a stated basis.
6. The agent calibrates the rolled-up interval and states its confidence.
7. The final interval is compared with the decision threshold.
8. The memo states the action implication and the largest remaining uncertainty.

The agent does not return only a point estimate.

## Inputs & outputs

[Section titled “Inputs & outputs”](#inputs--outputs)

**Inputs**

* decision statement;
* quantity of interest;
* unit;
* time horizon;
* decision threshold;
* cost of being wrong;
* evidence, source links, files, observations, and constraints; and
* optional requested confidence level.

**Outputs**

* calibrated range;
* central estimate;
* confidence statement;
* decomposition table;
* threshold implication;
* top uncertainty driver;
* recommendation; and
* structured `HTMA_RESULT` appendix.

## States & edge cases

[Section titled “States & edge cases”](#states--edge-cases)

| State                                 | Behavior                                                                     |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| Complete evidence                     | Return a calibrated memo with `estimate_status: "estimated"`.                |
| Vague decision                        | Ask for the missing decision or threshold before external research.          |
| Missing identifier                    | Keep numeric fields null and return `needs_identifier`.                      |
| Missing effective period              | Keep numeric fields null and return `needs_effective_period`.                |
| Current authoritative lookup required | Return `lookup_required` until the source is refreshed.                      |
| Private fact missing                  | Name it in `blocking_missing_inputs`; do not infer it.                       |
| Inputs too weak for a range           | Return `not_estimable` and the next measurement step.                        |
| Range crosses the threshold           | Explain the decision sensitivity instead of forcing a yes/no recommendation. |
| Monte Carlo requested too early       | Decompose and calibrate inputs before simulation.                            |

## Data shape

[Section titled “Data shape”](#data-shape)

```ts
type EstimateContext = {
  decision: string
  quantity: string
  unit: string
  timeHorizon: string
  decisionThreshold: number | string | null
  costOfBeingWrong: string
  estimateMode:
    | "paid quote"
    | "market value"
    | "budget allowance"
    | "amount likely paid"
    | "official/public benchmark"
    | "ambiguous"
  evidence: EvidenceItem[]
}


type ComponentRange = {
  component: string
  low: number
  central: number
  high: number
  confidence: string
  basis: string
  whatWouldTighten: string
}
```

## Decisions

[Section titled “Decisions”](#decisions)

* **2026-07-11 — Intervals are mandatory.** A central value without bounds hides the uncertainty the skill exists to expose.
* **2026-07-11 — Missing required inputs produce nulls.** Fabricated completeness is worse than a blocked result.

## Open questions

[Section titled “Open questions”](#open-questions)

None for the current release.

# Measurement memos

> Return a durable written analysis and a matching HTMA_RESULT JSON appendix.

The measurement memo makes an estimate reviewable by a human and reusable by software.

## Behavior

[Section titled “Behavior”](#behavior)

1. The memo opens with a compact relevance summary.
2. It makes the question precise and presents the short answer.
3. It records priors and sources with quality notes.
4. It decomposes the quantity into components.
5. It explains the calibrated range rather than merely printing it.
6. It ranks uncertainties by value of information.
7. It states what would move the estimate up or down.
8. It connects the estimate to the decision.
9. It ends with valid JSON whose numeric and status fields match the prose.

The JSON is an appendix. It never replaces the reasoning unless the user explicitly requests JSON-only output.

## Inputs & outputs

[Section titled “Inputs & outputs”](#inputs--outputs)

**Inputs**

* a completed estimate context;
* evidence and source provenance;
* component ranges;
* threshold comparison; and
* remaining uncertainties.

**Outputs**

A Markdown memo with:

* relevance summary;
* date and scope;
* precise question;
* short answer;
* priors and sources;
* decomposition;
* calibrated range;
* value of information;
* recommendation;
* source list; and
* `HTMA_RESULT`.

The bundled template lives at `assets/measurement-brief-template.md`.

## States & edge cases

[Section titled “States & edge cases”](#states--edge-cases)

| State               | Behavior                                                               |
| ------------------- | ---------------------------------------------------------------------- |
| Estimated           | Numeric fields contain the final range and central estimate.           |
| Blocked             | Numeric fields are null; status and missing inputs explain why.        |
| Mixed units         | The memo stops and normalizes units before rolling up components.      |
| JSON parse failure  | The output fails verification and must be corrected.                   |
| Prose/JSON mismatch | The output fails verification and must be reconciled.                  |
| Sensitive input     | Omit it or use `[ask user]` unless inclusion is explicitly authorized. |
| Source unavailable  | Mark the claim unverified or return a lookup-required status.          |

## Data shape

[Section titled “Data shape”](#data-shape)

```ts
type EstimateStatus =
  | "estimated"
  | "needs_clarification"
  | "needs_identifier"
  | "needs_effective_period"
  | "lookup_required"
  | "not_estimable"


type HTMAResult = {
  quantity: string
  unit: string
  low_90: number | null
  central: number | null
  high_90: number | null
  confidence: string
  decision_threshold: number | string | null
  threshold_implication: string
  top_uncertainty_driver: string
  estimate_status: EstimateStatus
  blocking_missing_inputs: string[]
  assumed_target: string | null
  next_measurement_step: string
}
```

## Decisions

[Section titled “Decisions”](#decisions)

* **2026-07-11 — Prose and JSON ship together.** Humans need reasoning; automation needs stable fields.
* **2026-07-11 — The template includes every output-contract field.** A partial appendix is not a valid memo.

## Open questions

[Section titled “Open questions”](#open-questions)

None for the current release.

# Sources & value of information

> Rank evidence quality, freshness, and the next measurement by its ability to change the decision.

Source collection is not the goal. The skill gathers and measures information only when it improves the estimate or changes the action.

## Behavior

[Section titled “Behavior”](#behavior)

1. The agent gathers available local context before web research.
2. Direct evidence, official sources, reference classes, and comparable cases are listed separately.
3. Every source is judged against the exact estimate target for quality and freshness.
4. Facts are distinguished from assumptions and inference.
5. Remaining uncertainties are ranked by their decision impact.
6. The agent proposes the cheapest credible next measurement.
7. Research stops when additional evidence cannot change the decision.

For local nonprofit, community, or relationship-priced work, the agent models both full-market pricing and plausible paid-quote pricing. It never applies that adjustment to official fees, statutory rates, or current public benchmarks.

## Inputs & outputs

[Section titled “Inputs & outputs”](#inputs--outputs)

**Inputs**

* estimate target and mode;
* decision threshold;
* available sources and observations;
* source dates and provenance;
* reference classes;
* remaining uncertainties; and
* cost or effort of additional measurements.

**Outputs**

* source/anchor table;
* source-quality and freshness notes;
* confirmed fact / assumption / inference separation;
* ranked value-of-information table;
* top uncertainty driver;
* next measurement step; and
* stopping rule.

## States & edge cases

[Section titled “States & edge cases”](#states--edge-cases)

| State                          | Behavior                                                           |
| ------------------------------ | ------------------------------------------------------------------ |
| Fresh direct source            | Use it as a confirmed anchor.                                      |
| Indirect comparable            | Use it as a reference class and label the inference.               |
| Stale source                   | Refresh it or weaken confidence.                                   |
| Conflicting sources            | Preserve the disagreement and widen the range.                     |
| Small sample                   | Update cautiously and keep the interval calibrated to sample size. |
| Sensitive private evidence     | Use only when the user explicitly authorizes inclusion.            |
| Easy but irrelevant metric     | Do not measure it if it cannot change the decision.                |
| Discounted local context       | Model a realistic paid scenario and stress-test the low bound.     |
| Official fee or statutory rate | Use the current official source without local discounting.         |

## Data shape

[Section titled “Data shape”](#data-shape)

```ts
type EvidenceItem = {
  label: string
  value: number | string
  sourceUrl?: string
  observedAt?: string
  kind: "direct" | "official" | "reference-class" | "assumption" | "inference"
  quality: "high" | "medium" | "low"
  freshness: "current" | "aging" | "stale" | "unknown"
  relevance: string
}


type ValueOfInformationItem = {
  rank: number
  uncertainty: string
  whyItMatters: string
  measurement: string
  expectedDecisionImpact: string
  stopWhen: string
}
```

## Decisions

[Section titled “Decisions”](#decisions)

* **2026-07-11 — Source relevance is target-specific.** A reputable source can still be a weak anchor for the quantity being estimated.
* **2026-07-11 — Research has a stopping rule.** More citations are not automatically more decision value.

## Open questions

[Section titled “Open questions”](#open-questions)

None for the current release.

# Command reference

> Copyable commands to discover, install, inspect, update, and remove HTMA Measure.

## Open Skills CLI

[Section titled “Open Skills CLI”](#open-skills-cli)

Discover:

```bash
npx skills add thatguysam/skills --list
```

Install in the current project:

```bash
npx skills add thatguysam/skills --skill htma-measure
```

Install for Codex without prompts:

```bash
npx skills add thatguysam/skills --skill htma-measure --agent codex --yes
```

List installed Codex skills:

```bash
npx skills list --agent codex
```

Update the skill:

```bash
npx skills update htma-measure --yes
```

Remove it from Codex:

```bash
npx skills remove htma-measure --agent codex --yes
```

## Codex plugin

[Section titled “Codex plugin”](#codex-plugin)

Add and install:

```bash
codex plugin marketplace add thatguysam/skills
codex plugin add htma-measure@thatguysam-skills
```

Inspect:

```bash
codex plugin marketplace list --json
codex plugin list --json
```

Refresh the marketplace:

```bash
codex plugin marketplace upgrade thatguysam-skills --json
```

Remove the plugin:

```bash
codex plugin remove htma-measure@thatguysam-skills --json
```

## Claude Code plugin

[Section titled “Claude Code plugin”](#claude-code-plugin)

Add and install:

```bash
claude plugin marketplace add thatguysam/skills
claude plugin install htma-measure@thatguysam-skills
```

Inspect:

```bash
claude plugin list --json
```

Update:

```bash
claude plugin update htma-measure@thatguysam-skills
```

Remove:

```bash
claude plugin uninstall htma-measure@thatguysam-skills --yes
```

## Repository

[Section titled “Repository”](#repository)

Clone:

```bash
git clone https://github.com/ThatGuySam/skills.git
cd skills
```

Validate the skill frontmatter with the OpenAI skill-creator validator when available:

```bash
python3 /path/to/skill-creator/scripts/quick_validate.py skills/htma-measure
```

The validator requires PyYAML. If that dependency is not installed, parse the YAML with another standards-compliant YAML parser and apply the same name/description checks.

# Your first measurement

> Write a decision-ready HTMA Measure prompt and understand the memo it returns.

After installation, ask your agent to use `htma-measure`. Clients that support explicit skill selectors expose the skill by name; the examples here use `$htma-measure`.

## Start with the decision

[Section titled “Start with the decision”](#start-with-the-decision)

A strong prompt supplies six pieces of context:

1. **Decision:** what action depends on the estimate?
2. **Quantity:** what exactly is being estimated?
3. **Unit:** dollars, hours, percentage points, users, incidents, or another unit?
4. **Time horizon:** per month, over one year, by a launch date, or for a one-time purchase?
5. **Threshold:** what result changes the decision?
6. **Evidence:** what facts, files, URLs, quotes, or observations are already available?

## Minimal prompt

[Section titled “Minimal prompt”](#minimal-prompt)

```text
Use $htma-measure to estimate the total implementation cost of this project.


Decision: approve or defer the project.
Quantity: total implementation cost in USD.
Time horizon: implementation through production launch.
Decision threshold: approve if the 90% high bound is below $75,000.
Available evidence: the attached scope, two vendor rates, and our last three project actuals.
```

## What the agent does

[Section titled “What the agent does”](#what-the-agent-does)

The skill:

1. clarifies any missing decision inputs;
2. classifies the estimate mode;
3. gathers local context before external research;
4. separates confirmed facts from assumptions and inference;
5. decomposes the quantity into low / central / high components;
6. calibrates the final interval;
7. compares it with the threshold;
8. ranks the next useful measurement; and
9. returns a written memo plus `HTMA_RESULT` JSON.

## Read the short answer first

[Section titled “Read the short answer first”](#read-the-short-answer-first)

A useful short answer looks like this structure:

```text
Calibrated range: $48,000–$82,000 (90%)
Central estimate: $63,000
Decision implication: the interval crosses the $75,000 approval threshold.
Next measurement: obtain a fixed quote for data migration, the largest uncertainty driver.
```

Those numbers are only a format example, not a real estimate. Your memo’s values must come from your supplied evidence and traceable sources.

## If key inputs are missing

[Section titled “If key inputs are missing”](#if-key-inputs-are-missing)

The skill does not fabricate a range. It returns null numeric fields and a status such as:

* `needs_clarification`
* `needs_identifier`
* `needs_effective_period`
* `lookup_required`
* `not_estimable`

Use `blocking_missing_inputs` and `next_measurement_step` to unlock the estimate.

## Improve the result

[Section titled “Improve the result”](#improve-the-result)

If the first interval is too wide, do not ask the agent to “be more precise.” Ask it to rank the evidence that would reduce decision-relevant uncertainty:

```text
Using the current memo, rank the remaining unknowns by value of information.
Tell me which single measurement is most likely to change the decision and when further research stops mattering.
```

# Installation

> Install HTMA Measure with npx skills, Codex plugins, Claude Code plugins, or a manual copy.

Choose one installation path. They all expose the same `skills/htma-measure` content.

## Open Skills CLI

[Section titled “Open Skills CLI”](#open-skills-cli)

This is the most portable path. The command is `npx skills`—plural.

List the skills found in the repository without installing:

```bash
npx skills add thatguysam/skills --list
```

Install only HTMA Measure into the current project:

```bash
npx skills add thatguysam/skills --skill htma-measure
```

Install non-interactively for Codex:

```bash
npx skills add thatguysam/skills \
  --skill htma-measure \
  --agent codex \
  --yes
```

Install globally instead of in one project:

```bash
npx skills add thatguysam/skills \
  --skill htma-measure \
  --agent codex \
  --global \
  --yes
```

A project-scoped Codex install lands at:

```text
.agents/skills/htma-measure/
```

To disable the Skills CLI’s anonymous telemetry for an install:

```bash
DISABLE_TELEMETRY=1 npx skills add thatguysam/skills \
  --skill htma-measure \
  --agent codex \
  --yes
```

## Codex plugin

[Section titled “Codex plugin”](#codex-plugin)

Register the public marketplace, then install the plugin:

```bash
codex plugin marketplace add thatguysam/skills
codex plugin add htma-measure@thatguysam-skills
```

Verify that it is installed and enabled:

```bash
codex plugin list --json
```

The plugin reports its version and marketplace source. Release `0.1.1` installs without additional authentication because the repository is public.

## Claude Code plugin

[Section titled “Claude Code plugin”](#claude-code-plugin)

Add the marketplace and install the plugin:

```bash
claude plugin marketplace add thatguysam/skills
claude plugin install htma-measure@thatguysam-skills
```

Verify the installation:

```bash
claude plugin list --json
```

The marketplace uses a same-repository relative source. Claude clones the public marketplace over HTTPS and copies the plugin from that checkout, so installing it does not require a GitHub SSH key.

## Manual installation

[Section titled “Manual installation”](#manual-installation)

Clone the repository:

```bash
git clone https://github.com/ThatGuySam/skills.git
```

Copy the skill directory into the location your agent discovers:

```bash
mkdir -p .agents/skills
cp -R skills/skills/htma-measure .agents/skills/htma-measure
```

The first `skills` in that copy command is the cloned repository directory. If you already changed into the repository, use:

```bash
cp -R skills/htma-measure /path/to/project/.agents/skills/htma-measure
```

## Verify the files

[Section titled “Verify the files”](#verify-the-files)

A complete installation contains:

```text
htma-measure/
├── SKILL.md
├── agents/openai.yaml
├── assets/measurement-brief-template.md
└── references/
    ├── local-paid-quote-adjustment.md
    ├── method-map.md
    └── output-rubric.md
```

Next: [run your first measurement](/guides/first-measurement/).

# Prompt recipes

> Copyable prompts for cost, vendor quote, ROI, risk, market-size, and small-sample estimates.

Use these as starting points. Replace bracketed text with real context.

## Project budget

[Section titled “Project budget”](#project-budget)

```text
Use $htma-measure to estimate [project]’s total cost through [milestone].


Decision: [approve, reduce scope, or defer].
Unit: USD.
Time horizon: [dates].
Decision threshold: [amount or range that changes the action].
Available evidence: [scope, rates, prior actuals, quotes, constraints].
Separate confirmed facts, assumptions, and inference.
```

## Likely vendor quote

[Section titled “Likely vendor quote”](#likely-vendor-quote)

```text
Use $htma-measure to estimate the likely paid quote for [deliverable].


Estimate mode: amount likely paid, not abstract national list price.
Context: [local vendor, nonprofit/community relationship, pickup, bundled scope, or discounts].
Decision threshold: [maximum acceptable quote].
Show both full-market and plausible paid-quote scenarios.
```

## ROI

[Section titled “ROI”](#roi)

```text
Use $htma-measure to estimate the 12-month ROI of [initiative].


Decision: proceed only if the 90% interval is mostly above [required return].
Decompose implementation cost, operating cost, adoption, benefit per user, and timing.
Name the assumption with the highest value of information.
```

## Operational risk

[Section titled “Operational risk”](#operational-risk)

```text
Use $htma-measure to estimate the annual probability and expected impact of [risk].


Decision: choose between [mitigation A], [mitigation B], or accepting the risk.
Threshold: mitigate if expected annual loss exceeds [amount].
Use direct incident evidence and an explicit reference class.
Do not infer confidential facts that are not supplied.
```

## Market size

[Section titled “Market size”](#market-size)

```text
Use $htma-measure to estimate the serviceable market for [product] in [geography] over [period].


Decision: enter the market only if the 90% low bound exceeds [threshold].
Decompose eligible customers, reachability, conversion, price, and retention.
Use current direct sources and show where inference begins.
```

## Small sample

[Section titled “Small sample”](#small-sample)

```text
Use $htma-measure to update this estimate from the attached [N] observations.


State the prior, explain what the sample changes, and keep the interval calibrated for the sample size.
Tell me whether collecting [next N] observations could change the decision.
```

## Blocked lookup

[Section titled “Blocked lookup”](#blocked-lookup)

```text
Use $htma-measure for this question, but do not guess if an identifier, jurisdiction, effective period, current lookup, or private fact is missing.
Return a nonnumeric HTMA_RESULT status and the exact next input needed.
```

# Troubleshooting

> Fix discovery, installation, invocation, missing-input, and source-quality problems.

## “npx skill” does not work

[Section titled ““npx skill” does not work”](#npx-skill-does-not-work)

The package and executable are plural:

```bash
npx skills add thatguysam/skills --skill htma-measure
```

## The Skills CLI finds no skill

[Section titled “The Skills CLI finds no skill”](#the-skills-cli-finds-no-skill)

Confirm discovery first:

```bash
npx skills add thatguysam/skills --list
```

It should report exactly:

```text
htma-measure
```

The canonical file path is `skills/htma-measure/SKILL.md`.

## Codex knows the marketplace but not the plugin

[Section titled “Codex knows the marketplace but not the plugin”](#codex-knows-the-marketplace-but-not-the-plugin)

Adding a marketplace does not install its plugins. Run both commands:

```bash
codex plugin marketplace add thatguysam/skills
codex plugin add htma-measure@thatguysam-skills
```

Then check:

```bash
codex plugin list --json
```

## Claude attempts a GitHub SSH clone

[Section titled “Claude attempts a GitHub SSH clone”](#claude-attempts-a-github-ssh-clone)

Release `0.1.1` changed the Claude marketplace entry to a same-repository relative source, so the plugin no longer needs a second SSH clone.

Refresh and update:

```bash
claude plugin marketplace update thatguysam-skills
claude plugin update htma-measure@thatguysam-skills
```

If a stale cache persists, remove and reinstall the plugin.

## The skill asks for clarification instead of estimating

[Section titled “The skill asks for clarification instead of estimating”](#the-skill-asks-for-clarification-instead-of-estimating)

That is expected when the decision, quantity, unit, time horizon, threshold, identifier, jurisdiction, effective period, or necessary private fact is missing.

Supply the missing input named in `blocking_missing_inputs`. Do not ask the agent to fill a private or current fact with a guess.

## The range is wide

[Section titled “The range is wide”](#the-range-is-wide)

A wide interval is information. Ask for value-of-information ranking:

```text
Which remaining unknown could most change the decision?
What is the cheapest credible way to measure it?
When does further measurement stop mattering?
```

## The result cites stale or indirect evidence

[Section titled “The result cites stale or indirect evidence”](#the-result-cites-stale-or-indirect-evidence)

Ask the agent to rank each source against the exact estimate target for:

* directness;
* authority;
* freshness;
* geographic or market fit; and
* whether it supports a fact or only an inference.

For official fees, statutory rates, and current public benchmarks, require a current direct source and do not apply a local paid-quote discount.

## The JSON disagrees with the prose

[Section titled “The JSON disagrees with the prose”](#the-json-disagrees-with-the-prose)

Treat the memo as incomplete. The verification gate requires `low_90`, `central`, `high_90`, confidence, threshold implication, and status fields to match the written estimate.

# How it works

> The end-to-end HTMA Measure workflow from decision threshold to the next useful measurement.

HTMA Measure follows a decision-first sequence.

## 1. Make the question precise

[Section titled “1. Make the question precise”](#1-make-the-question-precise)

The agent identifies:

* the decision;
* the quantity of interest;
* the unit;
* the time horizon;
* the decision threshold; and
* the cost of being wrong.

If a required identifier, period, jurisdiction, or private fact is missing, the workflow stops and names the blocker.

## 2. Choose the estimate mode

[Section titled “2. Choose the estimate mode”](#2-choose-the-estimate-mode)

The same noun can refer to different quantities. “Cost” might mean:

* a vendor’s public market price;
* a budget allowance;
* the amount likely paid;
* an official fee;
* a statutory rate; or
* an ambiguous target that needs clarification.

The mode determines which evidence and adjustments are legitimate.

## 3. Build and rank evidence

[Section titled “3. Build and rank evidence”](#3-build-and-rank-evidence)

The agent starts with available local context, then uses direct sources, reference classes, and comparable cases. Each source is judged against the target for quality and freshness.

Confirmed facts stay separate from assumptions and inference.

## 4. Decompose and calibrate

[Section titled “4. Decompose and calibrate”](#4-decompose-and-calibrate)

The quantity is broken into smaller components with low, central, and high values. Weak bounds are widened rather than hidden behind precision.

Monte Carlo simulation is optional and only follows credible, calibrated inputs.

## 5. Connect the range to the decision

[Section titled “5. Connect the range to the decision”](#5-connect-the-range-to-the-decision)

The final interval is compared with the decision threshold. The memo explains whether the range sits above, below, or across that threshold and what action follows.

## 6. Measure only what matters next

[Section titled “6. Measure only what matters next”](#6-measure-only-what-matters-next)

The value-of-information section ranks remaining uncertainties by their ability to change the decision. It names the next useful measurement and the point at which further research stops mattering.

## 7. Return prose and structured data

[Section titled “7. Return prose and structured data”](#7-return-prose-and-structured-data)

The result is a readable memo plus an `HTMA_RESULT` JSON appendix for scoring, automation, or later calibration review.

# Introduction

> What HTMA Measure does, why calibrated ranges matter, and what the skill produces.

HTMA Measure is a portable agent skill for estimating uncertain quantities when a decision depends on the answer. It works for project costs, budgets, vendor quotes, rates, risks, ROI, market size, revenue, and similar questions where a precise-looking guess would be misleading.

The skill converts a vague question into a measurement memo with:

* a precise decision and threshold;
* an explicit quantity, unit, and time horizon;
* confirmed facts separated from assumptions and inference;
* a low / central / high decomposition;
* a calibrated confidence interval;
* the uncertainty most worth reducing next;
* a recommendation tied to the decision; and
* a machine-readable `HTMA_RESULT` JSON appendix.

## The key difference

[Section titled “The key difference”](#the-key-difference)

HTMA Measure does not ask, “What number sounds plausible?” It asks, “What range is defensible, what decision changes across that range, and what evidence is worth buying next?”

That distinction prevents three common failures:

1. **False precision:** a single number disguises uncertainty.
2. **Research without a stopping rule:** the agent gathers easy facts that cannot change the decision.
3. **Simulation laundering:** Monte Carlo output makes weak assumptions look rigorous.

## What HTMA means here

[Section titled “What HTMA means here”](#what-htma-means-here)

The workflow draws on decision-focused measurement and calibrated estimation ideas popularized by Douglas W. Hubbard’s *How to Measure Anything*. This repository is an independent implementation and is not affiliated with or endorsed by the author or publisher.

## Start using it

[Section titled “Start using it”](#start-using-it)

* [Install the skill](/guides/installation/).
* [Run your first measurement](/guides/first-measurement/).
* [See prompt recipes](/guides/prompt-recipes/).
* [Inspect the complete output contract](/reference/output-contract/).

# Who it's for

> The teams and decisions that benefit from calibrated, source-backed estimation.

HTMA Measure is for people using AI agents to support decisions under uncertainty—not merely to generate plausible prose.

## Strong fits

[Section titled “Strong fits”](#strong-fits)

### Product and project leads

[Section titled “Product and project leads”](#product-and-project-leads)

Use it to estimate delivery cost, implementation effort, adoption, downside risk, or the likely value of a feature before committing resources.

### Consultants and operators

[Section titled “Consultants and operators”](#consultants-and-operators)

Use it to size budgets, compare vendor scenarios, estimate a likely paid quote, or show a client which unknown matters most.

### Founders and investors

[Section titled “Founders and investors”](#founders-and-investors)

Use it for market sizing, unit economics, revenue ranges, runway decisions, and calibrated downside cases.

### Community and nonprofit organizers

[Section titled “Community and nonprofit organizers”](#community-and-nonprofit-organizers)

Use the local paid-quote adjustment when public retail or corporate rates do not reflect relationship pricing, simplified scope, local pickup, sponsorship goodwill, or nonprofit discounts.

### Researchers and analysts

[Section titled “Researchers and analysts”](#researchers-and-analysts)

Use it when a small sample, reference class, or source-quality audit can narrow uncertainty without pretending the available evidence is stronger than it is.

## Weak fits

[Section titled “Weak fits”](#weak-fits)

Do not reach for this skill when:

* an exact current value is available from an authoritative lookup;
* the question has no decision attached to it;
* the answer depends on a private fact the user has not supplied;
* the identifier, jurisdiction, or effective date is missing; or
* the user needs bookkeeping or factual retrieval rather than estimation.

In those cases, the skill returns a blocked or lookup-required status instead of inventing a numeric interval.

# Changelog

> Public changes to the HTMA Measure skill, distribution metadata, and documentation.

## 2026-07-11

[Section titled “2026-07-11”](#2026-07-11)

### Documentation site

[Section titled “Documentation site”](#documentation-site)

* Added the public Starlight documentation application at `apps/docs`.
* Added installation, usage, prompt, command, troubleshooting, feature, architecture, and reference pages.
* Added public `llms.txt`, `llms-full.txt`, and `llms-small.txt` outputs.
* Deployed the site at `https://skills.samcarlton.com`.

### 0.1.1

[Section titled “0.1.1”](#011)

* Changed Claude’s plugin source to the same marketplace repository.
* Removed the second GitHub SSH clone requirement.
* Documented the complete two-command Codex installation.

### 0.1.0

[Section titled “0.1.0”](#010)

* Published the standalone `htma-measure` skill.
* Added Codex, Claude Code, and portable plugin manifests.
* Added the calibrated memo template, method map, output rubric, and local paid-quote adjustment.
* Sanitized personal and workspace-specific markers for public use.

# Open questions & decisions

> The genuine unknowns and dated decisions governing the public skill and documentation.

## Open questions

[Section titled “Open questions”](#open-questions)

No question blocks installation or use of the current `htma-measure` release.

Questions to revisit with evidence:

* Should the other HTMA companion skills become public packages, or remain optional internal accelerators?
* Which calibration-review metrics are useful enough to standardize across real measurement memos?
* Should the repository publish automated cross-client installation tests on every release?

## Decided

[Section titled “Decided”](#decided)

### 2026-07-11 — Publish one standalone skill first

[Section titled “2026-07-11 — Publish one standalone skill first”](#2026-07-11--publish-one-standalone-skill-first)

The public repository ships `htma-measure` without requiring the rest of the HTMA suite. This keeps installation portable and makes the core workflow independently useful.

### 2026-07-11 — Keep the local paid-quote method public

[Section titled “2026-07-11 — Keep the local paid-quote method public”](#2026-07-11--keep-the-local-paid-quote-method-public)

The local nonprofit/community adjustment remains part of the public skill because it corrects a repeatable reference-class error while clearly excluding official fees and statutory rates.

### 2026-07-11 — Use public identity and noreply commits

[Section titled “2026-07-11 — Use public identity and noreply commits”](#2026-07-11--use-public-identity-and-noreply-commits)

Repository metadata uses `ThatGuySam`; commits use the GitHub noreply address rather than exposing a configured personal email.

### 2026-07-11 — Use same-repository plugin sources

[Section titled “2026-07-11 — Use same-repository plugin sources”](#2026-07-11--use-same-repository-plugin-sources)

Claude installs the plugin from the already-cloned marketplace. This avoids requiring public users to configure GitHub SSH.

### 2026-07-11 — Make the entire documentation site public

[Section titled “2026-07-11 — Make the entire documentation site public”](#2026-07-11--make-the-entire-documentation-site-public)

The docs Worker serves static assets directly. There is no authentication Worker, private-route manifest, login secret, or gated `llms-full.txt`.

# Roadmap

> What is available now and the evidence required before expanding the public skill collection.

## Available now

[Section titled “Available now”](#available-now)

* Public `ThatGuySam/skills` repository.
* Standalone `htma-measure` skill.
* Open Skills CLI discovery and installation.
* Codex marketplace and plugin installation.
* Claude Code marketplace and plugin installation.
* Calibrated memo template and JSON output contract.
* Public documentation and machine-readable `llms*.txt` surfaces.

## Next

[Section titled “Next”](#next)

1. Collect real-world measurement memos and calibration outcomes.
2. Review whether repeated failure modes belong in the core skill or a reference.
3. Add installation smoke tests to continuous integration.
4. Publish versioned releases when the skill contract changes.
5. Consider publishing companion HTMA skills only when each works independently and has a clear public use case.

## Expansion gate

[Section titled “Expansion gate”](#expansion-gate)

A new public skill belongs in this repository only when it is:

* specific enough to trigger reliably;
* self-contained or honest about optional dependencies;
* verified on realistic tasks;
* free of private workspace context;
* documented with install and use examples; and
* licensed for public reuse.

# Compatibility

> Verified installation paths and the boundaries of current compatibility claims.

The repository uses the standard `skills/<name>/SKILL.md` layout and contains no runtime code or platform-specific dependency.

## Verified matrix

[Section titled “Verified matrix”](#verified-matrix)

Verified on **2026-07-11** against public commit `6989b11` or a later documentation-only commit:

| Surface                    | Result               | Evidence                                                                                                                |
| -------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Open Skills CLI `1.5.14`   | Passed               | Found exactly one skill, copied all six files, and produced a source/hash lock record.                                  |
| Codex plugin `0.1.1`       | Passed               | Marketplace add, plugin add, installed/enabled listing, and cached skill files all succeeded from a clean `CODEX_HOME`. |
| Claude Code plugin `0.1.1` | Passed               | Marketplace add and plugin install both succeeded from a clean `CLAUDE_CONFIG_DIR`.                                     |
| Manual copy                | Compatible by format | The skill is a self-contained directory with relative resource paths.                                                   |

The Open Skills CLI’s [documented discovery locations](https://github.com/vercel-labs/skills#skill-discovery) include the root `skills/` directory. Its [CLI reference](https://www.skills.sh/docs/cli) supports repository shorthand, `--list`, `--skill`, agent targeting, global installs, updates, and removal.

Claude’s [marketplace documentation](https://code.claude.com/docs/en/plugin-marketplaces) supports same-repository relative plugin sources. Version `0.1.1` uses that pattern to avoid a second GitHub SSH clone.

## Compatibility boundaries

[Section titled “Compatibility boundaries”](#compatibility-boundaries)

* The core skill works without the optional HTMA companion skills.
* Clients must support Agent Skills-style Markdown discovery or allow the instructions to be loaded manually.
* A successful install proves packaging and discovery, not the quality of every future estimate.
* Current-source research still requires network access and appropriate browsing tools.
* Private inputs remain the user’s responsibility; the skill does not fetch or infer inaccessible financial facts.

# Output contract

> The required memo sections, HTMA_RESULT fields, statuses, and verification rules.

Every complete response contains a written memo and an `HTMA_RESULT` JSON appendix.

## Memo sections

[Section titled “Memo sections”](#memo-sections)

1. Compact relevance summary
2. Date and scope
3. Question made precise
4. Short answer
5. Priors and sources
6. Decomposition
7. Calibrated range
8. Value of information
9. What would move the estimate
10. Recommendation
11. Sources
12. `HTMA_RESULT`

## JSON schema

[Section titled “JSON schema”](#json-schema)

```ts
type HTMAResult = {
  quantity: string
  unit: string
  low_90: number | null
  central: number | null
  high_90: number | null
  confidence: string
  decision_threshold: number | string | null
  threshold_implication: string
  top_uncertainty_driver: string
  estimate_status:
    | "estimated"
    | "needs_clarification"
    | "needs_identifier"
    | "needs_effective_period"
    | "lookup_required"
    | "not_estimable"
  blocking_missing_inputs: string[]
  assumed_target: string | null
  next_measurement_step: string
}
```

## Empty template

[Section titled “Empty template”](#empty-template)

This is a schema template, not a measured result:

```json
{
  "quantity": "[quantity of interest]",
  "unit": "[unit]",
  "low_90": null,
  "central": null,
  "high_90": null,
  "confidence": "90%",
  "decision_threshold": null,
  "threshold_implication": "[above, below, or overlaps threshold and action implication]",
  "top_uncertainty_driver": "[largest remaining uncertainty]",
  "estimate_status": "needs_clarification",
  "blocking_missing_inputs": ["[required missing input]"],
  "assumed_target": null,
  "next_measurement_step": "[specific input or source lookup]"
}
```

## Status semantics

[Section titled “Status semantics”](#status-semantics)

| Status                   | Meaning                                                            |
| ------------------------ | ------------------------------------------------------------------ |
| `estimated`              | A responsible numeric interval is available.                       |
| `needs_clarification`    | The decision or target quantity is ambiguous.                      |
| `needs_identifier`       | A required entity, product, case, or account identifier is absent. |
| `needs_effective_period` | The applicable date or time period is missing.                     |
| `lookup_required`        | A current direct source must be refreshed before estimating.       |
| `not_estimable`          | Available evidence cannot support a responsible interval.          |

When the status is not `estimated`, `low_90`, `central`, and `high_90` remain `null`.

## Verification

[Section titled “Verification”](#verification)

A valid result satisfies all of these:

* low ≤ central ≤ high when numeric;
* units are consistent across components and the final range;
* confidence matches the named interval;
* threshold implication matches the numeric range;
* top uncertainty driver appears in the value-of-information section;
* missing inputs are empty only for an estimated result;
* next measurement is specific enough to execute; and
* JSON parses and agrees with the prose.

# Repository layout

> The public skill package, plugin manifests, docs app, and progressive-disclosure boundaries.

The repository keeps one canonical skill directory and several distribution surfaces.

```text
skills/
├── .agents/plugins/marketplace.json
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .codex-plugin/plugin.json
├── apps/docs/
│   ├── src/content/docs/
│   ├── astro.config.mjs
│   └── wrangler.jsonc
├── skills/htma-measure/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── assets/measurement-brief-template.md
│   └── references/
│       ├── local-paid-quote-adjustment.md
│       ├── method-map.md
│       └── output-rubric.md
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── plugin.json
```

## Progressive disclosure

[Section titled “Progressive disclosure”](#progressive-disclosure)

### Level 1: discovery metadata

[Section titled “Level 1: discovery metadata”](#level-1-discovery-metadata)

Agents read the `name` and `description` in `SKILL.md` to decide whether the skill applies.

### Level 2: core workflow

[Section titled “Level 2: core workflow”](#level-2-core-workflow)

When activated, the agent reads `SKILL.md`. It contains the sequence, output contract, stop conditions, and verification gate.

### Level 3: conditional resources

[Section titled “Level 3: conditional resources”](#level-3-conditional-resources)

The agent reads only the resource needed for the current step:

* `method-map.md` selects the smallest useful measurement technique;
* `local-paid-quote-adjustment.md` handles local/community paid-price scenarios;
* `output-rubric.md` validates the final memo; and
* `measurement-brief-template.md` provides the durable output frame.

## Distribution manifests

[Section titled “Distribution manifests”](#distribution-manifests)

* `.agents/plugins/marketplace.json` exposes the repository to Codex’s plugin marketplace.
* `.codex-plugin/plugin.json` declares the Codex plugin and version.
* `.claude-plugin/marketplace.json` exposes the same repository as a Claude marketplace.
* `.claude-plugin/plugin.json` points Claude to the canonical `skills/` directory.
* `plugin.json` supplies portable root metadata.

No distribution surface duplicates the skill content.

# Research

> The public sources and verification evidence behind the skill’s packaging and documentation.

No dated research memo is bundled with the first public release.

The current documentation is grounded in:

* the canonical [HTMA Measure skill source](https://github.com/ThatGuySam/skills/tree/main/skills/htma-measure);
* the [Open Skills CLI repository and discovery format](https://github.com/vercel-labs/skills);
* the [Skills CLI reference](https://www.skills.sh/docs/cli);
* the [Claude Code plugin marketplace specification](https://code.claude.com/docs/en/plugin-marketplaces); and
* clean-room installation checks for the Open Skills CLI, Codex, and Claude Code completed on 2026-07-11.

Future source-backed measurement research can be published here as dated pages. Each memo becomes canonical at its deployed documentation path and appears as a separate Research sidebar entry.