Guide · Agent skill
How to use the Build Evidence Map agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The build-evidence-map skill tells an agent to answer a contested question as a traceable map: one current verdict, the evidence for it, the evidence against it, the qualifications, and the facts still unknown. It is for engineers weighing a technical choice, researchers reconciling sources that partly disagree, and reviewers who need to see what is missing before approving a proposal. After this guide you will know what an agent skill is, how to install this one, how to ask for it in plain language, and what the bundled tools do and do not guarantee.
Build Evidence Mapgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download and unzip. Download the build-evidence-map ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Or upload in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 3Check prerequisites. Make sure Node.js 18 or newer is available for the validator. Install the optional doubt-ai package only if you want rendering or verification.
- 4Ask a decision question. Describe the contested choice, the sources to use and the fact that you want supporting, contradicting and missing evidence shown.
- 5Validate the map. Run the bundled validator on decision.doubt.json and accept the result only when it exits 0 and prints VALID with a receipt.
- 6Review the output. Read the position, counterevidence, unknowns and source excerpts, then decide whether the evidence supports the verdict.
What an agent skill is and what this one makes the agent do
An agent skill is a folder containing a SKILL.md instruction file plus any supporting references and scripts. When the skill matches what you ask for, the agent follows its instructions. This skill covers one job: building an auditable evidence map for a decision that is contested or consequential.
Instead of answering in prose, the agent records each piece of evidence against a specific source location with dates and a short excerpt. It stores the relationships as a structured JSON file, which a bundled validator can check. An optional HTML view can also be produced. The skill is explicit that this does not make the answer true; it makes the reasoning traceable and harder to hide disagreement in prose.
- Creates four node types: position (the current verdict), claim, evidence (one source region) and unknown (a missing fact that could change the verdict).
- Types every edge as supports, contradicts, qualifies or missing, with a plain-language note.
- Keeps contrary evidence instead of deleting it when the verdict survives.
- Writes a canonical .doubt.json file that you can edit.
How to install the Build Evidence Map skill
Download the ZIP for build-evidence-map from this page and unzip it. For a personal setup, place the resulting skill folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder instead.
If you use the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.
- Personal install: unzip into ~/.claude/skills/.
- Project install: unzip into the project's .claude/skills/ folder.
- Claude apps: upload under Settings → Capabilities → Skills.
What you need before running it
The bundled validator uses only Node.js built-in modules, so it needs Node.js 18 or newer and does not require npm or network access. The skill's source notes that the validator is the deterministic check you should run.
The optional doubt-ai package is only needed for rendering HTML and for source verification. Its exact pinned version is stated in SKILL.md, so install that version rather than the latest. Source verification requires network access for HTTP(S) sources.
- Required for validation: Node.js 18 or newer.
- Optional: doubt-ai, installed locally, for rendering and verification.
- Network: needed only for verifying HTTP(S) sources.
How to trigger the skill with a natural request
You do not need special syntax. Ask a real decision question and say that you want the evidence laid out, including what contradicts the answer and what is unknown. The skill's description targets requests where Copilot must keep supporting, contradicting, qualifying and missing evidence with exact source regions.
Give the agent the sources you want used, or let it collect them, but expect it to record URLs or absolute local paths, publisher, dates and locators for each one.
- Example: Compare these two database options for our billing service and show the evidence for and against each, with sources and unknowns.
- Example: Synthesize these four vendor reports, where they disagree, and produce a sourced evidence map.
- Example: Before we approve this proposal, map what evidence is missing and which facts would change the decision.
Run the validator on the map
After the agent writes decision.doubt.json, it should run the bundled validator. Replace the placeholder with the path to the skill folder. A map is only valid when the command exits 0 and prints VALID followed by a 64-character receipt. A file hash, node count, JSON parse or manual review does not count.
If the validator finds problems, the skill requires fixing every finding before reporting success. If deterministic validation cannot run, the agent should report that block rather than claim success.
- Exit code 0 and VALID with a 64-character receipt means the structure passed.
- Validation checks traceability and graph integrity only; it does not prove the claims are true.
node <skill-directory>/scripts/validate.mjs decision.doubt.jsonOptional steps: render HTML and verify sources
Rendering creates a shareable HTML view of the validated map. The skill says to render only when you have already installed doubt-ai, and never to install or run a remote package implicitly.
Verification retrieves each recorded HTTP(S) source and fails if an excerpt cannot be matched. The skill forbids running it without explicit network permission. Local file verification does not use the network. The agent must not write a verification object by hand or hide a mismatch.
- Render only after you have installed doubt-ai yourself and asked for an HTML view.
- Verify only with explicit permission, since HTTP(S) requests go to remote URLs.
- JSON remains the editable source of truth; HTML is a view.
doubt map decision.doubt.json --out decision.htmlWhat a finished result should contain
The agent should report the current position in one sentence, the strongest counterevidence or qualification, the most important unresolved unknown, paths to the JSON and any HTML, and whether validation and explicit source verification ran. The skill's quality gates include one position with incoming reasoning, no duplicate edges or cycles, every source with dates and a bounded locator, and a verdict no broader than the evidence.
Read the result for readability first. Check that the excerpts really say what the evidence nodes claim, because the validator cannot judge source quality or inference quality.
- Check that each excerpt is substantive and matches its claim.
- Check that the verdict is not broader than the evidence.
- Treat the map as an aid to human review, not a verdict.
What people use it for
- Choosing between two architectures where trade-offs and counterevidence must be written down before a team commits.
- Synthesizing several research or analyst sources that partly disagree and need an explicit record of where they conflict.
- Reviewing a proposal to see which supporting facts are missing before approving it.
- Keeping a dated, sourced record of why a consequential technical decision was made.
Frequently asked questions
Is the Build Evidence Map skill free and what is its licence?
The skill is listed under the MIT licence. The skill files themselves are the download from this page; the optional doubt-ai package is a separate install that you choose to add.
What do I need to run the build-evidence-map skill?
You need Node.js 18 or newer to run the bundled validator, which uses only built-in modules. Rendering HTML and source verification need the optional doubt-ai package, and verification needs network access for HTTP(S) sources.
Where do I install an agent skill like this one?
Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps you can upload it under Settings, then Capabilities, then Skills.
Does the skill need internet access?
Not for the validator or local file checks. Network access is only needed when you explicitly run source verification on HTTP(S) sources, and the skill says the agent must not run it without your permission.
Why does validation fail, and what should I do?
Validation fails when the map breaks a structural rule, such as an unused source, an edge without a note, a duplicate edge or a cycle. Fix every finding the validator reports and run it again until it exits 0 and prints VALID with a receipt.
How is this different from a simple fact-checking workflow?
For a single factual claim or general fact-checking, the skill says to use a verification workflow such as doublecheck instead. Build Evidence Map is for cases where relationships between evidence, trade-offs and missing facts matter.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill when a technical or business decision is contested and you need the reasoning, counterevidence and gaps written down with traceable sources. Pick a lighter verification workflow for simple fact checks, or skip it when you have no real sources, because the skill depends on actual excerpts and locators.
Download the skill