Opening Your Rork Max App to Apple Intelligence — Designing App Intents Assistant Schemas and Handling What Doesn't Fit

Writing a schema-conforming App Intent

You declare conformance with the @AssistantIntent(schema:) macro. The compiler checks the parameters and return types the schema requires. Omitting a required property fails the build, which lets you catch the half-finished state — "I declared it, but it doesn't match what Apple Intelligence expects" — early.

import AppIntents
 
@AssistantIntent(schema: .photos.openAsset)
struct OpenWallpaperIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Wallpaper"
 
    // The schema requires a target. Its type must conform to AssistantEntity.
    @Parameter(title: "Wallpaper")
    var target: WallpaperEntity
 
    func perform() async throws -> some IntentResult {
        // Your app's real work. Keep this to calling the display logic
        // Rork Max already generated — nothing heavier.
        await WallpaperRouter.shared.present(id: target.id)
        return .result()
    }
}

You conform the target entity to the matching schema too. Adding @AssistantEntity(schema:) lets Apple Intelligence treat it as a "photo asset."

@AssistantEntity(schema: .photos.asset)
struct WallpaperEntity: IndexedEntity {
    let id: String
 
    // The display name the schema requires. Name it the way a user would speak.
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(title)")
    }
 
    let title: String
    let assetURL: URL
}

Not putting heavy display work inside perform() is a hard-won rule. Calls through Apple Intelligence can fire while the app isn't in the foreground. If you park UI-state-dependent logic in the Intent, a background launch will break it. Keep the Intent as a routing entrance and delegate the real work to your existing router. Holding that separation from the start noticeably cut down on later accidents.

Routing what the fixed schemas don't cover

In practice you'll always have features that fit none of the twelve domains. For a wallpaper app, "shuffle today's pick" is neither opening nor searching a photo — it's a bespoke action.

Forcing it into the photos schema invites Apple Intelligence to call it in the wrong context. If a user says "open a photo" and a shuffle runs, the experience is broken. The safe move is to write such actions as plain custom App Intents and surface them through AppShortcuts.

struct ShuffleWallpaperIntent: AppIntent {
    static let title: LocalizedStringResource = "Shuffle Wallpaper"
    static let openAppWhenRun = false
 
    func perform() async throws -> some IntentResult {
        try await WallpaperStore.shared.shuffleToday()
        return .result()
    }
}
 
struct WallpaperShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: ShuffleWallpaperIntent(),
            phrases: [
                "Shuffle wallpaper in \(.applicationName)",
                "Change my wallpaper in \(.applicationName)"
            ],
            shortTitle: "Shuffle",
            systemImageName: "shuffle"
        )
    }
}

The rule of thumb is single: if the action reads naturally in Apple's vocabulary, use an Assistant Schema; if it's bespoke value that doesn't translate, use a custom Intent. Schemas are a shared language for cross-app actions, not a place to force-translate what makes your app distinctive.

Entities and queries — the path to finding a target

For Apple Intelligence to pin down "that wallpaper," you need an EntityQuery that returns candidates. Build this carelessly and target resolution fails, taking the whole action down with it.

struct WallpaperQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [WallpaperEntity] {
        try await WallpaperStore.shared.load(ids: identifiers)
    }
 
    // Candidates offered when the target is ambiguous. Fewer resolve faster.
    func suggestedEntities() async throws -> [WallpaperEntity] {
        try await WallpaperStore.shared.recent(limit: 10)
    }
}

The count suggestedEntities() returns maps directly to perceived speed. Return everything and resolution grows heavy, with a visible lag in Siri's response. Narrowing to about ten recent or popular items shortened the wait on device. When the target isn't uniquely determined, Apple Intelligence presents these candidates to choose from — and if the display names are vague, the user can't tell which to pick. Name displayRepresentation after the words a user says, not an internal ID. That small effort decides the quality of disambiguation.

Availability fallback — don't let features die on unsupported devices

Assistant Schemas and Apple Intelligence run only on supported devices and OS versions. Run several apps as a solo developer and you'll always have some users on older hardware. It defeats the purpose if adding a schema-conforming Intent makes the feature itself vanish on those devices.

The design point is to separate registering the Intent from providing the feature. An Assistant Schema is an added path to being called, not the feature's body. Keep the body in the in-app UI at all times, and treat the assistant path as a secondary route layered on top.

enum AssistantAvailability {
    static var canUseSchemas: Bool {
        if #available(iOS 18.2, *) { return true }
        return false
    }
}

Hold that separation and the same action stays reachable from inside the app on unsupported devices. Position Apple Intelligence support as a "nice-to-have on top," and switch the in-app path based on the availability check. The trap is deleting the in-app button on the assumption of support — that loses the feature outright on older devices.

Testing on device — Shortcuts and Siri as two lenses

The simulator can't reproduce Apple Intelligence's behavior well enough. Splitting the check into two stages on real hardware cut down on gaps.

First, in the Shortcuts app, confirm the Intent shows up as an action. If it doesn't appear there, App Intents registration failed in the first place. Catch missed build configuration or target membership at this stage.

Then talk to Siri with a natural phrasing and confirm it's reached through the schema. The point is to try a deliberately loosened phrasing rather than the registered phrase verbatim. Whether meaning inference — not phrase matching — is actually working only shows up with the loosened wording.

Layering onto Rork Max's Swift

Rork Max generates native Swift from natural language. The display and save logic is usually already in your code. Adding Assistant Schemas is the work of layering a thin shim that calls that existing logic from an Intent's perform().

The order I hold to starts with not touching the feature body. Leave the existing router and store as they are, and add only the Intent and entity as new files. Once you start editing the code Rork Max produced, every regeneration breaks your diff. Keep the assistant work as an independent set of files, and open only a minimal "hook to be called" in the generated code. Draw that boundary first, and the tool's regeneration won't collide with your implementation.

In sequence: first, inventory whether each feature translates into Apple's vocabulary. Second, sort the translatable ones into schema-conforming Intents and the rest into custom Intents plus AppShortcuts. Third, prepare entities and queries, and cap the candidate count. Fourth, keep the in-app path with an availability check. Fifth, run the two-stage check on device.

What running it revealed

What I felt after shipping support is that Apple Intelligence integration is no acquisition magic. More features you can reach by voice doesn't send downloads jumping on its own. What did take effect was giving existing users one more path to reach an action. Once an action buried deep in a menu could be called by voice, usage of that feature ticked up a little. Not flashy, but the quiet kind of improvement.

If reaching native capability is Rork Max's worth, Assistant Schemas feel like one of the easiest places to feel that worth. Declare the shared actions — open, search — in Apple's vocabulary, and leave the distinctive value honestly as custom Intents. The more carefully you draw that line, the more accurately Apple Intelligence reads your app's intent.

Much of this area is still exploratory, but I'd be glad if a few of these implementation notes lighten someone's first step. Thank you for reading.