Agent-Skills.md

Agent Skills: Background Tasks

Apple BackgroundTasks framework for iOS/iPadOS background processing. Use when scheduling background work, refreshing app content, running long processing tasks, implementing BGAppRefreshTask, BGProcessingTask, BGContinuedProcessingTask, or dealing with BGTaskScheduler setup, registration, submission, expiration handlers, and debugger testing commands.

UncategorizedID: nonameplum/agent-skills/background-tasks

Repository

nonameplum/agent-skills
nonameplum
111

Install this agent skill to your local

pnpm dlx add-skill https://github.com/nonameplum/agent-skills/tree/HEAD/background-tasks

Skill Files

Browse the full folder contents for background-tasks.

Download Skill

Loading file tree…

background-tasks/SKILL.md

Skill Metadata

Name
background-tasks
Description
Apple BackgroundTasks framework for iOS/iPadOS background processing. Use when scheduling background work, refreshing app content, running long processing tasks, implementing BGAppRefreshTask, BGProcessingTask, BGContinuedProcessingTask, or dealing with BGTaskScheduler setup, registration, submission, expiration handlers, and debugger testing commands.

Background Tasks

Apple's BackgroundTasks framework for scheduling and running work while your app is suspended or backgrounded.

Choose the right task type

| Goal | Task class | Time limit | Trigger | |------|-----------|------------|---------| | Short content refresh | BGAppRefreshTask | ~30 seconds | System-decided | | Heavy processing (ML, DB, sync) | BGProcessingTask | Minutes | System-decided, device idle | | Foreground job that must survive backgrounding | BGContinuedProcessingTask | Unlimited | User action only | | Health research data processing | BGHealthResearchTask | Minutes | System-decided, device idle |

Limits: max 1 refresh task + 10 processing tasks schedulable at any time.

Decision tree

  1. Setting up for the first time? → references/setup.md (Info.plist keys, UIBackgroundModes, registration)

  2. Refreshing content periodically? → references/app-refresh.md (BGAppRefreshTask, reschedule pattern)

  3. Running heavy background work? → references/processing.md (BGProcessingTask, power/network requirements)

  4. Foreground task that must survive backgrounding? → references/continued-processing.md (BGContinuedProcessingTask, GPU, progress, Live Activity)

  5. Managing task lifecycle (cancel, limits, pending tasks)? → references/scheduling.md

  6. Handling submit errors? → references/error-handling.md (notPermitted, tooManyPendingTaskRequests, unavailable)

  7. Testing during development? → references/testing.md (LLDB debugger commands, device-only limitation)

Key rules

  • Register all launch handlers before applicationDidFinishLaunching returns.
  • Always set expirationHandler — missing it causes the system to silently mark the task failed.
  • Always call setTaskCompleted(success:) — missing it may cause the system to kill your app.
  • Reschedule inside the launch handler, not after it returns.
  • BGContinuedProcessingTask must be submitted as a result of a user action; it starts in the foreground.

Reference files

  • references/setup.md — Info.plist, UIBackgroundModes, registration
  • references/app-refresh.md — BGAppRefreshTask pattern
  • references/processing.md — BGProcessingTask pattern
  • references/continued-processing.md — BGContinuedProcessingTask, GPU, progress reporting
  • references/scheduling.md — earliestBeginDate, cancel, limits, pending task inspection
  • references/error-handling.md — BGTaskScheduler.Error codes and causes
  • references/testing.md — LLDB simulation commands
  • references/_index.md — Full navigation index
  • backgroundtasks.md — Full Apple API reference (raw docs)