Clerk Android (Native)
This skill implements Clerk in native Android projects by following current clerk-android SDK and docs patterns.
Activation Rules
Activate this skill when either condition is true:
- The user explicitly asks for Android, Kotlin, Jetpack Compose, or native mobile Clerk implementation on Android.
- The project appears to be native Android (for example
build.gradle(.kts) with Android plugins, AndroidManifest.xml, app/src/main/java, Compose UI files).
Do not activate this skill when either condition is true:
- The project is Expo.
- The project is React Native.
If Expo/React Native signals are present, route to the general setup skill instead.
What Do You Need?
| Task |
Reference |
| Prebuilt AuthView / UserButton (fastest) |
references/prebuilt.md |
| Custom API-driven auth flows (full control) |
references/custom.md |
Quick Start
| Step |
Action |
| 1 |
Confirm project type is native Android and not Expo/React Native |
| 2 |
Determine flow type (prebuilt or custom) and load the matching reference file |
| 3 |
Ensure a real Clerk publishable key exists (or ask developer) |
| 4 |
Ensure correct Clerk artifacts are installed for the selected flow |
| 5 |
Read official Android quickstart and verify required setup (Native API, min SDK/Java, manifest, initialization) |
| 6 |
Inspect clerk-android source/sample patterns relevant to selected flow |
| 7 |
Implement flow by following only the selected reference checklist |
Decision Tree
User asks for Clerk in Android/Kotlin
|
+-- Expo/React Native project detected?
| |
| +-- YES -> Do not use this skill
| |
| +-- NO -> Continue
|
+-- Existing auth UI detected?
| |
| +-- Prebuilt views detected -> Load references/prebuilt.md
| |
| +-- Custom flow detected -> Load references/custom.md
| |
| +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
|
+-- Ensure publishable key and SDK initialization path
|
+-- Ensure correct Android artifacts are installed
|
+-- Verify quickstart prerequisites in project
|
+-- Implement using selected flow reference
Flow References
After flow type is known, load exactly one:
- Prebuilt flow: references/prebuilt.md
- Custom flow: references/custom.md
Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.
Interaction Contract
Before any implementation edits, the agent must have both:
- flow choice:
prebuilt or custom
- a real Clerk publishable key
If either value is missing from the user request/context:
- ask the user for the missing value(s)
- pause and wait for the answer
- do not edit files or install dependencies yet
Only skip asking when the user has already explicitly provided the value in this conversation.
Source-Driven Templates
Do not hardcode implementation examples in this skill. Inspect current clerk-android source/docs for the installed SDK version before implementing.
| Use Case |
Source of Truth |
SDK artifacts and dependency split (clerk-android-api vs clerk-android-ui) |
clerk-android README and Android install docs |
| SDK initialization and publishable key wiring |
Android quickstart and source/api/.../Clerk.kt |
| Prebuilt auth and profile behavior |
source/ui/.../AuthView.kt, source/ui/.../UserButton.kt, and prebuilt sample |
| Custom auth sequencing and factor handling |
source/ui/auth/*, source/api/auth/*, and custom-flows sample |
| Capability/feature gating from instance settings |
Clerk public fields (for example enabledFirstFactorAttributes, socialProviders, isGoogleOneTapEnabled, mfaIsEnabled) and environment model source |
| Required Android setup checklist |
Official Android quickstart (/docs/android/getting-started/quickstart) |
Execution Gates (Do Not Skip)
- No implementation edits before prerequisites
- Do not edit project files until flow type is confirmed and a valid publishable key is available.
- Missing flow or key must trigger a question
- If flow choice is missing, explicitly ask: prebuilt views or custom flow.
- If publishable key is missing/placeholder/invalid, explicitly ask for a real key.
- Do not continue until both answers are provided.
- Publishable key wiring mode is mandatory
- By default, wire the developer-provided key directly in
Clerk.initialize(...).
- Do not introduce secret-management indirection unless explicitly requested.
- Artifact install policy is mandatory
- Prebuilt flow: use
clerk-android-ui (includes API).
- Custom flow: use
clerk-android-api unless prebuilt components are explicitly requested.
- If Clerk artifacts are missing, add the latest stable release available.
- Android quickstart compliance is mandatory
- Verify Native API is enabled for the Clerk app.
- Verify Android requirements from quickstart are implemented in project (minimum SDK and Java target, manifest internet permission, app-level Clerk initialization).
- Verify app waits for SDK initialization (
Clerk.isInitialized) before assuming auth-ready state.
- Capability-driven behavior is mandatory
- Use Clerk runtime capability/settings state (for example enabled factors/social providers/MFA flags) to gate flow behavior.
- Do not hardcode factor assumptions that may conflict with dashboard configuration.
- Reference-file discipline is mandatory
- Once flow is selected, follow only that flow reference file for implementation and verification.
- Custom-flow structure parity is mandatory
- For
custom flow, preserve multi-step auth progression and factor-specific handling (no single all-fields form by default).
- Keep UI, state orchestration, and Clerk API integration in separate modules.
- Prebuilt preference is mandatory when selected
- For
prebuilt flow, do not rebuild auth forms with custom API calls unless explicitly requested.
- Use
AuthView/UserButton as default building blocks.
Workflow
- Detect native Android vs Expo/React Native.
- If flow type is not explicitly provided, ask user for
prebuilt or custom.
- If publishable key is not explicitly provided, ask user for it.
- Wait for both answers before changing files.
- Load matching flow reference file.
- Ensure
Clerk.initialize(...) path and publishable key wiring are valid.
- Ensure dependencies/artifacts match selected flow.
- Review Android quickstart requirements and apply missing setup in project.
- Implement using selected reference checklist.
- Verify using selected reference checklist plus shared gates.
Common Pitfalls
| Level |
Issue |
Prevention |
| CRITICAL |
Not asking for missing flow choice before implementation |
Ask for prebuilt vs custom and wait before edits |
| CRITICAL |
Not asking for missing publishable key before implementation |
Ask for key and wait before edits |
| CRITICAL |
Starting implementation before flow type is confirmed |
Confirm flow first and load matching reference |
| CRITICAL |
Skipping Android quickstart prerequisites |
Verify and apply required setup from official Android quickstart |
| CRITICAL |
Missing app-level Clerk.initialize(...) call |
Initialize Clerk from Application startup path |
| HIGH |
Wrong artifact for chosen flow |
Prebuilt: clerk-android-ui; custom: clerk-android-api |
| HIGH |
Rendering auth UI before SDK initialization completes |
Gate UI with Clerk.isInitialized state |
| HIGH |
Hardcoding auth factors/social providers |
Drive behavior from Clerk runtime capability fields |
| HIGH |
Using this skill for Expo/React Native |
Detect and route away before implementation |
See Also
../clerk/SKILL.md for top-level Clerk routing
../setup/SKILL.md for cross-framework quickstart setup
https://github.com/clerk/clerk-android
https://clerk.com/docs/android/getting-started/quickstart
1---2name: clerk-android3description: Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.4license: MIT5allowed-tools: WebFetch6inputs:7 - name: CLERK_PUBLISHABLE_KEY8 description: Clerk publishable key for Android app configuration9 required: true10references:11 - references/prebuilt.md12 - references/custom.md13metadata:14 source: https://skillmd.com/skills/delorenj/clerk-android15 author: clerk16 version: 1.1.017pipeline-status:18 - new19---2021# Clerk Android (Native)2223This skill implements Clerk in native Android projects by following current `clerk-android` SDK and docs patterns.2425## Activation Rules2627Activate this skill when either condition is true:28- The user explicitly asks for Android, Kotlin, Jetpack Compose, or native mobile Clerk implementation on Android.29- The project appears to be native Android (for example `build.gradle(.kts)` with Android plugins, `AndroidManifest.xml`, `app/src/main/java`, Compose UI files).3031Do not activate this skill when either condition is true:32- The project is Expo.33- The project is React Native.3435If Expo/React Native signals are present, route to the general setup skill instead.3637## What Do You Need?3839| Task | Reference |40|------|-----------|41| Prebuilt AuthView / UserButton (fastest) | references/prebuilt.md |42| Custom API-driven auth flows (full control) | references/custom.md |4344## Quick Start4546| Step | Action |47|------|--------|48| 1 | Confirm project type is native Android and not Expo/React Native |49| 2 | Determine flow type (`prebuilt` or `custom`) and load the matching reference file |50| 3 | Ensure a real Clerk publishable key exists (or ask developer) |51| 4 | Ensure correct Clerk artifacts are installed for the selected flow |52| 5 | Read official Android quickstart and verify required setup (Native API, min SDK/Java, manifest, initialization) |53| 6 | Inspect `clerk-android` source/sample patterns relevant to selected flow |54| 7 | Implement flow by following only the selected reference checklist |5556## Decision Tree5758```text59User asks for Clerk in Android/Kotlin60 |61 +-- Expo/React Native project detected?62 | |63 | +-- YES -> Do not use this skill64 | |65 | +-- NO -> Continue66 |67 +-- Existing auth UI detected?68 | |69 | +-- Prebuilt views detected -> Load references/prebuilt.md70 | |71 | +-- Custom flow detected -> Load references/custom.md72 | |73 | +-- New implementation -> Ask developer prebuilt/custom, then load matching reference74 |75 +-- Ensure publishable key and SDK initialization path76 |77 +-- Ensure correct Android artifacts are installed78 |79 +-- Verify quickstart prerequisites in project80 |81 +-- Implement using selected flow reference82```8384## Flow References8586After flow type is known, load exactly one:87- Prebuilt flow: [references/prebuilt.md](references/prebuilt.md)88- Custom flow: [references/custom.md](references/custom.md)8990Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.9192## Interaction Contract9394Before any implementation edits, the agent must have both:95- flow choice: `prebuilt` or `custom`96- a real Clerk publishable key9798If either value is missing from the user request/context:99- ask the user for the missing value(s)100- pause and wait for the answer101- do not edit files or install dependencies yet102103Only skip asking when the user has already explicitly provided the value in this conversation.104105## Source-Driven Templates106107Do not hardcode implementation examples in this skill. Inspect current `clerk-android` source/docs for the installed SDK version before implementing.108109| Use Case | Source of Truth |110|----------|-----------------|111| SDK artifacts and dependency split (`clerk-android-api` vs `clerk-android-ui`) | `clerk-android` README and Android install docs |112| SDK initialization and publishable key wiring | Android quickstart and `source/api/.../Clerk.kt` |113| Prebuilt auth and profile behavior | `source/ui/.../AuthView.kt`, `source/ui/.../UserButton.kt`, and prebuilt sample |114| Custom auth sequencing and factor handling | `source/ui/auth/*`, `source/api/auth/*`, and custom-flows sample |115| Capability/feature gating from instance settings | `Clerk` public fields (for example `enabledFirstFactorAttributes`, `socialProviders`, `isGoogleOneTapEnabled`, `mfaIsEnabled`) and environment model source |116| Required Android setup checklist | Official Android quickstart (`/docs/android/getting-started/quickstart`) |117118## Execution Gates (Do Not Skip)1191201. No implementation edits before prerequisites121- Do not edit project files until flow type is confirmed and a valid publishable key is available.1221232. Missing flow or key must trigger a question124- If flow choice is missing, explicitly ask: prebuilt views or custom flow.125- If publishable key is missing/placeholder/invalid, explicitly ask for a real key.126- Do not continue until both answers are provided.1271283. Publishable key wiring mode is mandatory129- By default, wire the developer-provided key directly in `Clerk.initialize(...)`.130- Do not introduce secret-management indirection unless explicitly requested.1311324. Artifact install policy is mandatory133- Prebuilt flow: use `clerk-android-ui` (includes API).134- Custom flow: use `clerk-android-api` unless prebuilt components are explicitly requested.135- If Clerk artifacts are missing, add the latest stable release available.1361375. Android quickstart compliance is mandatory138- Verify Native API is enabled for the Clerk app.139- Verify Android requirements from quickstart are implemented in project (minimum SDK and Java target, manifest internet permission, app-level Clerk initialization).140- Verify app waits for SDK initialization (`Clerk.isInitialized`) before assuming auth-ready state.1411426. Capability-driven behavior is mandatory143- Use Clerk runtime capability/settings state (for example enabled factors/social providers/MFA flags) to gate flow behavior.144- Do not hardcode factor assumptions that may conflict with dashboard configuration.1451467. Reference-file discipline is mandatory147- Once flow is selected, follow only that flow reference file for implementation and verification.1481498. Custom-flow structure parity is mandatory150- For `custom` flow, preserve multi-step auth progression and factor-specific handling (no single all-fields form by default).151- Keep UI, state orchestration, and Clerk API integration in separate modules.1521539. Prebuilt preference is mandatory when selected154- For `prebuilt` flow, do not rebuild auth forms with custom API calls unless explicitly requested.155- Use `AuthView`/`UserButton` as default building blocks.156157## Workflow1581591. Detect native Android vs Expo/React Native.1602. If flow type is not explicitly provided, ask user for `prebuilt` or `custom`.1613. If publishable key is not explicitly provided, ask user for it.1624. Wait for both answers before changing files.1635. Load matching flow reference file.1646. Ensure `Clerk.initialize(...)` path and publishable key wiring are valid.1657. Ensure dependencies/artifacts match selected flow.1668. Review Android quickstart requirements and apply missing setup in project.1679. Implement using selected reference checklist.16810. Verify using selected reference checklist plus shared gates.169170## Common Pitfalls171172| Level | Issue | Prevention |173|-------|-------|------------|174| CRITICAL | Not asking for missing flow choice before implementation | Ask for `prebuilt` vs `custom` and wait before edits |175| CRITICAL | Not asking for missing publishable key before implementation | Ask for key and wait before edits |176| CRITICAL | Starting implementation before flow type is confirmed | Confirm flow first and load matching reference |177| CRITICAL | Skipping Android quickstart prerequisites | Verify and apply required setup from official Android quickstart |178| CRITICAL | Missing app-level `Clerk.initialize(...)` call | Initialize Clerk from `Application` startup path |179| HIGH | Wrong artifact for chosen flow | Prebuilt: `clerk-android-ui`; custom: `clerk-android-api` |180| HIGH | Rendering auth UI before SDK initialization completes | Gate UI with `Clerk.isInitialized` state |181| HIGH | Hardcoding auth factors/social providers | Drive behavior from Clerk runtime capability fields |182| HIGH | Using this skill for Expo/React Native | Detect and route away before implementation |183184## See Also185186- `../clerk/SKILL.md` for top-level Clerk routing187- `../setup/SKILL.md` for cross-framework quickstart setup188- `https://github.com/clerk/clerk-android`189- `https://clerk.com/docs/android/getting-started/quickstart`