Agent Skills Best Practices
A condensed summary of the 25 most important best practices drawn from every page in this section.
//
Search across all documentation pages
A condensed summary of the 25 most important best practices drawn from every page in this section.
Skills are playbooks, not tutorials: SKILL.md files tell agents how to execute - Agent Skills Basics defines structure; EAS Build Basics teaches concepts.
Pin the stack in every skill: React 19.2.3, RN 0.86.0, Expo SDK 57 (expo ~57.0.4) - unpinned skills hallucinate deprecated APIs.
One skill per decision domain: Release, routing, native review, testing, upgrade, incident - never one mega-skill.
Declare inputs before acting: eas.json, app.config.ts, bundle IDs, runtimeVersion, last good updateId - agents guess without them.
Outputs must be verifiable: Commands and checklists, not prose summaries - reject skill runs that omit npx expo-doctor.
Guardrails are the highest-value section: OTA vs build boundaries, credential rules, rollout pause - see EAS Release Skill.
Invoke skills at decision points: First production release, SDK upgrade, crash storm - not for reading introductory docs.
Human docs remain source of truth: Skills link to Typed Routes, Maestro E2E, Config Plugins - don't duplicate.
Run npx expo-doctor after dependency changes: Mandatory gate in SDK Upgrade Skill and every native-touching skill output.
Use npx expo install in skills: Never hand-pin expo-* versions - SDK 57 alignment drifts otherwise.
Classify JS-only vs native-impacting before release: Native module, plugin, or permission → eas build - OTA alone is unsafe.
runtimeVersion in every OTA skill invocation: Mismatch needs store binary - Runtime Version Policy.
Expo Router skills enable typedRoutes: Regenerate with npx expo start; verify npx tsc --noEmit - Expo Router Skill.
Validate deep-link params at runtime: Zod at screen entry - generated Href types don't prove malicious input.
Native skills prefer config plugins: CNG prebuild --clean erases hand-edited ios/ - Native Module Skill.
Idempotent plugins only: Second prebuild --clean should produce empty git diff.
App bridges → Expo Modules; TurboModules for RN libraries: RN 0.86 New Architecture defaults - test on device.
Testing skills respect the pyramid: Many Jest, few Maestro - Mobile Testing Skill.
Maestro appId must match bundle ID: Display name mismatches cause silent flow failures.
E2E on EAS e2e-test builds: Expo Go is not production-shaped - pair with EAS Workflows type: maestro.
SDK upgrade skills use dedicated branches: prebuild --clean, doctor, preview eas build matrix before production.
Incident skills contain before diagnose: Pause phased/staged rollout; assign IC - Incident Triage Skill.
Tag crashes with buildNumber + updateId + route: Triage without repro - Observability Best Practices.
OTA rollback < 15 minutes when JS regression: Record known-good updateId in every release ticket - Rollback Runbook.
Refresh skills after postmortems: Every missed guardrail becomes a new bullet - version skills with semver in createRunOncePlugin spirit.
App repo .cursor/skills/ for project-specific eas.json conventions; org registry for shared incident and upgrade playbooks. Always pin SDK version.
Skill may draft diffs - human release captain approves before CI non-interactive runs. Guardrails block production track submit without explicit prompt.
SDK Upgrade Skill orchestrates the same gates for agents - official release notes stay authoritative for breaking changes.
No. Skills accelerate checklists; Store Incident Response and rollback runbooks own production authority.
After any SDK bump, runtimeVersion policy change, or postmortem action item. Run npx expo-doctor in the skill verification section on refresh.
Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (
expo~57.0.4).
Reviewed by Chris St. John·Last updated Jul 19, 2026