# Relevancekit

Increase widget visibility on Apple Watch using RelevanceKit.

- Repository: https://github.com/dpearson2699/swift-ios-skills (1266 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-07-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dpearson2699/swift-ios-skills --skill relevancekit -g -a claude-code -y`
Codex: `npx skills add dpearson2699/swift-ios-skills --skill relevancekit -g -a codex -y`
Cursor: `npx skills add dpearson2699/swift-ios-skills --skill relevancekit -g -a cursor -y`
Gemini CLI: `npx skills add dpearson2699/swift-ios-skills --skill relevancekit -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dpearson2699/swift-ios-skills`

## Description

Increase widget visibility on Apple Watch using RelevanceKit. Use when providing contextual relevance signals for watchOS widgets, declaring time-based or location-based relevance, combining multiple relevance providers, helping the system surface the right widget at the right time on watchOS 26, or routing mixed RelevanceKit/WidgetKit/HealthKit/MapKit Smart Stack scope.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# RelevanceKit

Provide on-device contextual clues that increase a widget's visibility in the
Apple Watch Smart Stack. RelevanceKit tells the system *when* a widget is
relevant by time, location, fitness state, sleep schedule, or connected hardware.
Targets Swift 6.3 / watchOS 26+.

> **Beta-sensitive.** Re-check Apple documentation before making strong RelevanceKit availability or behavior claims.

See [references/relevancekit-patterns.md](references/relevancekit-patterns.md) for complete relevant-widget, timeline provider, grouping, preview, and permission patterns.

## Contents

- [Overview](#overview)
- [Setup](#setup)
- [Relevance Providers](#relevance-providers)
- [Boundary Routing](#boundary-routing)
- [Time-Based Relevance](#time-based-relevance)
- [Location-Based Relevance](#location-based-relevance)
- [Fitness and Sleep Relevance](#fitness-and-sleep-relevance)
- [Hardware Relevance](#hardware-relevance)
- [Combining Signals](#combining-signals)
- [Widget Integration](#widget-integration)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Overview

watchOS uses two mechanisms to determine widget relevance in the Smart Stack:

1. **Timeline provider relevance** -- implement `relevance()` on an existing
   `AppIntentTimelineProvider` to attach `RelevantContext` clues to timeline
   entries. Available across platforms; only watchOS acts on the data.
2. **Relevant widget** -- use `RelevanceConfiguration` with a
   `RelevanceEntriesProvider` to build a widget driven entirely by relevance
   clues. The system creates individual Smart Stack cards per relevant entry.
   watchOS 26+ only.

Choose a timeline provider when the widget always has data to show and relevance
is supplementary. Choose a relevant widget when the widget should *only* appear
when conditions match, or when multiple cards should appear simultaneously (e.g.,
several upcoming calendar events).

### Key Types

The rest: https://github.com/dpearson2699/swift-ios-skills/blob/HEAD/skills/relevancekit/SKILL.md