# Tool Shadow

> Design an explicit, uncertainty-aware approximation of an expensive or long-running tool so agents can explore and reason quickly without confusing prediction with verification.

- Skill: `closedloop-technologies/tool-shadow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add closedloop-technologies/tool-shadow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/closedloop-technologies/tool-shadow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: closedloop-technologies (https://skillmd.com/u/closedloop-technologies)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/closedloop-technologies/tool-shadow

---


# Tool Shadow

Use this skill when an agent needs repeated access to a property that is hidden
inside an expensive, slow, licensed, remote, or physical tool.

A **Tool Shadow** is a fast, explicitly lossy approximation of an authoritative
tool. It may use deterministic heuristics, a reduced solver, cached results, a
learned surrogate, or a combination of these. It exists to improve perception,
ranking, and design-space exploration. It does not inherit the authority of the
tool it approximates.

The governing rule is:

> Use the shadow to explore. Use the authoritative tool to verify.

## Required workflow

1. Name the hidden property the agent needs to perceive.
2. Identify the authoritative tool or physical procedure that establishes the
   best available answer.
3. Decide whether an exact cheap rule already solves the problem. Do not train a
   model where deterministic geometry, arithmetic, lookup tables, or caching are
   sufficient.
4. Define the Tool Shadow profile using
   `https://github.com/closedloop-technologies/climbhill/blob/main/resources/strategies/tool-shadows/CONTRACT.md`.
5. Declare the validity envelope, expected cost and latency, uncertainty method,
   known failure modes, and authority level.
6. Return a versioned Functional Observation Packet for every invocation.
7. Keep `predicted`, `verified`, and `observed` evidence separate.
8. Compose this skill with `progressive-fidelity-tool-routing` before an agent
   spends an expensive tool budget or acts on a shadow prediction.
9. Compose it with `tool-shadow-calibration` before promotion to wider use.

## ClimbHill mapping

Treat each candidate asset or action as an `Attempt`. Every shadow, reduced
solver, authoritative tool, or physical result is a distinct `Evaluation`.
A continuation analysis may recommend another candidate or a higher-fidelity
evaluation, but deterministic policy or a human authority decides whether the
tool may run or an attempt may be promoted.

Do not mutate an existing Evaluation when a better result arrives. Append the
new result, link it to the same candidate and conditions snapshot, and record
which prior evidence it supports, contradicts, or supersedes for the current
decision.

## Minimum outputs

- Tool Shadow profile
- immutable input and conditions hashes
- prediction and uncertainty
- validity-envelope result
- authority label
- escalation recommendation
- links to authoritative or physical evidence when available
- cost, latency, and cache metadata

## Never claim

- that a shadow prediction is certification
- that average model accuracy proves safety near a decision boundary
- that the shadow can authorize its own use or promotion
- that a stale prediction still applies after the asset, conditions, tool, or
  model version changes
- that a model is reliable outside its declared validity envelope

## Strategy resources

- [Tool Shadow overview](https://github.com/closedloop-technologies/climbhill/blob/main/resources/strategies/tool-shadows/README.md)
- [Contract and observation packet](https://github.com/closedloop-technologies/climbhill/blob/main/resources/strategies/tool-shadows/CONTRACT.md)
- [Progressive-fidelity routing](https://github.com/closedloop-technologies/climbhill/blob/main/resources/strategies/tool-shadows/ROUTING.md)
- [Calibration and active learning](https://github.com/closedloop-technologies/climbhill/blob/main/resources/strategies/tool-shadows/CALIBRATION.md)
- [GeoField bracket case study](https://github.com/closedloop-technologies/climbhill/blob/main/resources/case-studies/geofield-bracket-tool-shadow.md)