Shipyard

Adapt ALL SDK integration patterns to the detected platform:

• iOS: SPM packages in project.yml or Package.swift, Swift service classes, @MainActor patterns
• Android: Gradle dependencies, Kotlin service classes, Hilt DI
• Flutter: pubspec.yaml dependencies, Dart service classes, Provider/Riverpod
• React Native: package.json dependencies, TypeScript service modules, hooks

SDK Registry

Architecture Pattern

All SDK integrations MUST follow the AnalyticsRouter pattern — a single fan-out service that routes events to all providers. Never call SDKs directly from ViewModels or Views.

Views → ViewModels → AnalyticsRouter → [Firebase, PostHog, Meta, AppsFlyer]
                   → AdaptyService   → [Adapty SDK]

Key principles:

• SDK services are private — only the router touches them
• Revenue events use provider-specific conventions ($revenue for PostHog, AFEventParamRevenue for AppsFlyer)
• Feature flags from PostHog are exposed via the router
• Opt-out/opt-in (GDPR/ATT) flows through the router

Graceful fallbacks: When API keys are placeholders, SDKs auto-disable via guard checks in SDKKeys. No crashes, no error UI — just silent no-ops with DEBUG console warnings.

Browser Automation (Playwright)

When CLI/API doesn't cover a task (e.g., Adapty paywall visual builder), use Playwright MCP.

Always dispatch Playwright work as a subagent — never inline browser automation in the main context. Use the Agent tool with the appropriate model tier based on task complexity (see Model Selection below).

Model Selection for Playwright Subagents

Pick the model based on how much reasoning the browser task requires:

Default: Start with Haiku. If the task requires judgment calls (which template to pick, how to interpret UI), use Sonnet. Reserve Opus for flows that repeatedly fail or require deep reasoning about the UI state.

Dispatching Playwright Subagents

Use the Agent tool. Always include in the prompt:

1. Current browser state (URL, what's visible)
2. Exact steps to perform (the more specific, the better for Haiku)
3. What copy/values to enter
4. What to return (screenshots paths, what succeeded/failed)

Agent({
  description: "Fill Adapty paywall form fields",
  model: "haiku",          // or "sonnet" / "opus"
  prompt: "The browser is already at https://app.adapty.io/paywalls/123/edit.
           Click the headline field (ref: e42), clear it, type 'Touch Grass First'.
           Click Save. Take a screenshot. Return: success/failure + screenshot path."
})

Setup

Playwright MCP must be configured to use the user's existing Chrome profile:

{
  "playwright": {
    "command": "<path-to>/playwright-mcp",
    "args": ["--browser", "chrome", "--user-data-dir", "<user-home>/Library/Application Support/Google/Chrome"]
  }
}

Critical: The user must close Chrome before Playwright can use the profile. Always warn before launching.

Authentication Flow

1. Navigate to the target dashboard (e.g., https://app.adapty.io)
2. If redirected to login → click "Sign in with Google" → Chrome profile handles OAuth automatically
3. Wait for redirect back to dashboard
4. Proceed with automation

Dashboard Operations

Commands

/shipyard:init — Initialize SDK integrations

Interactive setup wizard for a new or existing mobile app.

Process:

1. Detect platform — scan project files to identify iOS/Android/Flutter/RN
2. Scan existing integrations — check for already-installed SDKs (grep imports, check dependency files)
3. Ask user — "Which SDKs do you need?" with defaults:
   • PostHog (analytics + session replay + feature flags)
   • Firebase (auth + crashlytics)
   • Adapty (paywalls + subscriptions)
   • Meta (attribution)
   • AppsFlyer (install attribution)
   • Superwall (optional — paywall experimentation)
4. For each selected SDK: a. Check if CLI is installed → install if missing b. Check if CLI is authenticated → authenticate if needed c. Check if API key exists → create app/project if needed, extract key d. Add SDK dependency to project (SPM/Gradle/pubspec/package.json) e. Create service class following the platform's patterns f. Wire into AnalyticsRouter (or create one if it doesn't exist) g. Add graceful fallback guards in SDKKeys
5. Create SDKKeys config — centralized key management with auto-derived enable flags
6. Configure ATT/GDPR — wire opt-in/opt-out through the router
7. Validate — build the project, check for errors

Output: Summary of what was set up, what keys are still placeholder, and next steps.

/shipyard:abilities — Show available tools and gaps

Audit the development environment for mobile app tooling.

Process:

1. Check installed CLIs:

   which adapty firebase posthog asc superwall 2>/dev/null
   adapty auth status 2>/dev/null
   firebase login:list 2>/dev/null
   asc auth status 2>/dev/null
   

2. Check MCP servers:
   • Playwright MCP → connected? Chrome profile configured?
   • PostHog MCP → connected? Authenticated?
   • Context7 MCP → available for docs?
3. Check installed skills:

   ls ~/.claude-shared/skills/ | grep -E "superwall|ios-marketing|posthog|firebase|adapty"
   

4. Report:

   READY:
   ✅ adapty CLI v0.1.5 — authenticated as semih
   ✅ asc CLI v1.2.1 — authenticated as Runlock
   ✅ Playwright MCP — Chrome profile configured
   
   MISSING:
   ❌ posthog CLI — install: npm i -g posthog-cli
   ❌ firebase CLI — install: npm i -g firebase-tools
   ⚠️ superwall CLI — optional, install: brew install superwall
   
   SKILLS TO ADD:
   📦 npx skills add ParthJadhav/ios-marketing-capture -g
   📦 npx skills add superwall-ios-quickstart -g
   

5. Auto-fix option: "Want me to install the missing tools now?"

/shipyard:setup <sdk> — Set up a specific SDK

Deep setup for one SDK. Available SDKs: posthog, adapty, firebase, meta, appsflyer, superwall.

Example: /shipyard:setup adapty

1. Check adapty CLI installed and authenticated
2. Check if app exists → adapty apps list → create if not
3. Extract SDK key → update SDKKeys.swift (or platform equivalent)
4. Create access level premium
5. Create products (weekly/monthly/annual) with platform product IDs
6. Create paywalls (onboarding + upgrade) with all products
7. Create placements matching code constants
8. Open Playwright → Adapty dashboard → pick paywall template → customize copy → publish
9. Set up App Store server notifications URL via asc app-setup
10. Validate: build project, check SDK initialization

/shipyard:connect <store> — Connect app stores

Set up app store integrations. Available: appstore, playstore.

Example: /shipyard:connect appstore

Reality check: the community asc CLI covers TestFlight and some subscription ops, but NOT full metadata or screenshot sync. For the "ship v1.0" workflow below, use the App Store Connect REST API via a Python client (see the App Store Connect REST API section later).

Full v1.0 release prep workflow:

1. Auth setup (one-time per project)

   • Create API key at https://appstoreconnect.apple.com/access/integrations/api with Admin or App Manager role
   • Download .p8 ONCE (Apple never shows it again)
   • Place at ~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8 (chmod 600)
   • Export in ~/.zshrc: APP_STORE_API_KEY, APP_STORE_API_ISSUER

2. Subscriptions (if monetized)

   • Create subscription group via asc CLI or Playwright
   • Create subscription products with localized pricing
   • Set App Store server notification URL (for Adapty/RevenueCat webhook)
   • Configure sandbox testers

3. Metadata sync (use /shipyard:asc-sync) — see next section. Covers:

   • App info: name, subtitle, privacy URL, primary category per locale
   • Version: description, keywords, promotional text, release notes, marketing URL, support URL per locale
   • Version-level: copyright, release type
   • Review contact + notes
   • Screenshots per locale per device class

4. Localization matrix

   • Default locale = primary (e.g., tr for a Turkish-first app)
   • Add secondary locales (en-US, ru, etc.) even if app UI is single-language — App Store listings can still be multi-locale
   • Turkish diacritics must be correct: Müslüman not Musluman, ÖZELLİKLER not OZELLIKLER

/shipyard:asc-sync — Push metadata + screenshots to App Store Connect

One-command sync for app listing: metadata for all locales + screenshots per locale + review info + category. Idempotent — safe to re-run.

Prereq structure in project:

marketing/
├── asc-metadata/
│   ├── shared.json                   # URLs, copyright, review contact, review notes, primary_category, release_type
│   ├── <locale>/
│   │   ├── name.txt                  # ≤30 chars (App Store limit)
│   │   ├── subtitle.txt              # ≤30 chars
│   │   ├── description.txt           # ≤4000 chars
│   │   ├── keywords.txt              # ≤100 chars, comma-separated, no spaces after commas
│   │   ├── promotional_text.txt      # ≤170 chars, editable anytime
│   │   └── release_notes.txt         # ≤4000 chars (ignored on first version)
└── asc-screenshots/
    └── <locale>/
        ├── iphone-6-9/*.png          # APP_IPHONE_67: 1290×2796 (or APP_IPHONE_69: 1320×2868)
        ├── iphone-6-5/*.png          # APP_IPHONE_65: 1242×2688
        └── ipad-12-9/*.png           # APP_IPAD_PRO_129: 2048×2732

Execution order (the sync script does this):

1. GET /apps?filter[bundleId]=<bundle> → resolve app_id
2. GET /apps/<app_id>/appStoreVersions?filter[appStoreState]=PREPARE_FOR_SUBMISSION,... → version_id
3. GET /apps/<app_id>/appInfos → pick editable → app_info_id
4. PATCH /appInfos/<app_info_id> — primaryCategory relationship (e.g., LIFESTYLE, HEALTH_AND_FITNESS)
5. PATCH /appStoreVersions/<version_id> — copyright, releaseType (MANUAL / AFTER_APPROVAL / SCHEDULED)
6. PATCH or POST /appStoreReviewDetails — contact name/phone/email + review notes
7. For each locale:
   • Upsert appInfoLocalization (name, subtitle, privacyPolicyUrl)
   • Upsert appStoreVersionLocalization (description, keywords, promotionalText, marketingUrl, supportUrl)
   • Try PATCH whatsNew separately — catch STATE_ERROR (first-version releases reject whatsNew)
   • Upsert appScreenshotSet per display type
   • Delete existing screenshots in set (clean slate per sync)
   • Upload new screenshots via 3-phase handshake (reservation → binary PUT → commit with MD5)

Idempotency patterns (must implement in the sync script):

• If POST returns 409 DUPLICATE: refetch and PATCH instead
• If PATCH of whatsNew returns 409 STATE_ERROR: skip silently on first-release versions
• If screenshot set doesn't exist: POST, otherwise reuse existing set ID
• Always wipe existing screenshots before upload to avoid stale mixed state

/shipyard:dashboard <service> — Open and configure a dashboard

Use Playwright to automate dashboard configuration.

Process:

1. Pre-flight: Check Playwright MCP is connected
2. Warn user: "I need to open Chrome with your profile. Please close Chrome if it's open."
3. Navigate to the dashboard (adapty/posthog/firebase/appstoreconnect)
4. Authenticate — use Google SSO via Chrome profile
5. Perform configuration — template selection, settings changes, etc.
6. Screenshot each step for verification
7. Report what was configured

/shipyard:status — Overall integration health check

Quick overview of all SDK integrations in the current project.

1. Read SDKKeys (or equivalent) — check which keys are real vs placeholder
2. Check each service file for proper guard patterns
3. Verify AnalyticsRouter wiring
4. Check dependency versions (outdated?)
5. Report:

   SDK Status:
   ✅ PostHog — key set, session replay enabled, ATT wired
   ✅ Adapty — key set, 2 paywalls, 3 products, webhook configured
   ⚠️ AppsFlyer — placeholder key, will silently disable
   ⚠️ Meta — no FACEBOOK_APP_ID in build settings
   ✅ Firebase — configured, anonymous auth active
   

/shipyard:prices <territory> — Set subscription pricing

Recommend and configure subscription prices for a specific market.

1. Research competitive pricing for the territory
2. Map to Apple/Google price tiers
3. Create/update subscriptions via asc CLI
4. Add localizations for the territory
5. Report pricing table with savings percentages

/shipyard:init-skills — Auto-install platform skills

Detects the project platform and installs all relevant Claude Code skills via git clone to ~/.claude-shared/skills/.

Process:

1. Detect platform — scan project files (see Platform Detection above)

2. Resolve skill directory — SKILLS_DIR="$HOME/.claude-shared/skills"

3. For each skill in the platform registry: a. Check if $SKILLS_DIR/<skill-name>/SKILL.md already exists → skip if present b. git clone <repo-url> $SKILLS_DIR/<skill-name> c. If SKILL.md is nested (e.g., <skill-name>/<nested-dir>/SKILL.md), flatten: cp -r <nested-dir>/* . d. Verify SKILL.md exists at root level

4. Update project CLAUDE.md — read the project's CLAUDE.md, find the platform rules section, and add Skill Reference lines for every installed skill that isn't already listed. Each line follows the format:

   - **Skill Reference**: Use `<skill-name>` skill for <purpose>
   

   Only add references for skills relevant to the detected platform. Do NOT duplicate references that already exist in the file.

5. Create ai-rules/ folder — if it doesn't exist, create ai-rules/ in the project root with domain-specific rule files tailored to the detected platform. This follows the Zabłocki progressive-disclosure pattern: a rule-loading.md index tells the LLM which rules to load on demand.

   For iOS projects, create these files:

   • ai-rules/rule-loading.md — index of all rule files with loading triggers and keywords (MUST list app-store.md with triggers: "submit", "release", "screenshot", "metadata", "ASC", "App Store Connect", "localization", "review notes")
   • ai-rules/general.md — core Swift engineering rules (always loaded): progressive architecture, error handling, dependency injection, localization, quality gates, anti-patterns
   • ai-rules/view.md — SwiftUI view rules: Liquid Glass API patterns, modifier order, design system tokens, animation patterns (staggered reveal, celebration, content transitions), reusable components list
   • ai-rules/view-model.md — ViewModel rules: @Observable pattern, computed derived state, async data loading, String(localized:), state ownership
   • ai-rules/services.md — services/SDK rules: AnalyticsRouter pattern, graceful SDK fallbacks, revenue event formatting, HealthKit/FamilyControls patterns
   • ai-rules/testing.md — testing rules: test behavior not implementation, mock dependency injection, focus areas, test structure
   • ai-rules/app-store.md — App Store Connect submission readiness: metadata file layout, locale matrix, character limits, Turkish/diacritic correctness, screenshot specs, review info, idempotent sync patterns (see template below)

   rule-loading.md trigger block for app-store.md (add to the trigger index):

   ### app-store.md - App Store Connect Submission Readiness
   **Load when:**
   - Preparing for App Store submission or TestFlight release
   - Running `/shipyard:asc-sync`
   - Editing files under `marketing/asc-metadata/` or `marketing/asc-screenshots/`
   - Adding a new locale to the App Store listing
   - Reviewing/fixing screenshot sizes, character limits, or review info
   - Debugging ASC API 401/409 errors
   
   **Keywords:** App Store, ASC, asc-sync, submission, metadata, screenshot, localization, keywords, description, review notes, TestFlight, promotional text, release notes, locale, Turkish diacritics
   

   Each rule file uses the <primary_directive>, <rule_N priority="...">, <pattern name="...">, <checklist>, and <avoid> XML-like tag structure for optimal LLM parsing.

   ai-rules/app-store.md template contents (copy into the file):

   <primary_directive>
   Before invoking `/shipyard:asc-sync` or submitting to App Store Connect, the project MUST have complete, validated metadata for every locale and screenshots at the correct display-type resolutions. Broken submissions are expensive: rejections delay releases by days.
   </primary_directive>
   
   <rule_1 priority="critical">
   **Metadata file layout is fixed.** The sync script expects exactly this structure. Do not invent new paths.
   
   

   marketing/ ├── asc-metadata/ │ ├── shared.json (urls, copyright, review_contact, review_notes, primary_category, release_type) │ └── <locale>/ (e.g. tr, en-US, ru, ar) │ ├── name.txt ≤30 chars │ ├── subtitle.txt ≤30 chars │ ├── description.txt ≤4000 chars │ ├── keywords.txt ≤100 chars, comma-separated, NO space after comma │ ├── promotional_text.txt ≤170 chars (editable post-release) │ └── release_notes.txt ≤4000 chars (ignored on v1.0) └── asc-screenshots/<locale>/<display-slug>/*.png

   </rule_1>
   
   <rule_2 priority="critical">
   **Character limits are enforced by Apple, not by the sync script.** The script just uploads — Apple rejects at submission time. Validate locally before running sync:
   - name ≤ 30, subtitle ≤ 30
   - keywords ≤ 100 total chars (including commas)
   - promotional_text ≤ 170
   - description ≤ 4000
   </rule_2>
   
   <rule_3 priority="critical">
   **Turkish and non-ASCII diacritics must be correct.** Common mojibake from copy-paste:
   - ✅ Müslüman, günlük, ÖZELLİKLER, İmsak, Öğle, Akşam
   - ❌ Musluman, gunluk, OZELLIKLER, Imsak, Ogle, Aksam
   
   Run a grep for ASCII-only variants of Turkish words before every sync. Same discipline for Arabic (`ar`), Russian (`ru`), German (`de`).
   </rule_3>
   
   <rule_4 priority="high">
   **Locales are independent of in-app language.** A Turkish-only app can (and should) have en-US and ru App Store listings. The listing text drives discovery; the app can be single-language.
   </rule_4>
   
   <rule_5 priority="high">
   **Screenshots must match display-type specs exactly.** Apple rejects with cryptic errors on off-by-one resolutions:
   
   | Slug | Resolution | Maps to |
   |---|---|---|
   | `iphone-6-9` | 1290×2796 | `APP_IPHONE_67` (covers 6.7"+6.9" in practice) |
   | `iphone-6-5` | 1242×2688 | `APP_IPHONE_65` |
   | `ipad-12-9` | 2048×2732 | `APP_IPAD_PRO_129` |
   
   If source captures are 1206×2622 (iPhone 17 Pro native), upscale to 1290×2796 with aspect-preserving black letterbox padding. Never stretch.
   
   3–10 screenshots per set. Same 10 images can be reused across locales when the UI is single-language.
   </rule_5>
   
   <rule_6 priority="high">
   **Review info is required before first submission.**
   - `shared.json.review_contact` — full name, phone with country code, email that Apple reviewers can actually reach
   - `shared.json.review_notes` — if the app needs a test account, include login credentials here. If it uses HealthKit/FamilyControls/special entitlements, document the permission flow
   - Missing review info = instant rejection with "Guideline 2.1"
   </rule_6>
   
   <rule_7 priority="medium">
   **Release notes (`whatsNew`) are NOT editable on v1.0.** Apple's logic: there's nothing "new" about a first release. The sync script catches `409 STATE_ERROR` and skips silently. For v1.0 builds, leave `release_notes.txt` empty or don't create it — avoid churn.
   </rule_7>
   
   <rule_8 priority="medium">
   **Primary category matters for discoverability.** Use the closest Apple category. Examples:
   - Prayer/religion apps → `LIFESTYLE`
   - Habit/health trackers → `HEALTH_AND_FITNESS`
   - Productivity/todo → `PRODUCTIVITY`
   
   Secondary category is set in ASC UI, not the sync script (REST limitation).
   </rule_8>
   
   <rule_9 priority="medium">
   **Release type decides when users get the update.**
   - `MANUAL` — release when I click the button (safest for risky changes)
   - `AFTER_APPROVAL` — release immediately after review passes
   - `SCHEDULED` — release at a specific date/time (requires `scheduledReleaseDate`)
   
   Set in `shared.json.release_type`.
   </rule_9>
   
   <pattern name="Pre-sync validation checklist">
   Run this BEFORE `/shipyard:asc-sync`:
   - [ ] All locale folders present with all 6 .txt files
   - [ ] Character counts under limits (`wc -m marketing/asc-metadata/*/*.txt`)
   - [ ] Turkish diacritics verified (grep for `Musluman`, `gunluk`, `OZELLIKLER` → should return nothing)
   - [ ] Keywords have no trailing spaces after commas (grep for `, ` in keywords.txt → should return nothing)
   - [ ] Screenshots resized to exact display-type resolution (imagemagick `identify` to verify)
   - [ ] `shared.json` has valid review_contact (reachable phone + email)
   - [ ] `APP_STORE_API_KEY` + `APP_STORE_API_ISSUER` env vars set
   - [ ] `.p8` file exists at `~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8`
   - [ ] Key role is **Admin** or **App Manager** (not Developer)
   </pattern>
   
   <pattern name="Idempotent re-runs">
   The sync is designed to be safe to re-run. Know what it does:
   - `POST` returns `409 DUPLICATE` → script falls back to GET + PATCH
   - `PATCH whatsNew` returns `409 STATE_ERROR` → script skips silently (v1.0)
   - Screenshot sets: existing set is reused, its contents are wiped and re-uploaded each run
   - Stale sets from old display types (e.g. leftover `APP_IPHONE_61`) must be cleaned manually — they cause "mixed sizes" warnings in ASC UI
   </pattern>
   
   <checklist>
   When adding a new locale:
   - [ ] Create `marketing/asc-metadata/<new-locale>/` with all 6 files
   - [ ] Create `marketing/asc-screenshots/<new-locale>/iphone-6-9/` (reuse primary-locale PNGs if UI is single-language)
   - [ ] Validate character limits and diacritics
   - [ ] Add locale to the sync script's locale list (if it has a hardcoded list)
   - [ ] Dry-run: `python3 Scripts/asc-sync.py --dry-run --locales <new-locale>`
   - [ ] Live run: `python3 Scripts/asc-sync.py --locales <new-locale>`
   - [ ] Verify in ASC UI that listing appears correctly
   </checklist>
   
   <avoid>
   - Hardcoding English copy for non-English locales ("en-US fallback" is lazy and tanks conversion)
   - Committing raw screenshots to git (binary bloat) — commit only the text metadata; screenshots are regenerated by capture scripts
   - Editing listing copy in the ASC web UI after the first sync (changes get overwritten on next sync — edit the `.txt` files instead)
   - Re-running sync without validating character counts — Apple may accept upload and reject at submission
   - Using `APP_IPHONE_61` (6.1") as the primary set — Apple now derives smaller displays from `APP_IPHONE_67`
   - Storing `.p8` files inside the repo — keychain or `~/.appstoreconnect/` only, chmod 600
   </avoid>
   

   Skip if ai-rules/ already exists — don't overwrite existing rule files.

6. Update project CLAUDE.md — two additions: a. Add a Rule Index section near the top pointing to @ai-rules/rule-loading.md b. Add Skill Reference lines for every installed skill not already listed Only add references for skills relevant to the detected platform. Do NOT duplicate.

7. Report: installed count, skipped count, any failures, CLAUDE.md references added, ai-rules created (yes/no)

CLAUDE.md Skill Reference Templates (by platform):

iOS Skill References

- **Skill Reference**: Use `swiftui-liquid-glass` skill for Liquid Glass implementation patterns
- **Skill Reference**: Use `swiftui-ui-patterns` skill for SwiftUI best practices
- **Skill Reference**: Use `swift-concurrency-expert` skill for async/await patterns
- **Skill Reference**: Use `swiftui-pro` skill for advanced SwiftUI patterns and component design
- **Skill Reference**: Use `swift-concurrency-pro` skill for structured concurrency and actor patterns
- **Skill Reference**: Use `swift-architecture` skill for MVVM, Clean Architecture, and design patterns
- **Skill Reference**: Use `swift-security-expert` skill for iOS security best practices (keychain, encryption, ATT)
- **Skill Reference**: Use `swift-testing-pro` skill for Swift Testing framework patterns
- **Skill Reference**: Use `swiftdata-pro` skill for SwiftData persistence patterns
- **Skill Reference**: Use `core-data-expert` skill for Core Data patterns (if needed alongside SwiftData)
- **Skill Reference**: Use `app-store-aso` skill for App Store Optimization
- **Skill Reference**: Use `shipyard` skill for SDK integration, CLI orchestration, and app store operations

Android Skill References

- **Skill Reference**: Use `mobile-android-design` skill for Material 3 patterns
- **Skill Reference**: Use `app-store-aso` skill for Play Store listing optimization
- **Skill Reference**: Use `shipyard` skill for SDK integration, CLI orchestration, and app store operations

Platform Skill Registries:

iOS Skills

Note: Skills already bundled in user config (swiftui-liquid-glass, swiftui-ui-patterns, swift-concurrency-expert, app-onboarding-questionnaire, shipyard, marketing-psychology, onboarding-cro) are NOT cloned — they are already available.

Example output:

Skills installed for iOS project:
✅ swiftui-pro — already installed, skipped
✅ swiftdata-pro — installed
✅ swift-concurrency-pro — installed
✅ swift-testing-pro — installed
✅ swift-architecture — already installed, skipped
✅ swift-security-expert — installed
✅ core-data-expert — installed
✅ app-store-aso — installed

6 installed, 2 skipped, 0 failed

Android Skills

(Android skill registry will grow as community skills are published)

Flutter Skills

(Flutter skill registry will grow as community skills are published)

React Native (Expo) Skills

(React Native skill registry will grow as community skills are published)

Auto-trigger: When /shipyard:init completes SDK setup, it should suggest running /shipyard:init-skills to install platform skills.

/shipyard:learn-lessons — Extract lessons from the current project

Analyze the current project end-to-end (git history, plans, architecture, SDK integrations, localization, extensions) and capture what was learned. Produces a project-local retrospective document and promotes generalizable lessons to the shared library at ~/.claude-shared/shipyard-lessons/.

Process:

1. Detect platform — same signals as /shipyard:init (iOS, Android, Flutter, RN Expo)
2. Gather project intelligence — git log, plans folder, architecture docs, SDK fingerprints, localization surface, extension targets, memory records
3. Extract lessons across 10 dimensions — architecture, platform, SDK, process, product, localization, performance, security, deployment, design — asking "what pattern worked?" and "what mistake did we make?" for each
4. Classify each lesson — polarity (require / avoid), severity (critical / high / medium / low), scope (project-specific vs generalizable)
5. Write docs/LESSONS-LEARNED.md — systematic table format (summary table, category tables, metrics snapshot, top takeaways)
6. Promote generalizable lessons — create lessons/L-XXX-NNN-*.md files in ~/.claude-shared/shipyard-lessons/lessons/ with full frontmatter, Detect shell block, Fix steps, worked examples
7. Dedupe — before creating a new lesson, scan existing ones; if substantially the same, update last_verified and add to ## Also observed in instead
8. Update INDEX.md — append new rows, keep sorted by ID, update totals and source-projects table
9. Commit — docs: learned-lessons for <project> and docs(shipyard-lessons): add L-XXX-NNN from <project>

Output: Compact summary showing the project-local doc path, new library IDs, reinforced existing IDs, top 3 takeaways.

When to use: At any project milestone, after shipping a major feature, or as a retrospective. Every project you ship should make the next one easier.

Library conventions:

• ID scheme: L-IOS-NNN (iOS), L-AND-NNN (Android), L-FLU-NNN (Flutter), L-RNE-NNN (RN/Expo), L-CRS-NNN (cross-platform), L-PRC-NNN (process). IDs never reused.
• Filenames: kebab-case, imperative (register-extension-bundle-ids-early.md)
• Every lesson must cite a commit hash, file path, or memory record — never invented

/shipyard:update-learned-lessons — Apply the lessons library to this project

Scan the current project against every applicable lesson in ~/.claude-shared/shipyard-lessons/ and apply the fixes where gaps are detected. Platform-aware — only runs lessons tagged for the detected platform plus cross-platform and process lessons.

Process:

1. Detect platform — same logic as /shipyard:learn-lessons
2. Load applicable lessons — read INDEX.md, filter by matching platforms: frontmatter (plus all/cross-platform and all L-PRC-*)
3. Run each Detect check — either the # detect: shell block (exit 0 = pattern PRESENT) or a manual checklist
4. Classify each lesson:
   • ✅ applied — require polarity + pattern present, OR avoid polarity + mistake absent
   • ⚠️ gap — require polarity + pattern absent, OR avoid polarity + mistake present
   • ❓ indeterminate — manual checklist, script errored, or Detect inconclusive
   • ➖ not applicable — applies_when precondition not satisfied
5. Present gap report — grouped by severity (CRITICAL + HIGH shown by default; --all for MEDIUM/LOW)
6. Offer to apply fixes — batch mode or per-lesson y/N confirmation; automated where a # fix: shell block exists, manual-guided otherwise
7. Re-verify after each fix — re-run Detect; if still failing, flag for human review
8. Update docs/LESSONS-LEARNED.md — append to ## Update log with applied/deferred IDs
9. Commit — chore: apply shipyard lessons L-XXX-NNN, L-YYY-NNN

Flags:

• --all — include MEDIUM and LOW severity in the report (default: critical + high only)
• --dry-run — detect and report only, never apply
• --only <id> — run a single lesson by ID
• --category <name> — filter by category (sdk, architecture, process, …)
• --auto — apply CRITICAL + HIGH automated fixes without per-lesson confirmation (use with caution)

Safety rules:

• Platform filter is mandatory — never run an Android-tagged lesson on an iOS project
• Never apply a fix whose Detect verification still fails afterward — flag instead
• Never modify library lessons from this command — that's /shipyard:learn-lessons's job
• Fixes touching .github/, Fastfile, or settings.json should be proposed via PR, not applied directly

When to use: After /shipyard:init on a new project (proactive gap check), when picking up a project after a pause, or before a release cut to catch regressions against known good patterns.

/shipyard:help — Show all commands

Display the full command reference with examples.

Tool Installation Commands

When abilities are missing, provide exact install commands:

# CLIs
npm install -g @playwright/mcp@latest
npm install -g adapty
npm install -g firebase-tools
brew install app-store-connect-cli  # provides `asc` binary

# Skills (clone to ~/.claude-shared/skills/)
# Use /shipyard:init-skills to auto-install all platform skills
# Manual install example:
SKILLS_DIR="$HOME/.claude-shared/skills"
git clone https://github.com/twostraws/SwiftUI-Agent-Skill.git "$SKILLS_DIR/swiftui-pro"
# If SKILL.md is nested, flatten: cd "$SKILLS_DIR/swiftui-pro" && cp -r swiftui-pro/* . 2>/dev/null

# MCP servers
claude mcp add playwright -- npx @playwright/mcp@latest
# PostHog MCP — available as built-in claude.ai MCP, authenticate via mcp__posthog__authenticate

Chrome Session Management

Always use the user's existing Chrome profile for dashboard automation. This preserves:

• Google SSO sessions (Adapty, Firebase, PostHog)
• App Store Connect sessions
• Any dashboard sessions

Config pattern (in settings.json mcpServers):

{
  "playwright": {
    "command": "/path/to/playwright-mcp",
    "args": ["--browser", "chrome", "--user-data-dir", "~/Library/Application Support/Google/Chrome"]
  }
}

Important notes:

• User MUST close Chrome before Playwright can use the profile (Chrome locks it)
• After Playwright is done, user can reopen Chrome normally
• The --user-data-dir path varies by OS:
  • macOS: ~/Library/Application Support/Google/Chrome
  • Linux: ~/.config/google-chrome
  • Windows: %LOCALAPPDATA%\Google\Chrome\User Data

Dynamic Path Resolution

Never hardcode user-specific paths. Resolve dynamically:

# Home directory
HOME=$(eval echo ~)

# Node binary path
NODE_BIN=$(dirname $(which node))

# Chrome profile (macOS)
CHROME_PROFILE="$HOME/Library/Application Support/Google/Chrome"

# Project bundle ID
BUNDLE_ID=$(grep "PRODUCT_BUNDLE_IDENTIFIER" project.yml | head -1 | awk '{print $2}')

Integration with Other Skills

Figma Integration

Organize screenshots and assets in Figma for design review and App Store submission prep.

What Figma REST API CAN do

• Read file structure, pages, nodes, styles, components
• Export existing nodes as PNG/SVG/PDF
• Update image fills on existing nodes (replace, not create)
• Post comments on frames
• Read component/style metadata

What Figma REST API CANNOT do

• Create new nodes (frames, rectangles, text) on canvas
• Place/position images on a page
• Create new pages
• Arrange layouts or set auto-layout properties

Figma REST API usage

import urllib.request, json

# Get file structure
req = urllib.request.Request(
    f"https://api.figma.com/v1/files/{FILE_KEY}?depth=1",
    headers={"X-Figma-Token": FIGMA_TOKEN}
)
data = json.loads(urllib.request.urlopen(req).read())

# Export a node as PNG
req = urllib.request.Request(
    f"https://api.figma.com/v1/images/{FILE_KEY}?ids={NODE_ID}&format=png&scale=2",
    headers={"X-Figma-Token": FIGMA_TOKEN}
)

Recommended workflow

Since programmatic image placement is not possible, use this workflow:

1. Generate screenshots — use app-store-screenshots or app-store-screenshots-2 skill to export PNGs
2. Prepare Figma file — create frames/pages manually in Figma (or use existing ones)
3. Import to Figma — drag-and-drop exported PNGs onto the canvas, or use Cmd+Shift+K (Place Image) to fill existing frames
4. Use REST API for reads — verify file structure, export finalized assets, post review comments

Figma MCP (not currently available)

As of 2026-04, Figma's official Dev Mode MCP (figma-developer-mcp) is read-only — it inspects designs for code generation but cannot create or modify canvas nodes. No write-capable Figma MCP exists yet. If one becomes available, it would be the preferred method.

Token resolution

• Check env var FIGMA_PERSONAL_TOKEN first
• If not set, ask the user for their Figma Personal Access Token
• NEVER hardcode or store tokens in files
• Remind user to rotate token after use if shared in conversation

When to use

• After app-store-screenshots export — read Figma file structure, post comments for review
• After ios-marketing-capture — guide user on importing raw screenshots into Figma
• After /shipyard:connect appstore — verify asset organization before submission

App Store Screenshot Skills

Two screenshot generator skills are available. Choose based on your needs:

Both support multi-locale, export at all Apple required sizes, and iPhone mockup frames.

App Store Connect REST API

The asc CLI covers TestFlight and some subscription operations, but full metadata and screenshot sync require the REST API directly. Build a small Python client — it's ~100 LOC and replaces a mess of curl commands and brittle browser automation.

Auth setup

1. Create API key at https://appstoreconnect.apple.com/access/integrations/api
   • Role: Admin or App Manager (Developer role cannot edit App Store listings — you'll get 401 on every metadata endpoint even with a valid JWT)
2. Download the .p8 exactly ONCE — Apple never shows it again. If lost, revoke and regenerate.
3. Store at fixed path:

   ~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8  (chmod 600)
   

4. Export in ~/.zshrc:

   export APP_STORE_API_KEY="<10-char key ID>"
   export APP_STORE_API_ISSUER="<UUID from ASC Integrations page>"
   

JWT signing — the one gotcha

App Store Connect requires ES256 with signature in raw r||s format per RFC 7515 §A.3.

⚠ PyJWT 1.x emits DER-encoded ECDSA signatures, which Apple rejects with a generic 401. The JWT looks perfect, the issuer matches, the key has Admin role, date -u matches Apple's clock — and it still fails. This wasted several hours of debugging on a real project.

Solution: Either use PyJWT ≥2.0 or sign with cryptography directly. The cryptography approach has no version-drift risk:

import base64, json, time
from pathlib import Path
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature

def _b64url(b: bytes) -> str:
    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

def make_token(key_id: str, issuer: str, p8_path: Path, ttl: int = 1200) -> str:
    pk = serialization.load_pem_private_key(p8_path.read_bytes(), password=None)
    now = int(time.time())
    header = {"alg": "ES256", "kid": key_id, "typ": "JWT"}
    payload = {"iss": issuer, "iat": now, "exp": now + ttl, "aud": "appstoreconnect-v1"}
    h = _b64url(json.dumps(header, separators=(",", ":")).encode())
    p = _b64url(json.dumps(payload, separators=(",", ":")).encode())
    der = pk.sign(f"{h}.{p}".encode(), ec.ECDSA(hashes.SHA256()))
    r, s = decode_dss_signature(der)
    raw = r.to_bytes(32, "big") + s.to_bytes(32, "big")
    return f"{h}.{p}.{_b64url(raw)}"

Apple tokens max out at 20 minutes (exp - iat ≤ 1200). Mint fresh per run; don't cache.

The resource tree

App Store Connect's data model isn't obvious from the docs. Keep this map handy:

app (bundle ID resolves here)
├── appInfos
│   └── appInfoLocalizations (one per locale)
│       ├── name                ← app name per locale
│       ├── subtitle            ← app subtitle per locale
│       └── privacyPolicyUrl
│   └── primaryCategory         ← LIFESTYLE, HEALTH_AND_FITNESS, etc.
└── appStoreVersions (one editable at a time)
    ├── copyright
    ├── releaseType              ← MANUAL / AFTER_APPROVAL / SCHEDULED
    ├── appStoreReviewDetail     ← review contact + notes
    └── appStoreVersionLocalizations (one per locale)
        ├── description
        ├── keywords             ← comma-separated, no trailing spaces, ≤100 chars
        ├── promotionalText      ← editable anytime, ≤170 chars
        ├── whatsNew             ← release notes, NOT editable on v1.0 initial release
        ├── marketingUrl
        ├── supportUrl
        └── appScreenshotSets (one per display type)
            └── appScreenshots (3–10 per set)

Critical distinction: name/subtitle live on appInfoLocalization (app-wide). description/keywords/whatsNew live on appStoreVersionLocalization (version-specific). Beginners confuse these and keep hitting the wrong endpoint.

Finding the editable version

def find_editable_version(client, app_id):
    r = client.get(
        f"/apps/{app_id}/appStoreVersions",
        **{"filter[appStoreState]": "PREPARE_FOR_SUBMISSION,DEVELOPER_REJECTED,REJECTED,METADATA_REJECTED,WAITING_FOR_REVIEW,INVALID_BINARY"},
    )
    data = r.get("data", [])
    return data[0] if data else None

Use comma-separated states. If no editable version exists, the user needs to create one in ASC first (requires an uploaded build).

Screenshot upload — the 3-phase handshake

Apple uses a reservation-then-PUT-then-commit protocol so abandoned uploads don't leave dangling files:

import hashlib, requests

def upload_screenshot(client, set_id: str, path: Path):
    data = path.read_bytes()
    md5 = hashlib.md5(data).hexdigest()

    # Phase 1: reserve
    resv = client.post("/appScreenshots", {
        "data": {
            "type": "appScreenshots",
            "attributes": {"fileName": path.name, "fileSize": len(data)},
            "relationships": {
                "appScreenshotSet": {"data": {"type": "appScreenshotSets", "id": set_id}}
            },
        }
    })
    sid = resv["data"]["id"]
    ops = resv["data"]["attributes"]["uploadOperations"]

    # Phase 2: PUT each chunk to Apple's presigned URL
    for op in ops:
        headers = {h["name"]: h["value"] for h in op.get("requestHeaders", [])}
        chunk = data[op["offset"] : op["offset"] + op["length"]]
        requests.request(op["method"], op["url"], headers=headers, data=chunk, timeout=120).raise_for_status()

    # Phase 3: commit
    client.patch(f"/appScreenshots/{sid}", {
        "data": {
            "type": "appScreenshots",
            "id": sid,
            "attributes": {"uploaded": True, "sourceFileChecksum": md5},
        }
    })

Skip Phase 3 and the screenshot sits forever in UPLOADING state. Always include the MD5 — Apple rejects commits without it.

Display types and sizes

For iPhone 17 Pro captures (native 1206×2622, 6.3"), upscale to 1290×2796 (APP_IPHONE_67) — Apple accepts it and derives the 6.9" display from there. Pad with black bars if aspect ratios don't match.

Idempotency patterns (critical for re-runnable sync)

Mobile metadata sync has to be safe to re-run. These error patterns show up every time:

1. 409 DUPLICATE on POST — locale already exists (auto-created by Apple when version was made). Fall back to GET + PATCH:

   try:
       return client.post("/appStoreVersionLocalizations", payload)["data"]
   except RuntimeError as e:
       if "DUPLICATE" in str(e) or "already exists" in str(e):
           current = get_version_localizations(client, version_id).get(locale)
           return client.patch(f"/appStoreVersionLocalizations/{current['id']}", patch_payload)["data"]
       raise
   

2. 409 STATE_ERROR on whatsNew — Apple disallows "What's New" on first-version submissions (1.0). There's nothing "new" about a first release. Either skip entirely for 1.0 or try-catch:

   def _try_patch_whats_new(client, loc_id, whats_new):
       try:
           client.patch(f"/appStoreVersionLocalizations/{loc_id}",
               {"data": {"type": "appStoreVersionLocalizations", "id": loc_id,
                         "attributes": {"whatsNew": whats_new}}})
       except RuntimeError as e:
           if "STATE_ERROR" in str(e) or "cannot be edited" in str(e):
               return  # silently skip on first release
           raise
   

3. Screenshot set: create once, wipe contents each run. Don't delete the appScreenshotSet itself — its relationship to appStoreVersionLocalization is stable. Just delete all appScreenshots inside it and re-upload.

4. Stale sets from past display-type changes — if someone uploaded to APP_IPHONE_61 in a prior run and you're now uploading to APP_IPHONE_67, the old set lingers. Clean it up or ASC shows mixed sizes.

Recommended file layout

Store metadata as files so they're reviewable in git (without the raw binaries — .gitignore marketing/):

marketing/
├── asc-metadata/
│   ├── shared.json                    ← URLs, copyright, review info, category, release type
│   └── <locale>/
│       ├── name.txt
│       ├── subtitle.txt
│       ├── description.txt
│       ├── keywords.txt
│       ├── promotional_text.txt
│       └── release_notes.txt
└── asc-screenshots/
    └── <locale>/<display-slug>/*.png

This separates content (editable by marketing/copywriters) from the sync logic (editable by engineers). Copywriters PR their .txt changes; engineers re-run the sync.

Common 401 debugging flow

When you get 401 NOT_AUTHORIZED with a correctly formed JWT:

1. Check key role at https://appstoreconnect.apple.com/access/integrations/api — must be Admin or App Manager
2. Check "Last used" column — if it updates after your attempts, Apple IS receiving the token; problem is with signature or issuer match
3. Check signature format — if using PyJWT, check version with pip show pyjwt. Anything <2.0 emits DER format → rejected. Upgrade or switch to cryptography direct signing
4. Check Issuer ID — the UUID at the top of the Integrations page, above the keys table. Must match APP_STORE_API_ISSUER exactly
5. Check .p8 file integrity — openssl ec -in AuthKey_XXX.p8 -noout should succeed; ECDSA P-256 key
6. Clock skew — date -u vs curl -sI https://api.appstoreconnect.apple.com/ | grep -i date:. Apple tolerates ~5 min drift
7. Nuclear option — revoke key, generate new one, download new .p8, update env. Cheapest way to rule out stale/mismatched key material

When to use the asc CLI vs REST API

Rules

• Never hardcode paths — resolve dynamically from environment
• Always check before installing — which <tool> before npm install -g
• Always authenticate before using — check auth status before CLI operations
• Always use graceful fallbacks — placeholder keys = silent disable, not crash
• Always follow platform conventions — SPM for iOS, Gradle for Android, etc.
• Always use the AnalyticsRouter pattern — never call SDKs directly from UI
• Always preserve existing code — read before writing, extend don't replace
• Always warn before Playwright — user must close Chrome first
• Revenue events need provider-specific formatting — $revenue for PostHog, AFEventParamRevenue for AppsFlyer, etc.
• Client SDK keys are safe to compile — they're public tokens, not server secrets