Sumsub: Check Skills Version

Detects version drift between the locally installed @sumsub/agent-skills package and the canonical version published at https://api.sumsub.com/llms.txt, so that out-of-date skills don't silently produce stale or incorrect Sumsub behavior.

This skill's one user-visible deliverable is the `headsup` line. Running check_version.sh only computes it; the skill has not done its job until that line appears in your reply to the user. Treat emitting it exactly like emitting the result of any other tool call — not as an optional courtesy.

Two-phase protocol (this is how the heads-up actually lands)

Only your FINAL reply reaches the user, and you surface what is freshest in your context when you compose it. If you compute the heads-up first and then do a task, the task result becomes the freshest thing and the heads-up gets dropped. To prevent that, split the work into two phases:

Phase 1 — compute the verdict (before the task). Run check_version.sh. It computes the verdict and caches the rendered heads-up. Note whether a headsup= line was printed; do not write anything to the user yet.

Phase 2 — render LAST, then compose. Carry out the user's actual Sumsub task. Then, as your final action before writing the reply — after the task, after every other tool call — run:

bash ${CLAUDE_SKILL_DIR}/scripts/render_headsup.sh

Treat its stdout exactly like the result of any tool you must surface: if it prints a blockquote, that blockquote is the first line of your reply, verbatim, rendered as markdown; then the task answer follows. If it prints nothing, say nothing about the version. The render step is deliberately your last tool call so the heads-up is the freshest thing in context when you compose — that is what makes it survive into the final reply.

For an explicit "are my skills up to date?" question there is no other task, so Phase 1 already leaves the heads-up as the freshest output — just lead your reply with it; the Phase-2 render is a no-op you can skip.

When NOT to run the check

Do not invoke this skill, run check_version.sh, or mention Sumsub-skills version drift when:

• The user asks about non-Sumsub tools or vendors (Onfido, Persona, Stripe, etc.) — even if the topic is KYC.
• The user asks about generic package freshness (npm outdated, pip list --outdated, etc.) for their own project — that is unrelated to the @sumsub/agent-skills npm bundle.
• The user explicitly says they are not asking about Sumsub.

Never append a "by the way, want me to check your Sumsub skills?" sidenote on unrelated answers.

Anti-pattern (npm outdated): ❌ "Want me to run sumsub-check-skills-version instead?" or mentioning agent-skills-version / llms.txt — the user's npm question is complete once you've summarized npm outdated. Stop there.

Anti-pattern (vendor comparison): ❌ Mentioning Sumsub skills version while comparing Onfido vs Persona. Answer only what was asked.

When to run the check

Run it once per session, before the first Sumsub-related action. Concretely:

• Before calling any mcp__Sumsub_Dev__* tool for the first time in this session.
• Before walking the user through any Sumsub workflow (creating an applicant, requesting a check, reading a transaction, building a verification link, etc.).
• When the user explicitly asks whether their Sumsub skills are up to date.

Do not re-run the network check (check_version.sh) within the same session — repeated curls add latency without value. The Phase-2 render_headsup.sh step does not re-check; it only re-emits the cached verdict, and it is mandatory every time you produce a Sumsub answer in a session that found drift.

The check is non-blocking only in the sense that you do not pause or wait for the user before continuing — it does not mean the heads-up is optional or skippable. Follow the two-phase protocol above, then proceed with the user's task in the same reply.

How to run the check

bash ${CLAUDE_SKILL_DIR}/scripts/check_version.sh

It prints up to four key=value lines on stdout:

local=1.0.1
remote=1.0.2
status=PATCH_BEHIND
headsup=> ⚠️ **Sumsub skills update available** — you're on **1.0.1**, latest is **1.0.2** (patch). Run `npx skills add SumSubstance/agent-skills --all` to update.

• local — installed version (baked into references/version.txt at publish time).
• remote — canonical version parsed from the agent-skills-version: line of the canonical llms.txt.
• status — the verdict (see below).
• headsup — present only for non-silent verdicts; the exact markdown line to surface. Don't emit it from here — Phase 1 just caches it; the Phase-2 render_headsup.sh step re-prints it (as a clean blockquote) when you're ready to compose. Never echo the local=/remote=/status=/headsup= keys themselves.

The remote URL is https://api.sumsub.com/llms.txt. No credentials needed — it's a public static file. Override with the SUMSUB_VERSION_URL environment variable for testing.

How to handle each verdict

The headsup text is produced once, by Phase 1, and re-emitted by Phase 2's render_headsup.sh; you never hand-write it. Whatever the render step prints becomes the first line of your reply, verbatim. If it prints nothing (silent verdict), say nothing about the version. The heads-up is shown once per session.

For reference, what each verdict means:

Important: never block the user's request because of the verdict, and never show the heads-up more than once in the same session — if you've already shown it in this conversation, don't repeat it.

Worked example — implicit trigger

The most common case: the check runs as a background step before some other Sumsub task, verdict is non-UP_TO_DATE. Order of operations:

1. Phase 1 — run check_version.sh (verdict PATCH_BEHIND, local 1.0.0, remote 1.0.1; heads-up cached). Write nothing yet.
2. Do the task — look up the transaction.
3. Phase 2 — run render_headsup.sh as your last action; it prints the blockquote.
4. Compose the reply: blockquote first, task answer after.

User: "look up sumsub transaction 65a3… — what risk score and which rules fired?"

Your reply:

⚠️ Sumsub skills update available — you're on 1.0.0, latest is 1.0.1 (patch). Run npx skills add SumSubstance/agent-skills --all to update.

Transaction 65a3…: risk score 78 (RED), 2 rules fired — …answer the actual request here…

Notes

• The check needs no API credentials — the canonical llms.txt is a public static file.
• The local version lives in references/version.txt and is bumped together with public/package.json and public/skills.json on every release.
• If the canonical source moves (host change, or migration to a different file shape), set SUMSUB_VERSION_URL to the new location; the script accepts an agent-skills-version: line (preferred), a JSON "version" field, or a bare version: line.