agentleFS
aka-kikaaka-kika/akakika-skills/skills/swift-macos/apple-app-intents/SKILL.md

apple-app-intents

Skill11 starsChanged 3 months agoMITView on GitHub

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.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 13 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 12
  2. Distinctive:

    Use when the user asks for:

    line 14
  3. Distinctive:

    Use this skill for:

    line 36
  4. Distinctive:

    Do not use this skill for:

    line 48
  5. Very specific:

    Every phrase should include \(.applicationName).

    line 102
  6. Distinctive:

    Keep shortcuts few and high-value.

    line 104
  7. Distinctive:

    Use clear SF Symbols.

    line 105
  8. Distinctive:

    Use dialogs for user reassurance:

    line 120
  9. Distinctive:

    Avoid long generated responses inside intents.

    line 129
  10. Very specific:

    Use AppEnum for small controlled choices:

    line 174
  11. Very specific:

    Use AppEntity when the intent needs to reference app data.

    line 187
  12. Distinctive:

    Use open app for:

    line 256
  13. Distinctive:

    Every useful menu bar app should expose at least:

    line 285
  14. Distinctive:

    Do not expose dangerous actions without friction.

    line 309
  15. Distinctive:

    Avoid direct intents like:

    line 311
  16. Distinctive:

    If destructive action is needed:

    line 320

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

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

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

// 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

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

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.

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:

static var openAppWhenRun = false

Open app for visual workflows:

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:

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.