docs(skills): Google android-skills adoption PRD + precedence guard (#139)

[stozo04]

Description

Google ships 21 agent skills for Android (android/skills, Apache 2.0). This PR adopts them through the official Claude Code plugin — all 21, uncurated (owner decision; docs/PRD-android-skills.md records the decision, the triage of every skill, the play-policy-insights pilot verdict, and the future-feature mapping) — and adds a precedence guard to CLAUDE.md: where a skill conflicts with a documented repo decision, the repo wins. The known collisions are spelled out there (navigation-3 vs the Lesson-014 sealed OpenLoopNavHost, camerax's MlKitAnalyzer preference vs the deliberate manual FaceTracker analyzer, AGP ceiling = the installed Studio pairing).

The plugin is enabled at project scope via the checked-in .claude/settings.json (extraKnownMarketplaces source + enabledPlugins object map), never user scope: Claude Code injects every enabled skill's name + description into each turn (~2 k tokens for these 21), so user scope would tax every project on the machine while the guard — which lives in this repo's CLAUDE.md — protects none of them. docs/guides/android-skills.md (+ its row in docs/guides/README.md) is the how-to: forcing a skill (/android-skills:camerax), project-only scoping and the user→project migration, the r8-analyzer / play-policy-insights cadences, updates. .gitignore gains the two skill scratch dirs (.scratch/, tmp/); cspell.json gains 7 terms.

Related Issue

Closes #139

Work that outlives this PR is tracked elsewhere, so closing #139 is honest:

• Reconcile on-device privacy claim with Firebase telemetry (play-policy audit findings 1–3) #142 — play-policy-insights pilot findings 1–3 (Firebase Analytics/Crashlytics upload vs the onboarding "100% on your phone" claim; the Crashlytics source_label key can carry a user-picked file name)
• docs: post-android-skills hygiene — layering rule, stale facts, §5 CameraX collapse, e2e retention #143 — docs/ hygiene after the skills landed
• Play Console FGS declaration for mediaProcessing + dataSync (pilot finding 4) — manual owner action in Play Console, not a repo change

Type of Change

• ✨ Feature: A new feature (non-breaking change which adds functionality)
• 🐛 Bug Fix: A bug fix (non-breaking change which fixes an issue)
• 🎨 Design/Style: Visual changes, layouts, animations, or asset integrations
• ⚙️ Refactor: Code changes that neither fix a bug nor add a feature
• 📝 Documentation: PRD, guide + README row, CLAUDE.md precedence section
• 🔧 Chore: .claude/settings.json plugin enablement, .gitignore, cspell.json

How Has This Been Tested?

No app code changed (app/** untouched, 7 files: 5 Markdown + .claude/settings.json + .gitignore + cspell.json). The DEFINITION_OF_DONE.md build / unit + instrumented test / 16 KB zipalign / emulator-screenshot gates are therefore N/A and are stated as such rather than ticked.

• Project-scope install proven (PRD plan step 2 c/d), fresh session 2026-08-22:
  • The session's skill list contains exactly 21 android-skills:<name> entries (agp-9-upgrade … display-glasses-with-jetpack-compose-glimmer).
  • grep -n android-skills ~/.claude/settings.json → 39: "android-skills": { — that line is the extraKnownMarketplaces source; the user-level enabledPlugins map has no android-skills entry.
  • From a non-repo folder (%LOCALAPPDATA%\Temp\claude\…\scratchpad; git rev-parse --show-toplevel → "not a git repository"): claude -p "Reply with only the count of skills in your list whose name starts with android-skills:" → 0.
• Markdown gates, run locally on the final content — CI's "Tier 3 Markdown checks" job is soft (|| true), so its green check alone proves nothing. Files: docs/PRD-android-skills.md CLAUDE.md docs/guides/android-skills.md docs/guides/README.md
  • npx cspell --no-progress → CSpell: Files checked: 4, Issues found: 0 in 0 files.
  • npx markdownlint-cli2 → Summary: 0 issues in 0 files
  • npx markdown-link-check --config .markdown-link-check.json per file → 3 / 12 / 2 / 7 links checked, 0 dead, exit 0 each
• Android Lint (./gradlew :app:lintDebug) on 3768182, local: BUILD SUCCESSFUL, exit 0, and the XML report app/build/reports/lint-results-debug.xml is an empty <issues/> — HTML says No Issues Found (0 errors / 0 warnings; no baseline, abortOnError=false, so the build could not have masked findings). The pr-reviewer skill's report comment on this PR carries the formal gate.
• Not verified here, honestly: PRD plan step 6 — camerax auto-triggering on a real camera task — is left ☐ (no camera-domain work has happened since the install; no staged task to tick the box). The Play Console FGS declaration is the owner's manual action.

Checklist

• 🧪 My changes have been verified locally and work as expected. (project-scope evidence + gates above)
• 🔍 I have performed a self-review of my own code.
• ✍️ I have commented my code, particularly in hard-to-understand areas. — N/A, no code in this PR
• 📖 My changes generate no new compile warnings or errors. — no compiled source changed; Lint 0 errors / 0 warnings on 3768182 (above)
• 🧹 The git branch is clean and references to obsolete branches have been pruned.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UYnJd1K9tbrjaj8DZCStev

---

Note

Low Risk
Documentation and Claude Code plugin settings only; no application, auth, or data-handling code. The main operational risk is auto-triggering skills that conflict with architecture, which this PR mitigates with an explicit precedence guard.

Overview
Adopts Google's official android/skills plugin for this repo (all 21 skills, uncurated) and records how agents must treat them.

Checks in .claude/settings.json so the marketplace and plugin load at project scope only. CLAUDE.md now states that repo docs win over skill guidance, with explicit collisions: do not migrate to Navigation 3, keep the manual FaceTracker analyzer, and do not bump AGP past the installed Studio pairing.

Adds docs/PRD-android-skills.md (triage, pilot verdict for play-policy-insights, future-feature mapping) and docs/guides/android-skills.md (how to force a skill, r8-analyzer / Play-policy cadences, updates). Gitignores skill scratch output (.scratch/, tmp/).

^{Reviewed by Cursor Bugbot for commit 3768182. Bugbot is set up for automated code reviews on this repo. Configure here.}

[stozo04]

PR Review — Google Android Standards Compliance

Reviewer: Claude (Automated)
Date: 2026-08-22
PR: #141 — docs(skills): Google android-skills adoption PRD + precedence guard (#139) — head 3768182
Standards sourced from: App architecture · UI-layer state holders · Compose performance · Coroutines best practices · DataStore · CameraX image analysis · CameraX ML Kit Analyzer · Navigation 3 · About AGP (Studio↔AGP pairing) · Runtime permissions · Testing strategies · Accessibility principles · Play target API requirement · Android 16 behavior changes · Claude Code docs: settings precedence · plugins / marketplaces
Files reviewed: 7 (.claude/settings.json, .gitignore, CLAUDE.md, cspell.json, docs/PRD-android-skills.md, docs/guides/README.md, docs/guides/android-skills.md) — git diff --stat origin/main...HEAD -- app/ is empty; no Kotlin, manifest, resource, or Gradle change.

---

PASS

The PR is documentation + agent-harness config, so the review question is Lesson 007: do the docs and config agree with the code, with each other, and with the tools they describe? Every claim below was checked by command, not read.

• [Architecture] CLAUDE.md's new precedence section claims the sealed OpenLoopUiState + exhaustive OpenLoopNavHost when is deliberate (Lesson 014, Decision Log feat: implement onboarding splash carousel and brand icon #1/feat: Phase 2 Burst Capture integration, Custom Flip Icon & Test Suite #2). Verified: the when inside OpenLoopNavHost has no else (13 is OpenLoopUiState.* branches); the only else -> in MainActivity.kt is the permission-check when at MainActivity.kt:482, not the router. CameraScreen( appears once (MainActivity.kt:710) — Lesson 012 guard intact.
• [CameraX] The guard says camerax prefers MlKitAnalyzer and FaceTracker is a deliberate manual analyzer. Verified both halves: the skill body (camera/camerax/SKILL.md:97, upstream 6685cac2923e) literally says "Use MlKitAnalyzer instead of manual ImageAnalysis.Analyzer"; FaceTracker.kt:25 is class FaceTracker(...) : ImageAnalysis.Analyzer on the stable com.google.mlkit:face-detection:16.1.7 (libs.versions.toml:29,105, app/build.gradle.kts:278); MlKitAnalyzer appears nowhere in app/src. Google's own page frames MlKitAnalyzer as an ImageAnalysis.Analyzer implementation intended for CameraController; OpenLoop binds via ProcessCameraProvider + UseCaseGroup with the single CameraEffect (Lesson 031) and owns coordinate mapping (Lesson 032), so the manual analyzer is the coherent choice and the collision is real, not hypothetical.
• [Android Version] CLAUDE.md tech-stack table vs build files: Kotlin 2.4.10, Compose BOM 2026.08.00, CameraX 1.6.1, Media3 1.11.0, DataStore 1.2.1 (gradle/libs.versions.toml:2-13), Gradle 9.5.0 (gradle-wrapper.properties), AGP 9.3.1, compileSdk 37 / minSdk 26 / targetSdk 36 (app/build.gradle.kts:25,29,35) — zero drift. The "AGP ceiling = installed Studio pairing" line matches the About-AGP compatibility model (each Studio supports a bounded AGP range).
• [Play Store] targetSdk 36 already meets Play's 31 Aug 2026 floor (API 36 for new apps and updates). Nothing in this PR touches the manifest, permissions, or packaging; .claude/settings.json and .gitignore are not shipped in the APK.
• [DataStore] / [Permissions] / [Compose] / [Media & Audio] / [Coroutines] / [Accessibility] — no app/** file in the diff; each area is unchanged by construction. Checked only that the new docs make no claim about them that the code contradicts (they don't).
• [Testing] No test change is warranted: no production code changed. docs/TEST_COVERAGE.md untouched and still accurate.
• [Static Analysis — config correctness]
  • .claude/settings.json: valid JSON (node JSON.parse); enabledPlugins is an object map ({"android-skills@android-skills": true}), not an array; extraKnownMarketplaces.android-skills.source = {"source":"github","repo":"android/skills"} — matches the Claude Code plugin-settings schema and the PRD's Decision snippet. File sits in .claude/, which doc-layout.yml allows.
  • .gitignore: comments are on their own lines (a # is only a comment at column 0); git check-ignore -v matches .scratch/y (L72) and tmp/keepradius/x / tmp/r8analysis/z (L73); git ls-files -i -c --exclude-standard is empty, so no tracked file became ignored.
  • cspell.json: 148 words, 0 out of case-insensitive order, 0 duplicates; all 7 added words (appfunctions, frontmatter, keepradius, mlkit, PYTHONUTF, styleable, uncurated) are actually used in the changed docs.
  • Docs placement (docs/README.md): both new .md files are under docs/; CI "New .md file placement" — pass on 3768182.
  • Cross-doc consistency: CLAUDE.md (L40-42), the PRD (L67-69, L117, L119) and the guide (L10) name the same three collision points; the guide's 4-step user→project migration mirrors PRD plan step 2 (a)-(d); PRD step-2 evidence matches what this session measured — 21 android-skills:* skills listed, grep -n android-skills ~/.claude/settings.json → line 39 only (extraKnownMarketplaces), claude -p from a non-repo folder → 0; the plugin cache holds 21 SKILL.md at upstream 6685cac2923e, the commit the PRD header cites.
  • Claude Code harness claims in the guide — "managed → project-local → project → user" precedence, --scope project writes .claude/settings.json, third-party marketplaces don't auto-update, project extraKnownMarketplaces apply after folder trust — all match the current Claude Code docs.

FAIL

None.

WARNING

None.

RECOMMENDATIONS

• [Docs — Lesson 007 accuracy, fresh-clone behaviour] Current Claude Code docs (v2.1.195+) state: "A plugin that only the project's .claude/settings.json enables, and that comes from an external source such as a GitHub repository … doesn't load until the team member installs it. Until then, Claude Code reports the plugin as not installed and shows the claude plugin install command to run." The guide ("so the file resolves on a fresh clone") and the PRD ("self-contained on a fresh clone") are correct that the marketplace name resolves without a /plugin marketplace add, but a reader can infer the 21 skills load automatically on a fresh clone or new machine — they won't until claude plugin install android-skills@android-skills --scope project is run once. Add that one sentence (with the explicit --scope project, otherwise the install lands at user scope — the exact drift the PRD just migrated away from) to docs/guides/android-skills.md → "Scope: this project only" and, optionally, the PRD Decision note.
  • Why: prevents a silent user-scope relapse on the owner's next machine; cheap insurance for the PRD's "project only, never user" rule.
  • Effort: low (one sentence; can ride docs: post-android-skills hygiene — layering rule, stale facts, §5 CameraX collapse, e2e retention #143 or a follow-up — not a merge blocker).

---

Summary

Category	Pass	Fail	Warning	Rec
Architecture	1	0	0	1
DataStore	1	0	0	0
Permissions	1	0	0	0
Compose	1	0	0	0
CameraX	1	0	0	0
Media & Audio	1	0	0	0
Coroutines	1	0	0	0
Testing	1	0	0	0
Accessibility	1	0	0	0
Play Store	1	0	0	0
Android Version	1	0	0	0
Static Analysis (Lint + IDE Inspect)	1	0	0	0
Total	12	0	0	1

(The single REC is a documentation-accuracy item about the agent harness; it is counted on the Architecture row because CLAUDE.md/guide govern how agents treat the architecture decisions.)

Verdict

APPROVE

Docs + config only; no app code changed, so the build / unit / instrumented / emulator gates of DEFINITION_OF_DONE.md are N/A for this PR. Engine 1 — Android Lint ran on 3768182 (./gradlew :app:lintDebug → BUILD SUCCESSFUL, exit 0; app/build/reports/lint-results-debug.xml is an empty <issues format="6" by="lint 9.3.1"> — No Issues Found, 0 errors / 0 warnings, no baseline, abortOnError=false so nothing was masked) — clean pass. Engine 2 — IDE Inspect Code was NOT run (it does not run headlessly on this machine); per STATIC_ANALYSIS.md the owner runs it locally before merge — for a Markdown/JSON-only diff the Tier 3 tools below are the faithful subset. Tier 3 ran on the 4 changed Markdown files: cspell Files checked: 4, Issues found: 0; markdownlint-cli2 Summary: 0 issues in 0 files; markdown-link-check 3 / 12 / 2 / 7 links checked, 0 dead — clean. Every claim the new docs make about the code (router exhaustiveness, single camera call site, manual ML Kit analyzer, every version in the tech table) was verified against the source and holds. The one thing worth doing — not before merge — is the one-sentence fresh-clone install note above.