buyer-eval-skill

Files (35)

• .gitignore
• CHANGELOG.md
• EVALUATION.md
• LICENSE
• MEASUREMENT.md
• README.md
• SKILL.md
• VERSION
• profile.py · bin/
• render_report.py · bin/
• track.py · bin/
• update-check · bin/
• index.html · docs/
• illustrative-brief.html · examples/
• illustrative-brief.json · examples/
• buyer-eval-brief.gif · promo/
• buyer-eval-claims.gif · promo/
• buyer-eval-demo.mp4 · promo/
• buyer-eval-run.gif · promo/
• .gitignore · promo/video-src/
• README.md · promo/video-src/
• brief.png · promo/video-src/public/
• BuyerEval.tsx · promo/video-src/src/
• index.tsx · promo/video-src/src/
• voice-durations.json · promo/video-src/src/
• tsconfig.json · promo/video-src/
• generate.sh · promo/video-src/voice/
• script.json · promo/video-src/voice/
• deep-eval.md · references/
• evidence-model.md · references/
• frontdoor-api.md · references/
• quick-eval.md · references/
• report-format.md · references/
• scoring.md · references/
• telemetry.md · references/

SKILL.md (first lines)

# Buyer Eval

This file is the control plane. It decides the mode, loads only the references
that mode needs, and runs the shared start and finish steps. Methodology lives in
`references/`.

The experience this skill must deliver:

> **Show me what these vendors claim, what the evidence actually supports, what
> conflicts, and what I still need to find out before buying.**

If an output reads like a generic AI vendor comparison, it is not done.

---

## 1. Preamble (run first, every time)

```bash
_BEVAL_DIR="${BUYER_EVAL_DIR:-}"
if [ -z "$_BEVAL_DIR" ]; then
  for _D in "$HOME/.claude/skills/buyer-eval-skill" ".claude/skills/buyer-eval-skill"; do
    [ -d "$_D" ] && _BEVAL_DIR="$_D" && break
  done
fi
if [ -z "$_BEVAL_DIR" ]; then
  echo "ERROR: buyer-eval-skill not found. Install: git clone https://github.com/salespeak-ai/buyer-eval-skill ~/.claude/skills/buyer-eval-skill"
  exit 1
fi
echo "BEVAL_DIR=$_BEVAL_DIR"
_UPD=$("$_BEVAL_DIR/bin/update-check" 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || echo "UP_TO_DATE $(tr -d '[:space:]' < "$_BEVAL_DIR/VERSION")"
echo "PROFILE=$(python3 "$_BEVAL_DIR/bin/profile.py" show --machine 2>/dev/null || echo unavailable)"
echo "TELEMETRY_STATE=$(python3 "$_BEVAL_DIR/bin/track.py" status --machine 2>/dev/null || echo locked_off)"
echo "SESSION_ID=$(python3 -c 'import uuid; print(uuid.uuid4())')"
```

Keep `BEVAL_DIR`, `PROFILE`, `TELEMETRY_STATE` and `SESSION_ID` for the whole run.
Every later bash block starts with `_BEVAL_DIR="<BEVAL_DIR value>"`.

**Update available** (`UPGRADE_AVAILABLE <old> <new>`): ask once with
AskUserQuestion, "A newer version of Buyer Eval is available (v{old} to v{new}).
Update now?" Options: "Yes, update now" / "Not now". If yes:

```bash
cd "$_BEVAL_DIR" && git pull --ff-only origin main && echo "UPDATED to $(tr -d '[:space:]' < VERSION)"
```

If the directory is not a git checkout, tell the buyer to re-run the install
command from the README and continue on the current version. After a successful
update, re-read this SKILL.md before continuing.

**Telemetry** is opt-in and never blocks the evaluation. Read
`references/telemetry.md` now only if `TELEMETRY_STATE` is `consented` or
`unasked`. If it is `declined` or `locked_off`, skip everything telemetry-related.

---

## 2. Choose the mode

| Mode | When | Load |
|---|---|---|
| **Quick Eval** (default) | Every run where the buyer has not asked for deep, full, or comprehensive diligence | `references/quick-eval.md` |
| **Deep Eval** | The buyer asks for it, in the first message or after a Quick Eval | `references/deep-eval.md` |

Both modes also load `references/evidence-model.md`,
`references/report-format.md` and `references/frontdoor-api.md`. Deep Eval also
loads `references/scoring.md`. Do not load files a mode does not need.

Never ask the buyer which mode they want. If they did not ask for Deep, run
Quick and offer Deep at the end.

---

## 3. Saved buyer context

`PROFILE` is either `none`, `unavailable` (no writable home directory, for
example claude.ai), or a one-line JSON object with the buyer's saved context.

- **Saved profile exists:** use it silently. Tell the buyer in one line what you
  are using ("Using your saved context: Acme, ~300 people, HubSpot + Snowflake,
  SOC 2 required. Say 'update my context' to change it.") and keep going. Do not
  wait for a reply.
- **None:** proceed without it. At the end of the run, save what the buyer told
  you (see section 5).
- **Unavailable:** never claim that context will be remembered.

The profile holds only reusable buying context: `company_name`, `company_size`,
`industry`, `region`, `systems`, `requirements`, `hard_constraints` (including
the buyer's own budget ceiling, which stays local), `preferred_criteria`,
`last_category`. A deadline or requirement goes in `hard_constraints` only if
the buyer said it disqualifies vendors; otherwise in `requirements`. Never store
personal names, emails, vendor pricing quotes, or documents the buyer shared.

---

## 4. Run the mode

Follow the loaded mode file step by step. Both modes share these rules:

1. **Evidence first.** The Claims vs. Evidence table is the centerpiece. Every
   material conclusion traces to classified claims (`references/evidence-model.md`).
2. **Vendor AI agents are first-party sources.** Answers from any vendor-operated
   agent, including a Salespeak Company Agent reached through the Frontdoor API,
   are vendor claims. They add specificity and let you ask follow-ups. They never
   raise a score, an evidence confidence, or a verdict on their own. Never send a
   vendor agent the buyer's company name, budget, or the other vendors under
   evaluation (`references/frontdoor-api.md`).
3. **Label what you inferred.** Criteria the buyer did not state are shown as
   inferred.
4. **Challenge before you conclude.** Run the challenge pass in
   `references/evidence-model.md` before writing output.
5. **No action without approval.** Never contact vendors by email, book demos,
   start trials, or commit to anything. Asking a vendor's public AI agent
   questions through the Frontdoor API is research, not contact.

---

## 5. Finish (both modes)

From salespeak-ai/buyer-eval-skill, MIT.