Apple Developer Toolkit

Apple Developer Toolkit

This skill has two execution surfaces plus a local Apple docs corpus. Each part works independently with different requirements.

Architecture

Use the right entry point for the job:

node cli.js search ...    # Apple docs + WWDC lookup from this repo
appledev build ...        # SwiftShip app builder
appledev store ...        # App Store Connect CLI
appledev ios ...          # Build iOS Apps plugin workflows in the CLI
appledev macos ...        # Build macOS Apps plugin workflows in the CLI

Important: appledev --help exposes build, store, ios, and macos. Docs lookup is repo-local through node cli.js.

Codex Build iOS/macOS Plugin Features

The OpenAI Codex Build iOS Apps and Build macOS Apps plugin features are implemented directly in the CLI:

• appledev ios features|doctor|mcp-config|simulators|build|screenshot|logs|mirror|memgraph|ettrace
• appledev macos features|doctor|bootstrap|run|logs|codesign-inspect

Load references/codex-build-ios-macos-workflows.md for the detailed feature map and proof loops.

Agent Setup

Before asking the user for defaults, read config.json in this skill directory.

• Keep non-secret setup defaults in config.json
• Keep durable agent-side notes or run logs in ${CLAUDE_PLUGIN_DATA}/apple-developer-toolkit/
• Keep secrets out of repo files. Use env vars or Keychain-backed flows instead

Agent Skills Installation

Use the current Agent Skills CLI syntax when installing this repository into coding agents:

# Install both skills
npx skills add Abdullah4AI/apple-developer-toolkit

# Install a specific skill
npx skills add Abdullah4AI/apple-developer-toolkit --skill ios-rules
npx skills add Abdullah4AI/apple-developer-toolkit --skill swiftui-guides

Supported agents include Claude Code, Codex, Cursor, Windsurf, Gemini CLI, and any agent that supports the Agent Skills format. For Codex or Cursor, install the same skills with npx skills add ... from the project where the agent should use the Apple rules, then let the agent load the generated skill instructions from that workspace.

Agent Safety, Permissions, and Observability

Use this skill with strict agent-operating rules so Apple workflows do not poison future context or create unintended side effects.

Memory Discipline

• Do not save task logs, raw Apple docs output, generated code snippets, App Store state, build errors, credentials, or temporary decisions to persistent memory
• Save only stable reusable facts: user preferences, environment conventions, tool quirks, or confirmed setup details that will matter in future sessions
• Prefer skill references, local artifacts, run summaries, and status files over memory for workflow state

Tool Permission Design

• Read-only by default: node cli.js search, symbols, doc, overview, samples, wwdc-*, appledev store ... list/status/validate/diff/docs/doctor, and reading reference files
• Requires explicit user approval before side effects: App Store Connect creates/updates/deletes, TestFlight publish, App Store submit, metadata/localization updates, pricing/IAP/subscription changes, certificate/profile/device changes, webhooks, notarization, uploads, Xcode Cloud runs, appledev build project writes, simulator launches, or hook installation
• Never use publishing or external-posting tools outside their stated surface. In particular, this skill must not post to X/Twitter or invoke any X publishing command
• If a command can mutate App Store Connect or a local project, state the target app/project, expected change, and whether credentials will be used before running it
• Prefer dry-run, diff, status, validate, or docs commands before mutating commands when available

Observability Requirements

For non-trivial runs, create or preserve enough artifacts to audit what happened:

• Logs: keep command output or tool output relevant to the decision
• Traces: note the command path used, for example node cli.js vs appledev store vs appledev build
• Artifacts: write generated plans, diffs, reports, metadata exports, or build summaries to project-local files when appropriate
• Status files: for long app-builder or release workflows, keep a small status/summary file with current step, target app/project, next safe action, and blockers
• Run summaries: finish with what was checked, what changed, what did not change, and remaining risks

Workflow Orchestration

• Route tasks explicitly: docs lookup → node cli.js; App Store Connect → appledev store; app scaffolding/fix loops → appledev build; platform/design rules → relevant references/ files
• Break multi-step release or build work into inspect → plan → dry-run/validate → execute with approval → verify → summarize
• Use specialized references progressively. Load only the relevant references/apple-*.md, references/ios-rules/, or references/swiftui-guides/ material needed for the task
• Stop and ask when ambiguity changes side effects, such as which app ID, bundle ID, release version, TestFlight group, pricing, certificate, or project path to mutate

Credential Requirements by Feature

Setup

Check config.json first for local defaults and paths.

Part 1: Documentation Search (no setup needed)

Works immediately with Node.js:

node cli.js search "NavigationStack"

Part 2: App Store Connect CLI

Install via Homebrew:

brew install Abdullah4AI/tap/appledev

Authenticate with your App Store Connect API key:

appledev store auth login --name "MyApp" --key-id "KEY_ID" --issuer-id "ISSUER_ID" --private-key /path/to/AuthKey.p8

Or set environment variables:

export APPSTORE_KEY_ID="your-key-id"
export APPSTORE_ISSUER_ID="your-issuer-id"
export APPSTORE_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"

API keys are created at https://appstoreconnect.apple.com/access/integrations/api

Part 3: iOS App Builder

Prerequisites: Xcode (with iOS Simulator), XcodeGen, and an LLM API key for code generation.

appledev build setup    # Checks and installs prerequisites

Build from source

bash scripts/setup.sh

The setup script builds appledev, copies it to /opt/homebrew/bin/appledev, and symlinks swiftship plus appstore to the same binary.

Gotchas

• Apple docs and WWDC lookup are not exposed through appledev --help right now. Use node cli.js ... from this repo for those tasks
• Help text inside cli.js mentions apple-docs ..., but a separate apple-docs binary may not be installed. In this skill, node cli.js ... is the safe path
• appledev store ... needs App Store Connect credentials. If they are missing, authenticate with appledev store auth login or env vars before trying release actions
• appledev build ... is macOS-only in practice and depends on Xcode, Simulator support, and an LLM API key. Do not assume it will work in a generic sandbox
• Hook config lives outside the repo at ~/.appledev/hooks.yaml and optionally inside projects at .appledev/hooks.yaml. Use templates/hooks-*.yaml as starting points instead of writing YAML from scratch
• Do not write secrets into config.json, templates, or repo files

Part 1: Documentation Search

node cli.js search "NavigationStack"
node cli.js symbols "UIView"
node cli.js doc "/documentation/swiftui/navigationstack"
node cli.js overview "SwiftUI"
node cli.js samples "SwiftUI"
node cli.js wwdc-search "concurrency"
node cli.js wwdc-year 2025
node cli.js wwdc-topic "swiftui-ui-frameworks"

Part 2: App Store Connect

Full reference: references/app-store-connect.md

Environment Variables

All environment variables are optional. They override flags when set.

Part 3: Multi-Platform App Builder

Supports iOS, watchOS, tvOS, and iPad. Generates complete Swift/SwiftUI apps from natural language with AI-powered code generation.

appledev build                     # Interactive mode
appledev build setup               # Install prerequisites (Xcode, XcodeGen, AI backend)
appledev build fix                 # Auto-fix build errors
appledev build run                 # Build and launch in simulator
appledev build open                # Open project in Xcode
appledev build chat                # Interactive chat mode (edit/ask questions)
appledev build info                # Show project status
appledev build usage               # Token usage and cost

Supported Platforms

How it works

describe > analyze > plan > build > fix > run

1. Analyze - Extracts app name, features, core flow, target platform from description
2. Plan - Produces file-level build plan: data models, navigation, design
3. Build - Generates Swift source files, project.yml, asset catalog
4. Fix - Compiles and auto-repairs until build succeeds
5. Run - Boots Simulator and launches the app

Interactive commands

References

iOS Rules (38 files)

accessibility, app_clips, app_review, apple_translation, biometrics, camera, charts, color_contrast, components, dark_mode, design-system, feedback_states, file-structure, forbidden-patterns, foundation_models, gestures, haptics, healthkit, live_activities, localization, maps, mvvm-architecture, navigation-patterns, notification_service, notifications, safari_extension, share_extension, siri_intents, spacing_layout, speech, storage-patterns, swift-conventions, timers, typography, view-composition, view_complexity, website_links, widgets

SwiftUI Guides (12 files)

animations, forms-and-input, layout, liquid-glass, list-patterns, media, modern-apis, navigation, performance, scroll-patterns, state-management, text-formatting

Consolidated Apple/Swiftship references

This umbrella absorbed the former one-feature/one-phase Apple skills. Load the targeted reference instead of relying on narrow active sibling skills:

• references/apple-features-skills.md — App Store Connect, framework features, monetization, assets, and app services.
• references/apple-ui-skills.md — accessibility, layout, typography, animations, glass, gestures, and view composition.
• references/apple-extensions-skills.md — widgets, App Clips, Live Activities, Safari/share/notification extensions.
• references/apple-phases-skills.md — Swiftship analyzer/planner/builder/editor/fixer/recovery routing.
• references/apple-always-skills.md and platform variants — shared SwiftUI, design-system, layout, components, navigation, review guidance.