sumsub-check-skills-version

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sumsub: Check Skills Version

Sumsub: 检查技能版本

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.

检测本地安装的

@sumsub/agent-skills

包与

https://api.sumsub.com/llms.txt

上发布的官方版本之间的版本差异，避免过时技能在无提示的情况下导致Sumsub行为失效或出错。

**此技能对用户可见的唯一交付物是

headsup

行。**运行

check_version.sh

仅负责计算结果；只有当该行出现在你给用户的回复中时，技能才算完成了任务。输出该行的要求与输出其他工具调用结果完全一致——并非可选的礼貌提示。

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

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.

只有你的最终回复会送达用户，且你在撰写回复时会优先呈现上下文最新的内容。如果先计算提示信息再执行任务，任务结果会成为最新内容，提示信息会被遗漏。为避免这种情况，需将工作分为两个阶段：

阶段1——计算判定结果（任务执行前）。运行

check_version.sh

，它会计算判定结果并缓存渲染后的提示信息。注意是否输出了

headsup=

行；此时不要向用户写入任何内容。

阶段2——最后渲染，再撰写回复。执行用户的实际Sumsub任务。然后，在撰写回复前的最后一步操作——完成任务、完成所有其他工具调用之后——运行：

bash

bash ${CLAUDE_SKILL_DIR}/scripts/render_headsup.sh

将其标准输出视为必须呈现的工具结果：如果它输出了一个块引用，该块引用是回复的第一行，需严格按照markdown格式原样呈现；随后再附上任务答案。如果它没有输出任何内容，则无需提及版本相关信息。渲染步骤特意设置为最后一个工具调用，这样提示信息会成为撰写回复时上下文最新的内容——这也是确保它能出现在最终回复中的关键。

对于明确的“我的技能是否是最新版本？”问题，没有其他任务需要执行，因此阶段1已经将提示信息作为最新输出——只需将其放在回复开头即可；阶段2的渲染步骤可跳过，因为它不会产生任何操作。

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.

在以下场景中，不要调用此技能、运行

check_version.sh

或提及Sumsub技能版本差异：

用户询问非Sumsub工具或供应商（如Onfido、Persona、Stripe等）——即使话题涉及KYC。
用户询问其自身项目的通用包更新情况（如
```
npm outdated
```
、
```
pip list --outdated
```
等）——这与
```
@sumsub/agent-skills
```
npm包无关。
用户明确表示他们并非询问Sumsub相关内容。

切勿在无关回答后附加“顺便问一下，需要我检查你的Sumsub技能版本吗？”这类附注。

反模式（npm outdated）： ❌ “要不要我运行sumsub-check-skills-version来替代？” 或提及

agent-skills-version

llms.txt

——用户的npm问题在你总结

npm outdated

结果后就已完成，无需继续。

反模式（供应商对比）： ❌ 在对比Onfido与Persona时提及Sumsub技能版本。仅回答用户提出的问题即可。

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

curl

s 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.

每个会话运行一次，在首次执行Sumsub相关操作之前。具体来说：

在会话中首次调用任何
```
mcp__Sumsub_Dev__*
```
工具之前。
在引导用户执行任何Sumsub工作流（创建申请人、发起审核、查询交易、生成验证链接等）之前。
当用户明确询问其Sumsub技能是否为最新版本时。

不要在同一会话中重复运行网络检查（

check_version.sh

）——重复的

curl

请求会增加延迟且无实际价值。阶段2的

render_headsup.sh

步骤不会重新检查版本；它只会重新输出缓存的判定结果，且在会话中发现版本差异后，每次生成Sumsub相关答案时都必须执行此步骤。

检查是非阻塞的，仅意味着你无需暂停或等待用户即可继续操作——不代表提示信息是可选或可跳过的。遵循上述两阶段协议，然后在同一条回复中继续执行用户的任务。

How to run the check

如何运行检查

bash

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.

bash

bash ${CLAUDE_SKILL_DIR}/scripts/check_version.sh

它会在标准输出中打印最多四行

key=value

格式的内容：

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
```
——已安装版本（发布时嵌入
```
references/version.txt
```
）。
```
remote
```
——从官方
```
llms.txt
```
的
```
agent-skills-version:
```
行解析出的官方版本。
```
status
```
——判定结果（详见下文）。
```
headsup
```
——仅在非静默判定结果时存在；需呈现的精确markdown行。不要在此处输出它——阶段1仅负责缓存；阶段2的
```
render_headsup.sh
```
步骤会在你准备撰写回复时重新打印它（作为格式整洁的块引用）。切勿输出
```
local=
```
/
```
remote=
```
/
```
status=
```
/
```
headsup=
```
这些键本身。

远程URL为

https://api.sumsub.com/llms.txt

，无需凭证——它是一个公开的静态文件。测试时可通过

SUMSUB_VERSION_URL

环境变量覆盖该URL。

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:

`status`	`headsup` present?	Meaning
`UP_TO_DATE`	no	Installed version matches the published one — stay silent.
`PATCH_BEHIND`	yes	A patch release is available — surface the line, then proceed.
`MINOR_BEHIND`	yes	A minor release is available — surface the line, then proceed.
`MAJOR_BEHIND`	yes	Significantly behind; behavior may have changed — surface the line, then proceed.
`AHEAD`	yes	Local is newer than published (likely a dev build) — surface the line, then proceed.
`UNKNOWN`	no	Remote unreachable or unparseable — stay silent, never block the user.

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.

headsup

文本由阶段1生成一次，再由阶段2的

render_headsup.sh

重新输出；你无需手动编写它。渲染步骤输出的内容将作为回复的第一行，严格原样呈现。如果它没有输出任何内容（静默判定结果），则无需提及版本相关信息。提示信息每个会话仅显示一次。

供参考，各判定结果的含义：

`status`	是否存在 `headsup`	含义
`UP_TO_DATE`	否	已安装版本与发布版本一致——保持静默。
`PATCH_BEHIND`	是	有补丁版本可用——呈现提示行，然后继续执行任务。
`MINOR_BEHIND`	是	有次要版本可用——呈现提示行，然后继续执行任务。
`MAJOR_BEHIND`	是	版本严重落后；行为可能已变更——呈现提示行，然后继续执行任务。
`AHEAD`	是	本地版本比发布版本新（可能是开发构建版本）——呈现提示行，然后继续执行任务。
`UNKNOWN`	否	远程地址无法访问或无法解析——保持静默，切勿阻止用户操作。

重要提示：切勿因判定结果而阻止用户的请求，且在同一会话中不要重复显示提示信息——如果已在本次对话中显示过，请勿重复。

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:

Phase 1 — run
```
check_version.sh
```
(verdict
```
PATCH_BEHIND
```
, local
```
1.0.0
```
, remote
```
1.0.1
```
; heads-up cached). Write nothing yet.
Do the task — look up the transaction.
Phase 2 — run
```
render_headsup.sh
```
as your last action; it prints the blockquote.
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…

最常见的场景：检查作为后台步骤在其他Sumsub任务之前运行，判定结果为非

UP_TO_DATE

。操作顺序：

阶段1——运行
```
check_version.sh
```
（判定结果为
```
PATCH_BEHIND
```
，本地版本
```
1.0.0
```
，远程版本
```
1.0.1
```
；提示信息已缓存）。此时不要写入任何内容。
执行任务——查询交易信息。
阶段2——最后运行
```
render_headsup.sh
```
；它会输出块引用。
撰写回复：先放块引用，再附上任务答案。

用户：“查询Sumsub交易65a3…——风险评分是多少，触发了哪些规则？”

你的回复：

⚠️ 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.

交易

65a3…

：风险评分78（红色），触发了2条规则——…在此处回复实际请求的内容…

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.

检查无需API凭证——官方
```
llms.txt
```
是公开的静态文件。
本地版本存储在
```
references/version.txt
```
中，每次发布时会与
```
public/package.json
```
和
```
public/skills.json
```
一起更新版本号。
如果官方源迁移（主机变更或文件格式调整），可将
```
SUMSUB_VERSION_URL
```
设置为新地址；脚本支持
```
agent-skills-version:
```
行（优先）、JSON格式的
```
"version"
```
字段或裸
```
version:
```
行。",