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.
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
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
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
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
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
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
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 handoff if the work should move into docs lookup, Xcode execution, testing, SwiftUI architecture, or external automation
platform_context: optional emphasis such as macos, ios, visionos, mac-web-app, or mixed-apple.
extension_shape: optional explicit shape such as web-extension, app-extension, content-blocker, unknown, or no-extension.
control_goal: optional explicit goal such as open-url, open-window, send-message, read-page-state, modify-page, block-content, authenticate, or automate-ui.
Defaults:
docs-first guidance always applies
prefer Safari Web Extensions for portable browser-extension behavior
prefer Safari Web Inspector Extensions only for developer tools that live inside Safari Web Inspector
prefer Safari App Extensions only when the macOS-only native extension model is the real requirement
prefer SafariServices and AuthenticationServices over GUI scripting when the documented API surface covers the job
Outputs
status
success: the request belongs to this workflow and a Safari integration recommendation is ready
handoff: the request belongs to another Apple Dev skill after Safari-aware classification
blocked: the request lacks enough context or relies on unsupported Safari behavior
path_type
primary: the recommendation uses a documented SafariServices, Web Extension, Web Inspector Extension, App Extension, content blocker, or authentication path
fallback: the recommendation depends on external automation because the documented Safari API surface does not cover the requested behavior
output
resolved Safari integration class
chosen Safari surface
documented Apple behavior relied on
app, extension, JavaScript, and Safari ownership boundaries
messaging and shared-data plan
validation plan
recommended skill or automation handoff when needed
Guards and Stop Conditions
Do not claim a Mac app can freely inspect or control arbitrary Safari windows, tabs, cookies, page content, or user browsing state unless the documented SafariServices, extension, or automation surface actually supports it.
Do not use AppleScript, Shortcuts, UI automation, accessibility automation, or browser GUI scripting as the first recommendation when a supported SafariServices or extension path exists.
Do not collapse Safari Web Extension native messaging, Safari App Extension injected-script messaging, and app-group shared storage into one vague "bridge"; name the exact contexts and transport.
Do not recommend a Safari App Extension for portable WebExtension behavior unless a macOS-only native extension requirement is explicit.
Do not recommend a Safari Web Extension for arbitrary native control of Safari outside the browser-extension permission model.
Do not recommend a Safari Web Inspector Extension for ordinary end-user browser customization; Web Inspector extensions are developer tools.
Stop with blocked when the feature requires user-private Safari data or privileged browser control that Apple does not expose through the documented APIs and the user has not explicitly opted into external automation.
Fallbacks and Handoffs
Recommend explore-apple-swift-docs when the real need is direct Apple docs lookup for SafariServices, Web Extensions, App Extensions, Web Inspector Extensions, or AuthenticationServices.
Recommend xcode-build-run-workflow when the next step is creating targets, adding entitlements, wiring app groups, signing, running the containing app, or debugging build/install state.
Recommend xcode-testing-workflow when the next step is repeatable test design or extension-state verification.
Recommend swiftui-app-architecture-workflow when Safari integration shape is settled and the native app shell needs scene, command, focus, settings, or menu ownership guidance.
Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable Xcode-project policy for a repo that will own the containing app and extension targets.
Treat external automation as a conscious fallback, not the default. When it is requested, state the user-visible permissions, fragility, and Safari-version sensitivity before implementation.
Customization
Use references/customization-flow.md.
scripts/customization_config.py exists to preserve the repo-wide customization-file contract, but the first version of this skill defines no runtime-enforced knobs.
Keep the first release focused on the documented Safari surface decision. If future iterations add deterministic checks for manifests, entitlements, or app-group configuration, document the knobs before runtime behavior depends on them.
Recommend explore-apple-swift-docs when the user needs current Apple docs before a Safari implementation choice.
Recommend xcode-build-run-workflow when the user needs target, signing, entitlements, build, run, or install follow-through.
Recommend xcode-testing-workflow when the user needs repeatable extension-state or Safari UI verification.
Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable Xcode project guidance for containing-app and extension-target work.
