Clerk Expo Skill Audit

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.

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

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.

Workflow

1. Establish the version delta

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.

2. Inventory the SDK surface

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.

3. Inventory the docs claims

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.

4. Extract the skill's claims

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.

5. Diff and bucket

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.

6. Propose edits

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.

7. Apply or hand back

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.

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.

Output Shape

markdown

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

## Summary
<stamped vs current version, changelog entries reviewed, counts per bucket, largest drift>

## 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>

## skills/mobile/clerk-expo/references/<file>.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.

audit-expo-skill

NPX Install

Tags

SKILL.md Content

Clerk Expo Skill Audit

Inputs

Source Checkout Resolution

Workflow

1. Establish the version delta

2. Inventory the SDK surface

3. Inventory the docs claims

4. Extract the skill's claims

5. Diff and bucket

6. Propose edits

7. Apply or hand back

Guardrails

Output Shape