axiom-app-discoverability

# App Discoverability

## Overview

**Core principle** Feed the system metadata across multiple APIs, let the system decide when to surface your app.

iOS surfaces apps in Spotlight, Siri suggestions, and system experiences based on metadata you provide through App Intents, App Shortcuts, Core Spotlight, and NSUserActivity. The system learns from actual usage and boosts frequently-used actions. No single API is sufficient—comprehensive discoverability requires a multi-API strategy.

**Key insight** iOS boosts shortcuts and activities that users actually invoke. If nobody uses an intent, the system hides it. Provide clear, action-oriented metadata and the system does the heavy lifting.

---

## When to Use This Skill

Use this skill when:
- Making your app appear in Spotlight search results
- Enabling Siri to suggest your app in relevant contexts
- Adding app actions to Action Button (iPhone/Apple Watch Ultra)
- Making app content discoverable system-wide
- Planning discoverability architecture before implementation
- Troubleshooting "why isn't my app being suggested?"

Do NOT use this skill when:
- You need detailed API reference (use app-intents-ref, axiom-app-shortcuts-ref, axiom-core-spotlight-ref)
- You're implementing a specific API (use the reference skills)
- You just want to add a single App Intent (use app-intents-ref)

---

## The 6-Step Discoverability Strategy

This is a proven strategy from developers who've implemented discoverability across multiple production apps. **Implementation time: One evening for minimal viable discoverability.**

### Step 1: Add App Intents

App Intents power Spotlight search, Siri requests, and Shortcut suggestions. **Without AppIntents, your app will never surface meaningfully.**

```swift
struct OrderCoffeeIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Coffee"
    static var description = IntentDescription("Orders coffee for pickup")

    @Parameter(title: "Coffee Type")
    var coffeeType: Coff