Agent skill

deep-linking

View SKILL.md on GitHub Repository
Stars 127
Forks 10

Install this agent skill to your Project

npx add-skill https://github.com/rshankras/claude-code-apple-skills/tree/main/skills/generators/deep-linking

SKILL.md

Deep Linking Generator

Generate deep linking infrastructure with URL schemes, Universal Links, and App Intents for Siri/Shortcuts.

When to Use

  • User wants to handle custom URL schemes (myapp://)
  • User mentions Universal Links or Associated Domains
  • User wants Siri Shortcuts or App Intents
  • User needs to navigate to specific content from external sources

Pre-Generation Checks

Before generating, verify:

  1. Existing Deep Link Handling

    bash
    # Check for existing URL handling
grep -r "onOpenURL\|open.*url\|handleOpen" --include="*.swift" | head -5

  2. URL Scheme in Info.plist

    bash
    # Check for CFBundleURLTypes
find . -name "Info.plist" -exec grep -l "CFBundleURLSchemes" {} \;

  3. Associated Domains Entitlement

    bash
    find . -name "*.entitlements" -exec grep -l "associated-domains" {} \;

Configuration Questions

1. URL Scheme

  • What custom URL scheme? (e.g., myapp)
  • This enables myapp://path/to/content links

2. Universal Links

  • Yes - Handle HTTPS links (requires AASA file on server)
  • No - Custom URL scheme only

3. App Intents / Siri Shortcuts

  • Yes - Enable voice commands and Shortcuts app
  • No - URL-based deep linking only

4. Link Types

  • Profile: /users/{id}
  • Content: /items/{id}
  • Actions: /actions/share, /actions/create
  • Custom routes based on app needs

Generated Files

Core Infrastructure

Sources/DeepLinking/
├── DeepLinkRouter.swift       # Central router
├── DeepLink.swift             # Route definitions
└── UniversalLinkHandler.swift # Universal link processing

App Intents (Optional)

Sources/AppIntents/
├── OpenContentIntent.swift    # Open specific content
├── AppShortcuts.swift         # Shortcuts provider
└── ContentEntity.swift        # Entities for Spotlight/Siri

Server Files (Universal Links)

.well-known/
└── apple-app-site-association  # AASA file template

Key Features

Route Definitions

swift
enum DeepLink: Equatable {
    case home
    case profile(userId: String)
    case item(itemId: String)
    case settings
    case action(ActionType)

    enum ActionType {
        case share(itemId: String)
        case create
    }
}

URL Parsing

swift
extension DeepLink {
    init?(url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
            return nil
        }

        let pathComponents = components.path.split(separator: "/").map(String.init)

        switch pathComponents {
        case ["users", let userId]:
            self = .profile(userId: userId)
        case ["items", let itemId]:
            self = .item(itemId: itemId)
        case ["settings"]:
            self = .settings
        default:
            self = .home
        }
    }
}

SwiftUI Integration

swift
@main
struct MyApp: App {
    @State private var router = DeepLinkRouter()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(router)
                .onOpenURL { url in
                    router.handle(url)
                }
        }
    }
}

App Intents Integration

OpenIntent for Navigation

swift
struct OpenItemIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Item"

    @Parameter(title: "Item")
    var target: ItemEntity

    func perform() async throws -> some IntentResult {
        await router.navigate(to: .item(itemId: target.id))
        return .result()
    }
}

App Shortcuts

swift
struct AppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenItemIntent(),
            phrases: [
                "Open \(\.$target) in \(.applicationName)",
                "Show \(\.$target)"
            ],
            shortTitle: "Open Item",
            systemImageName: "doc"
        )
    }
}

Required Capabilities

URL Scheme (Info.plist)

xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.myapp</string>
    </dict>
</array>

Universal Links (Entitlements)

xml
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:yourapp.com</string>
    <string>applinks:www.yourapp.com</string>
</array>

Server Configuration (AASA)

Host at https://yourapp.com/.well-known/apple-app-site-association:

json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.yourcompany.yourapp",
        "paths": [
          "/items/*",
          "/users/*",
          "/share/*"
        ]
      }
    ]
  }
}

Integration Steps

1. Basic URL Handling

swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    handleDeepLink(url)
                }
        }
    }
}

2. Universal Links (UIKit)

swift
// In SceneDelegate
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return
    }
    handleUniversalLink(url)
}

3. App Intents Setup

  1. Create entities for Spotlight indexing
  2. Implement OpenIntent for each content type
  3. Define AppShortcuts for Siri phrases
  4. Index entities with CSSearchableIndex

Testing

URL Schemes

bash
# Simulator
xcrun simctl openurl booted "myapp://items/123"

# Device
# Open Safari and navigate to myapp://items/123

Universal Links

bash
# Test AASA file
curl -I "https://yourapp.com/.well-known/apple-app-site-association"
# Should return Content-Type: application/json

# Validate with Apple
# Use Apple's tool or Branch.io validator

App Intents

  1. Build and run on device
  2. Open Shortcuts app
  3. Your app's shortcuts should appear
  4. Test with Siri: "Hey Siri, [your phrase]"

References

Didn't find tool you were looking for?

Be as detailed as possible for better results