apple-app-intents git:20260620.d4b3079A

Immutable. This exact content is served forever at /api/v1/blob/3d4c8a5415a21e93.

---
name: apple-app-intents
description: Use when exposing app features to App Intents, Shortcuts, Siri, Spotlight, widgets, controls, or system actions — small safe AppIntents, AppShortcutsProvider, AppEnum/AppEntity, parameters, and open-vs-background behavior.
---

# Apple App Intents

Expose your app's most useful actions to Shortcuts, Siri, Spotlight, widgets, and Control Center. Keep each intent a small, safe action, add an `AppShortcutsProvider` for discoverability, and push real work into services.

## When to use

Use this skill when exposing app features to App Intents, Shortcuts, Siri, Spotlight, widgets, controls, or system actions.

Use when the user asks for:

- App Intents
- Siri actions
- Shortcuts support
- Spotlight actions
- App Shortcuts
- Widget buttons
- Control Center controls
- Action Button support
- Apple Intelligence-compatible app actions

## Core rule

```
App Intent = a small, safe app action the system can run.
App Shortcut = a discoverable phrase and shortcut that exposes that action.
App Entity = app data the system can reference.
```

## When to use this skill

Use this skill for:

- Adding a command to Shortcuts
- Making a menu bar action available from Spotlight
- Creating app actions that run without opening the app
- Opening the app to a specific screen
- Running a task, prompt, skill, or automation from system surfaces
- Adding widget or Control Center interactions
- Defining typed parameters for user actions

## When not to use this skill

Do not use this skill for:

- Normal in-app buttons only
- Complex multi-screen workflows
- Unsafe destructive actions without confirmation
- UI design of sidebars/toolbars/inspectors
- Background daemons with no user-facing actions

## Minimal AppIntent

```swift
import AppIntents

struct StartFocusIntent: AppIntent {
    static var title: LocalizedStringResource = "Start Focus"
    static var description = IntentDescription("Starts a focus session.")
    static var openAppWhenRun = false

    func perform() async throws -> some IntentResult {
        FocusService.shared.start()
        return .result(dialog: "Focus started")
    }
}
```

Requirements:

```
title
perform()
```

## App Shortcut provider

```swift
import AppIntents

struct AppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartFocusIntent(),
            phrases: [
                "Start focus in \(.applicationName)",
                "Begin focus with \(.applicationName)"
            ],
            shortTitle: "Start Focus",
            systemImageName: "timer"
        )
    }
}
```

Rules:

- Every phrase should include `\(.applicationName)`.
- Keep phrases natural.
- Keep shortcuts few and high-value.
- Use clear SF Symbols.

## Return patterns

```swift
// Silent success
return .result()

// Success with dialog
return .result(dialog: "Done")

// Opens app when static openAppWhenRun = true
return .result()
```

Use dialogs for user reassurance:

```
Task created
Report generated
Skill started
Focus mode enabled
```

Avoid long generated responses inside intents.

## Parameters

```swift
struct CreateTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Create Task"

    @Parameter(title: "Title")
    var title: String

    @Parameter(title: "Priority")
    var priority: TaskPriority

    static var parameterSummary: some ParameterSummary {
        Summary("Create \(\.$title) with \(\.$priority) priority")
    }

    func perform() async throws -> some IntentResult {
        TaskStore.shared.create(title: title, priority: priority)
        return .result(dialog: "Task created")
    }
}
```

## AppEnum pattern

```swift
import AppIntents

enum TaskPriority: String, AppEnum {
    case low
    case normal
    case high

    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Priority")

    static var caseDisplayRepresentations: [TaskPriority: DisplayRepresentation] = [
        .low: "Low",
        .normal: "Normal",
        .high: "High"
    ]
}
```

Use `AppEnum` for small controlled choices:

```
Priority
Mode
Report type
Model choice
Export format
Task status
```

## AppEntity pattern

Use `AppEntity` when the intent needs to reference app data.

```swift
import AppIntents

struct ProjectEntity: AppEntity {
    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Project")
    static var defaultQuery = ProjectQuery()

    let id: String
    let name: String

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)")
    }
}

struct ProjectQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [ProjectEntity] {
        ProjectStore.shared.projects
            .filter { identifiers.contains($0.id) }
            .map { ProjectEntity(id: $0.id, name: $0.name) }
    }

    func suggestedEntities() async throws -> [ProjectEntity] {
        ProjectStore.shared.recentProjects
            .map { ProjectEntity(id: $0.id, name: $0.name) }
    }
}
```

Use `AppEntity` for:

```
Projects
Tasks
Skills
Prompts
Reports
Files
Notes
Clients
Workspaces
```

## Open app or stay background

Stay background for quick actions:

```swift
static var openAppWhenRun = false
```

Open app for visual workflows:

```swift
static var openAppWhenRun = true
```

Use background for:

```
Create task
Start run
Toggle mode
Generate short report
Save note
```

Use open app for:

```
Open project
Review report
Edit prompt
Show run details
Configure skill
```

## Default intents for an agent app

Recommended starting intents:

```
Create Task
Start Agent Run
Open Active Runs
Run Skill
Validate Skill
Create Prompt
Generate Daily Report
Search Memory
Open Project
Toggle Focus Mode
```

## Menu bar app minimum

Every useful menu bar app should expose at least:

```
1. Open app / show main panel
2. Run primary action
3. Open settings or create common item if relevant
```

Example:

```swift
struct OpenCommandPaletteIntent: AppIntent {
    static var title: LocalizedStringResource = "Open Command Palette"
    static var openAppWhenRun = true

    func perform() async throws -> some IntentResult {
        AppRouter.shared.openCommandPalette()
        return .result()
    }
}
```

## Safety rules

Do not expose dangerous actions without friction.

Avoid direct intents like:

```
Delete All Projects
Clear All Memory
Remove All Files
Reset Workspace
```

If destructive action is needed:

```
- Use clear title
- Require confirmation in app where possible
- Prefer opening the app
- Return a dialog explaining what happened
- Support undo if possible
```

## File placement rules

```
App Intents should live in the app target or a target visible to the app.
Keep intent code small.
Call services for real work.
Do not put heavy business logic directly inside perform().
```

Recommended structure:

```
AppName/
  Intents/
    AppShortcuts.swift
    CreateTaskIntent.swift
    RunSkillIntent.swift
    Entities/
      ProjectEntity.swift
      SkillEntity.swift
      TaskEntity.swift
  Services/
    TaskService.swift
    SkillService.swift
    ReportService.swift
```

## Testing checklist

```
[ ] App builds with AppIntents imported
[ ] Shortcuts appear in Shortcuts app
[ ] Shortcuts appear in Spotlight where supported
[ ] Phrases include application name
[ ] Parameters display clearly
[ ] Entity suggestions work
[ ] Intent succeeds when app is closed where expected
[ ] Intent opens app where expected
[ ] Errors return useful dialog
[ ] Destructive actions are protected
[ ] Works after clean install
```

## Common mistakes

```
❌ Too many shortcuts
❌ Phrases without app name
❌ Heavy logic inside perform()
❌ Unsafe destructive actions
❌ AppEntity without useful suggested entities
❌ Intent opens app when it should be quick background action
❌ Background intent tries to show UI
❌ No error handling
❌ No testing in Shortcuts app
```

## Prompt template

Drop this into any coding agent (Claude Code, Codex, Cursor, …) to apply the skill:

```
Use the apple-app-intents skill to add App Intents support.

Goal:
Expose the app's most useful actions to Shortcuts, Siri, Spotlight, widgets, or controls.

Rules:
- Create small, safe AppIntent types.
- Add AppShortcutsProvider for discoverability.
- Every phrase should include \(.applicationName).
- Use AppEnum for small controlled choices.
- Use AppEntity for app data like projects, skills, tasks, prompts, notes, and reports.
- Keep perform() small and call services for real work.
- Use openAppWhenRun intentionally.
- Avoid unsafe destructive actions or require confirmation by opening the app.
- Add useful dialogs for success and failure.
- Compile and test in Shortcuts.

After coding:
1. List files changed.
2. List intents added.
3. List shortcuts added.
4. Explain parameters/entities.
5. Explain safety behavior.
6. Give manual testing steps.
```