audit-expo-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clerk Expo Skill Audit

Clerk Expo Skill 审核

Cross-check

skills/mobile/clerk-expo/

in this repository against the actual

@clerk/expo

SDK source and the clerk-docs content it cites. The SDK source is the source of truth for API shape; clerk-docs is the source of truth for recommended patterns; the skill must track both. When the two conflict on a factual claim (an API exists, a signature, a default, a version floor), SDK source wins — always. Docs win only on prescriptive questions source cannot answer (which flow to recommend, prop placement in examples, dashboard prerequisites).

The skill intentionally hardcodes verified code snippets (see its freshness gate). This audit is the maintenance half of that contract: it runs after SDK releases so the snippets stay verified rather than becoming folklore.

将本仓库中的

skills/mobile/clerk-expo/

与实际的

@clerk/expo

SDK源码及其引用的clerk-docs内容进行交叉校验。SDK源码是API形态的唯一权威依据；clerk-docs是推荐模式的唯一权威依据；Skill必须同时遵循两者。**当两者在事实性声明（如某API是否存在、签名、默认值、最低版本要求）上发生冲突时，始终以SDK源码为准。**只有在源码无法解答的规范性问题（如推荐使用哪种流程、示例中属性的放置位置、控制台前置条件）上，才以文档为准。

该Skill会有意硬编码经过验证的代码片段（详见其新鲜度校验机制）。本次审核是该约定的维护环节：在SDK发布后运行审核，确保代码片段始终保持验证状态，而非过时失效。

Inputs

输入项

SDK source of truth: a
```
clerk/javascript
```
checkout containing
```
packages/expo/
```
(and
```
packages/shared/src/types/
```
for the sign-in/sign-up resource types).

Docs source of truth: a

clerk/clerk-docs

checkout containing

docs/getting-started/quickstart.expo.mdx

docs/guides/development/custom-flows/authentication/*.mdx

, and

docs/reference/expo/**

Target skill:

skills/mobile/clerk-expo/SKILL.md

references/*.md

, and

evals/evals.json

Optional corroboration: a
```
clerk/clerk-expo-quickstart
```
checkout (three example apps exercising the current API).

SDK权威来源：包含
```
packages/expo/
```
（以及用于登录/注册资源类型的
```
packages/shared/src/types/
```
）的
```
clerk/javascript
```
代码仓库副本。

文档权威来源：包含

docs/getting-started/quickstart.expo.mdx

、

docs/guides/development/custom-flows/authentication/*.mdx

和

docs/reference/expo/**

的

clerk/clerk-docs

代码仓库副本。

目标Skill：

skills/mobile/clerk-expo/SKILL.md

、

references/*.md

和

evals/evals.json

。

可选佐证：包含三个使用当前API的示例应用的
```
clerk/clerk-expo-quickstart
```
代码仓库副本。

Source Checkout Resolution

源码仓库副本解析规则

Resolve each checkout in this order:

Use

--sdk <path>

--docs <path>

when supplied. The SDK path must contain

packages/expo/package.json

; the docs path must contain

docs/getting-started/quickstart.expo.mdx

Look for sibling checkouts of this repository:
```
../javascript
```
and
```
../clerk-docs
```
(the standard Clerk projects layout), and
```
../clerk-expo-quickstart
```
for corroboration.
If
```
CLERK_JAVASCRIPT_REPO
```
/
```
CLERK_DOCS_REPO
```
are set, use those paths.
If a checkout is missing and network access is acceptable, shallow-clone into
```
.context/
```
:

mkdir -p .context && cd .context
git clone --depth 1 https://github.com/clerk/javascript.git
git clone --depth 1 https://github.com/clerk/clerk-docs.git

If neither is available, stop and ask the user for paths. Do not audit from memory or from an installed

node_modules

copy alone; the audit exists precisely because memory drifts.

按以下顺序解析每个仓库副本：

若提供了
```
--sdk <路径>
```
/
```
--docs <路径>
```
参数，则使用指定路径。SDK路径必须包含
```
packages/expo/package.json
```
；文档路径必须包含
```
docs/getting-started/quickstart.expo.mdx
```
。
查找本仓库的同级仓库副本：
```
../javascript
```
和
```
../clerk-docs
```
（Clerk项目标准布局），以及用于佐证的
```
../clerk-expo-quickstart
```
。
若设置了
```
CLERK_JAVASCRIPT_REPO
```
/
```
CLERK_DOCS_REPO
```
环境变量，则使用这些路径。
若缺少仓库副本且允许网络访问，则浅克隆到
```
.context/
```
目录：

mkdir -p .context && cd .context
git clone --depth 1 https://github.com/clerk/javascript.git
git clone --depth 1 https://github.com/clerk/clerk-docs.git

若上述方式均无法获取仓库副本，请停止操作并向用户索要路径。请勿仅凭记忆或已安装的

node_modules

副本进行审核；审核的存在正是因为记忆会出现偏差。

Workflow

工作流程

1. Establish the version delta

1. 确定版本差异

Read the skill's stamped version from
```
SKILL.md
```
frontmatter (
```
compatibility:
```
) and its freshness-gate text.
Read the current version from
```
packages/expo/package.json
```
plus
```
peerDependencies
```
(Expo SDK range, React Native floor, React range) and bundled native SDK versions (
```
clerk-ios
```
,
```
clerk-android
```
in dependencies).
Read
```
packages/expo/CHANGELOG.md
```
entries between the stamped version and current. This is the primary work queue: every changelog entry either affects the skill or is explicitly irrelevant.

If the stamped version equals the current version and the changelog shows nothing new, report "no drift" and stop.

从
```
SKILL.md
```
的前置元数据（
```
compatibility:
```
）及其新鲜度校验文本中读取Skill的标记版本。
从
```
packages/expo/package.json
```
读取当前版本，包括
```
peerDependencies
```
（Expo SDK版本范围、React Native最低版本、React版本范围）以及捆绑的原生SDK版本（依赖项中的
```
clerk-ios
```
、
```
clerk-android
```
）。
读取
```
packages/expo/CHANGELOG.md
```
中标记版本与当前版本之间的条目。这是主要的工作队列：每个变更日志条目要么影响Skill，要么明确无关。

若标记版本与当前版本一致且变更日志无新内容，则报告“无偏差”并停止操作。

2. Inventory the SDK surface

2. 梳理SDK表面信息

Build a structured inventory from source (prefer

src/

over

dist/

Exports map:

packages/expo/package.json

exports

— every subpath (

/native

/web

/token-cache

/resource-cache

/secure-store

/local-credentials

/passkeys

/google

/apple

/legacy

/experimental

, …), noting additions and removals.

Hooks: everything re-exported from
```
src/hooks/index.ts
```
and the Expo-specific hooks (
```
useSSO
```
,
```
useAuth
```
extensions,
```
useSignInWithGoogle
```
,
```
useSignInWithApple
```
,
```
useLocalCredentials
```
). Capture signatures, return shapes, and
```
@deprecated
```
tags.
Custom-flow resources: the
```
SignInFutureResource
```
/
```
SignUpFutureResource
```
method surface in
```
packages/shared/src/types/signInFuture.ts
```
and
```
signUpFuture.ts
```
(method names, param shapes, status enums). The skill's custom-flows reference mirrors this surface.
Native components:
```
src/native/index.ts
```
exports and each component's props types (
```
AuthView.types.ts
```
,
```
UserProfileView
```
,
```
UserButton
```
). Flag any prop the skill names that no longer exists, and any new public prop.
Config plugin:
```
src/plugin/withClerkExpo.ts
```
— required env vars, theme option schema, platform side effects (deployment targets, URL schemes).

Provider:

src/provider/ClerkProvider.tsx

props, especially experimental ones (

__experimental_passkeys

__experimental_resourceCache

) and any newly stabilized names.

Dev warnings / migration signals: grep for
```
@deprecated
```
,
```
console.warn
```
, and package-migration notices (e.g. the
```
@clerk/expo-google-signin
```
split). These become "coming changes" notes in the skill.

从源码（优先使用

src/

而非

dist/

）构建结构化清单：

导出映射：

packages/expo/package.json

中的

exports

—— 所有子路径（

/native

、

/web

、

/token-cache

、

/resource-cache

、

/secure-store

、

/local-credentials

、

/passkeys

、

/google

、

/apple

、

/legacy

、

/experimental

等），记录新增和移除的内容。

Hooks：从
```
src/hooks/index.ts
```
重新导出的所有内容，以及Expo专属Hooks（
```
useSSO
```
、
```
useAuth
```
扩展、
```
useSignInWithGoogle
```
、
```
useSignInWithApple
```
、
```
useLocalCredentials
```
）。捕获签名、返回形态和
```
@deprecated
```
标签。
自定义流程资源：
```
packages/shared/src/types/signInFuture.ts
```
和
```
signUpFuture.ts
```
中的
```
SignInFutureResource
```
/
```
SignUpFutureResource
```
方法表面信息（方法名称、参数形态、状态枚举）。Skill的自定义流程参考需与此保持一致。
原生组件：
```
src/native/index.ts
```
的导出内容以及每个组件的属性类型（
```
AuthView.types.ts
```
、
```
UserProfileView
```
、
```
UserButton
```
）。标记Skill中提及但已不存在的属性，以及新增的公共属性。
配置插件：
```
src/plugin/withClerkExpo.ts
```
—— 必填环境变量、主题选项 schema、平台副作用（部署目标、URL scheme）。
Provider：
```
src/provider/ClerkProvider.tsx
```
的属性，尤其是实验性属性（
```
__experimental_passkeys
```
、
```
__experimental_resourceCache
```
）以及任何新稳定的名称。
开发警告/迁移信号：搜索
```
@deprecated
```
、
```
console.warn
```
以及包迁移通知（如
```
@clerk/expo-google-signin
```
拆分）。这些将作为Skill中的“即将到来的变更”说明。

3. Inventory the docs claims

3. 梳理文档声明

For every canonical docs URL cited in the skill's references:

Confirm the corresponding
```
.mdx
```
file still exists in clerk-docs at that route (URL path →
```
docs/
```
path). Broken citations are
```
drift
```
.
Re-read the Expo tab/section of each cited custom-flow guide and the Expo quickstart. Where the docs' recommended pattern changed (new required step, changed prop placement, new dashboard prerequisite), the skill's matching snippet is
```
drift
```
even if it still compiles.

针对Skill引用的每个规范文档URL：

确认对应的
```
.mdx
```
文件仍存在于clerk-docs的对应路由中（URL路径 →
```
docs/
```
路径）。失效的引用属于“偏差”。
重新阅读每个引用的自定义流程指南的Expo标签/章节以及Expo快速入门文档。若文档推荐的模式发生变化（新增必填步骤、属性位置变更、新增控制台前置条件），即使Skill中的对应代码片段仍可编译，也属于“偏差”。

4. Extract the skill's claims

4. 提取Skill的声明

Read

SKILL.md

, every

references/*.md

, and

evals/evals.json

. Extract each concrete claim:

Version stamps and peer ranges.
Every code snippet (imports, method calls, props, env var names).
Every gate and pitfall that names an API (
```
useSSO
```
vs
```
useOAuth
```
,
```
resourceCache
```
vs
```
secureStore
```
, captcha mount point,
```
treatPendingAsSignedOut
```
placement).
The capability matrix (Expo Go / dev build / web).
Eval expectations that assert API strings.

读取

SKILL.md

、所有

references/*.md

和

evals/evals.json

。提取每个具体声明：

版本标记和依赖范围。
每个代码片段（导入语句、方法调用、属性、环境变量名称）。
每个提及API的校验机制和注意事项（如
```
useSSO
```
vs
```
useOAuth
```
、
```
resourceCache
```
vs
```
secureStore
```
、验证码挂载点、
```
treatPendingAsSignedOut
```
的放置位置）。
能力矩阵（Expo Go / 开发构建 / Web）。
断言API字符串的评估预期。

5. Diff and bucket

5. 差异对比与分类

Produce a structured diff with four buckets:

Missing from skill: new exports, hooks, props, flows, or prerequisites in SDK/docs that the skill should cover (or explicitly scope out).
Stale in skill: claims contradicted by source or docs — renamed/removed APIs, changed defaults, changed peer floors, moved props, dead docs URLs, evals asserting outdated strings.
Thin in skill: covered but under-specified relative to real footgun surface (e.g. a new error code developers will hit).
Over-specified: detail the docs or installed
```
.d.ts
```
cover better; propose shrinkage where it reduces drift risk.

Cite source file and line for every bucket-1/2/3 entry, plus the target skill location.

生成包含四个类别的结构化差异报告：

Skill缺失内容：SDK/文档中新增的导出项、Hooks、属性、流程或前置条件，Skill应覆盖（或明确排除）。
Skill内容过时：与源码或文档矛盾的声明 —— API重命名/移除、默认值变更、依赖最低版本变更、属性位置移动、文档URL失效、评估断言过时字符串。
Skill内容不足：已覆盖但相对于实际易踩坑场景说明不够充分（如开发者会遇到的新错误码）。
Skill内容过度指定：文档或已安装的
```
.d.ts
```
已更好覆盖的细节；建议精简以降低偏差风险。

为每个1/2/3类别的条目标注源码文件及行号，以及目标Skill的位置。

6. Propose edits

6. 提出编辑建议

Emit a review-ready proposal grouped by target file. For each change include severity (

drift

gap

, or

polish

), the source citation, the target location, and a unified diff or concise before/after. Always include, when any change is applied:

The
```
compatibility:
```
stamp and freshness-gate version in
```
SKILL.md
```
updated to the audited SDK version.
Eval updates when expectations reference changed APIs.

Do not rewrite accurate neighboring sections. Skill shrinkage is a valid proposal.

按目标文件分组生成可直接用于评审的建议。每个变更需包含严重程度（

drift

偏差、

gap

缺失、

polish

优化）、源码引用、目标位置，以及统一差异对比或简洁的前后对比。当应用任何变更时，始终包含：

更新
```
SKILL.md
```
中的
```
compatibility:
```
标记和新鲜度校验版本为审核后的SDK版本。
当评估预期引用已变更的API时，更新评估内容。

请勿重写准确的相邻章节。精简Skill内容是合理的建议方向。

7. Apply or hand back

7. 应用建议或返回评审

Default: present the proposal and stop for review.

With

--apply

: apply

drift

and

gap

edits, update the version stamps, list

polish

for review, then validate — JSON files parse, every relative reference path in

SKILL.md

resolves, and every canonical docs URL maps to an existing clerk-docs file.

默认行为：展示建议并停止操作等待评审。

若使用

--apply

参数：应用

drift

偏差和

gap

缺失类别的编辑，更新版本标记，列出

polish

优化类别的内容供评审，然后进行验证 —— JSON文件可解析、

SKILL.md

中的每个相对引用路径均有效、每个规范文档URL均映射到clerk-docs中存在的文件。

Guardrails

约束规则

Never invent API surface. On factual conflicts between docs and SDK source, side with source and write the skill accordingly; list the discrepancy under "Open questions" as a probable clerk-docs bug worth reporting upstream. Only genuinely prescriptive ambiguity (source supports both patterns, docs unclear on which to recommend) goes to human review.
Snippets must stay minimal (API shape and control flow, not styled screens) and keep their canonical docs URL citation.
Preserve the skill's execution-gate structure and voice; edits slot into existing sections.
The legacy-API prohibition (Gate: method-based flows, never
```
prepareFirstFactor
```
/
```
setActive
```
for new code) may only be relaxed if the SDK itself re-legitimizes the legacy surface — treat any such change as a major finding, not a routine edit.
Do not audit against an installed
```
node_modules
```
copy as authority; it reflects whatever the last install pulled, not the release being audited.
Do not commit; leave staging and committing to the maintainer unless explicitly asked.

切勿虚构API表面信息。当文档与SDK源码在事实性内容上冲突时，以SDK源码为准并据此编写Skill；将差异列为“待解决问题”，作为可能的clerk-docs bug上报给上游。只有真正的规范性歧义（源码支持两种模式、文档未明确推荐哪种）才需提交人工评审。
代码片段必须保持精简（仅包含API形态和控制流，不包含样式化界面），并保留规范文档URL引用。
保留Skill的执行校验结构和语气；编辑内容需融入现有章节。
遗留API禁用规则（校验机制：基于方法的流程，新代码禁止使用
```
prepareFirstFactor
```
/
```
setActive
```
）仅在SDK本身重新认可遗留表面信息时方可放宽 —— 此类变更需作为重大发现处理，而非常规编辑。
切勿以已安装的
```
node_modules
```
副本作为权威依据进行审核；它反映的是上次安装的内容，而非待审核的版本。
请勿提交代码；除非明确要求，否则将暂存和提交操作留给维护者。

Output Shape

输出格式

markdown

undefined

markdown

undefined

clerk-expo skill audit - <YYYY-MM-DD>

Summary

摘要

<标记版本 vs 当前版本、已评审的变更日志条目数量、各类别条目数量、最严重的偏差>

skills/mobile/clerk-expo/SKILL.md

<section>

<章节>

[drift|gap|polish] <one-line description>
- source: packages/expo/src/<...>:<line> (or docs/<...>.mdx:<line>)
- target: skills/mobile/clerk-expo/SKILL.md:<line>
- change: <diff or concise before/after>

[drift|gap|polish] <一行描述>
- source: packages/expo/src/<...>:<行号> (或 docs/<...>.mdx:<行号>)
- target: skills/mobile/clerk-expo/SKILL.md:<行号>
- change: <差异对比或简洁的前后对比>

skills/mobile/clerk-expo/references/<file>.md

skills/mobile/clerk-expo/references/<文件>.md

...

skills/mobile/clerk-expo/evals/evals.json

...

Open questions

待解决问题

...


Keep the result skimmable so a maintainer can approve, reject, or apply each entry independently.

...


确保结果易于浏览，以便维护者可独立批准、拒绝或应用每个条目。