/safari-extension-control-workflow

name: safari-extension-control-workflow
description: Guide macOS Safari integration decisions across Safari Web Extensions, Safari Web Inspector Extensions, Safari App Extensions, SafariServices APIs, content blockers, extension messaging, and app-to-Safari control surfaces. Use when the user wants a Mac app to extend, message, open, inspect, debug, or coordinate with Safari without confusing WebExtension, Web Inspector, native extension, content blocker, authentication, or AppleScript-style automation paths.

Safari Extension Control Workflow

Purpose

Guide Safari integration work for macOS apps, with enough platform awareness to choose the right Safari extension or SafariServices surface before implementation starts.

This skill owns the decision between Safari Web Extensions, Safari Web Inspector Extensions, Safari App Extensions, content blockers, SafariServices APIs, app-to-extension messaging, and limited external automation paths. It is not a generic browser-extension guide and it is not a replacement for `xcode-build-run-workflow` or `xcode-testing-workflow`.

When To Use

• Use this skill when the user wants a macOS app to extend Safari, communicate with Safari content, or coordinate native app state with a Safari extension.
• Use this skill when choosing between a Safari Web Extension, Safari Web Inspector Extension, Safari App Extension, Safari content blocker, `SFSafariApplication`, `SFSafariExtensionManager`, `SFSafariViewController`, `ASWebAuthenticationSession`, AppleScript, Shortcuts, or URL-opening behavior.
• Use this skill when the work involves WebExtension manifests, Web Inspector developer-tool panels, native messaging, app groups, injected scripts, toolbar items, content blockers, Safari profiles, temporary extension loading, unsigned extension testing, or App Store distribution.
• Use this skill when a user says they want to "control Safari" from a Mac app and the first job is distinguishing supported SafariServices control from broader GUI or scripting automation.
• Recommend `explore-apple-swift-docs` when the user primarily needs direct Apple documentation lookup rather than integration-shape guidance.
• Recommend `xcode-build-run-workflow` when the next step is target setup, build settings, entitlements, signing, file membership, running the containing app, or guarded Xcode project mutation.
• Recommend `xcode-testing-workflow` when the next step is repeatable XCTest, XCUITest, extension-state checks, or test-plan work.
• Recommend `swiftui-app-architecture-workflow` when the Safari work is settled and the remaining question is native app scene, command, focus, or settings structure.

Single-Path Workflow

1. Classify the Safari integration request:

• WebExtension-compatible browser feature
• Web Inspector developer-tool feature
• macOS-only Safari App Extension feature
• declarative content blocking
• containing app to extension messaging
• extension to webpage or injected-script messaging
• app-initiated Safari window, tab, or extension-state operation
• authentication, reading list, associated-domain, or in-app Safari content
• external automation outside SafariServices

2. Apply the Apple docs gate before recommending shape:

• read the relevant SafariServices, Safari Web Extension, Safari App Extension, App Extension, or AuthenticationServices documentation first
• state the documented behavior or platform limit being relied on
• if Apple docs and the current code disagree, stop and surface that conflict
• if no relevant Apple documentation can be found, say that explicitly before proceeding

3. Choose the supported integration surface:

• Safari Web Extension for cross-browser-style JavaScript, HTML, CSS, manifest, browser APIs, iOS, visionOS, Mac web apps, or extension portability
• Safari Web Inspector Extension for developer-facing tools that extend Safari Web Inspector rather than user-facing browsing behavior
• Safari App Extension for macOS-only native extension behavior that uses SafariServices classes and can share data with a containing Mac app
• Content blocker when the feature is declarative blocking and does not need to inspect page content or run arbitrary page logic
• `SFSafariApplication` and related Safari App Extension proxies only for supported Safari extension interactions such as opening windows, sending app-to-extension messages, or working with Safari windows, tabs, pages, and toolbar items from the extension context
• `SFSafariExtensionManager` for extension state checks before UI or feature claims
• `ASWebAuthenticationSession` for SSO-style browser authentication rather than embedding or automating Safari
• external automation only when the user explicitly needs behavior outside SafariServices and has accepted automation, permissions, fragility, and user-visible side effects

4. Plan data flow and permissions:

• keep app, extension, and JavaScript contexts explicit
• use app groups for shared app and extension data when Apple requires a shared container
• keep message names typed or centralized in code and document payload shapes
• model profile-aware behavior when Safari profile identifiers are exposed
• avoid logging sensitive URLs, cookies, page text, tokens, or browsing history

5. Plan validation:

• verify extension visibility and enabled state before debugging feature logic
• test unsigned-extension setup separately from signed distribution setup
• validate the containing app install path, Safari Settings state, profile state, and Web Inspector or system logs when relevant
• run Xcode build, signing, entitlements, target membership, or UI validation through the Xcode skills

6. Return one recommendation path with:

• chosen Safari surface
• documented Apple behavior relied on
• native app, extension, JavaScript, and Safari ownership boundaries
• messaging and shared-data plan
• validation plan
• one handof