relevancekit
Increase widget visibility on Apple Watch using RelevanceKit
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill relevancekitInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of relevancekit
relevancekit scores 86/100 on our quality scale, 2434th of 4,698 Development & Engineering skills we index.
Its SKILL.md is 16 KB long, well organised into 34 sections with 17 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-03 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
relevancekit compared with similar skills
All 4 of these similar skills score higher than relevancekit; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| relevancekit (this skill)by dpearson2699 | 86 | 1.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install relevancekit?
- Run
npx skills add dpearson2699/swift-ios-skills --skill relevancekit. The install tabs above show the steps for each supported agent. - Which AI agents does relevancekit work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is relevancekit safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is relevancekit still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: relevancekit 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."
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 for complete relevant-widget, timeline provider, grouping, preview, and permission patterns.
Contents
- Overview
- Setup
- Relevance Providers
- Boundary Routing
- Time-Based Relevance
- Location-Based Relevance
- Fitness and Sleep Relevance
- Hardware Relevance
- Combining Signals
- Widget Integration
- Common Mistakes
- Review Checklist
- References
Overview
watchOS uses two mechanisms to determine widget relevance in the Smart Stack:
- Timeline provider relevance -- implement
relevance()on an existingAppIntentTimelineProviderto attachRelevantContextclues to timeline entries. Available across platforms; only watchOS acts on the data. - Relevant widget -- use
RelevanceConfigurationwith aRelevanceEntriesProviderto 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
| Type | Module | Role |
|---|---|---|
| RelevantContext | RelevanceKit | A contextual clue (date, location, fitness, sleep, hardware) |
| WidgetRelevance | WidgetKit | Collection of relevance attributes for a widget kind |
| WidgetRelevanceAttribute | WidgetKit | Pairs a widget configuration with a RelevantContext |
| WidgetRelevanceGroup | WidgetKit | Controls grouping behavior in the Smart Stack |
| RelevanceConfiguration | WidgetKit | Widget configuration driven by relevance clues (watchOS 26+) |
| RelevanceEntriesProvider | WidgetKit | Provides entries for a relevance-configured widget (watchOS 26+) |
| RelevanceEntry | WidgetKit | Data needed to render one relevant widget card (watchOS 26+) |
RelevanceConfiguration, RelevanceEntriesProvider, and RelevanceEntry are
WidgetKit APIs. Keep them in this skill's scope only when they are part of the
watchOS relevant-widget workflow that exposes RelevanceKit clues.
Setup
Import
import RelevanceKit
import WidgetKit
Platform Availability
RelevantContext is declared across platforms (iOS 17+, watchOS 10+), but
RelevanceKit functionality only takes effect on watchOS. Calling the API on
other platforms has no effect. Timeline-provider relevance() is available on
iOS 18+, macOS 15+, visionOS 26+, and watchOS 11+ for shared provider code.
RelevanceConfiguration, RelevanceEntriesProvider, and RelevanceEntry are
watchOS 26+ only.
Permissions
Certain relevance clues require authorization or target setup:
| Clue | Required Permission |
|---|---|
| .location(inferred:) | Containing app requests location access; widget extension declares NSWidgetWantsLocation |
| .location(_:) (CLRegion) | Containing app requests location access; widget extension declares NSWidgetWantsLocation |
| .location(category:) | Containing app requests location access; widget extension declares NSWidgetWantsLocation |
| .fitness(.workoutActive) | HealthKit access to HKWorkoutType |
| .fitness(.activityRingsIncomplete) | HealthKit access to appleExerciseTime, appleMoveTime, and appleStandTime |
| .sleep(_:) | HealthKit sleepAnalysis permission |
| .hardware(headphones:) | None |
| .date(...) | None |
Add location purpose strings to the containing app's Info.plist, not only the
widget extension. In widget code, check CLLocationManager.isAuthorizedForWidgetUpdates
before relying on location clues. For fitness and sleep clues, enable HealthKit
and request the exact read types in the app and widget extension target that
provides relevance.
Relevance Providers
Option 1: Timeline Provider with Relevance
Add a relevance() method to an existing AppIntentTimelineProvider. This
approach shares code across iOS and watchOS while adding watchOS Smart Stack
intelligence.
struct MyProvider: AppIntentTimelineProvider {
// ... snapshot, timeline, placeholder ...
func relevance() async -> WidgetRelevance<MyWidgetIntent> {
let attributes = events.map { event in
let context = RelevantContext.date(
from: event.startDate,
to: event.endDate
)
return WidgetRelevanceAttribute(
configuration: MyWidgetIntent(event: event),
context: context
)
}
return WidgetRelevance(attributes)
}
}
Option 2: RelevanceEntriesProvider (watchOS 26+)
Build a widget that only appears when conditions match. The system calls
relevance() to learn when the widget matters, then calls entry() with
the matching configuration to get render data.
@available(watchOS 26.0, *)
struct MyRelevanceProvider: RelevanceEntriesProvider {
func relevance() async -> WidgetRelevance<MyWidgetIntent> {
let attributes = events.map { event in
WidgetRelevanceAttribute(
configuration: MyWidgetIntent(event: event),
context: RelevantContext.date(event.date, kind: .scheduled)
)
}
return WidgetRelevance(attributes)
}
func entry(
configuration: MyWidgetIntent,
context: Context
) async throws -> MyRelevanceEntry {
if context.isPreview {
return .preview
}
return MyRelevanceEntry(event: configuration.event)
}
func placeholder(context: Context) -> MyRelevanceEntry {
.placeholder
}
}
Boundary Routing
When a feature mixes widgets, location, workouts, and Smart Stack relevance,
keep RelevanceKit focused on RelevantContext, WidgetRelevanceAttribute,
provider relevance(), RelevantIntentManager, relevant-widget handoffs, and
permissions for relevance clues. Route timelines, reload budgets, families,
rendering, APNs widget pushes, Live Activities, and widget Controls to
WidgetKit; HKWorkoutSession, HKLiveWorkoutBuilder, HKWorkoutRoute,
queries, activity-ring/sleep data, and authorization UX to HealthKit; and
MKLocalSearch, MKLocalSearchCompleter, MKDirections, geocoding,
authorization, regions, geofencing, and place data to MapKit/CoreLocation.
Time-Based Relevance
Time clues tell the system a widget matters at or around a specific moment.
Single Date
RelevantContext.date(eventDate)
Date with Kind
DateKind provides an additional hint about the nature of the time relevance:
| Kind | Use |
|---|---|
| .default | General time relevance |
| .scheduled | A scheduled event (meeting, flight) |
| .informational | Information relevant around a time (weather forecast) |
RelevantContext.date(meetingStart, kind: .scheduled)
Date Range
// Using from/to
RelevantContext.date(from: startDate, to: endDate)
// Using DateInterval
RelevantContext.date(interval: dateInterval, kind: .scheduled)
// Using ClosedRange
RelevantContext.date(range: startDate...endDate, kind: .default)
Location-Based Relevance
Inferred Locations
The system infers certain locations from a person's routine. No coordinates needed.
RelevantContext.location(inferred: .home)
RelevantContext.location(inferred: .work)
RelevantContext.location(inferred: .school)
RelevantContext.location(inferred: .commute)
Apply the location row in the Permissions table and check
CLLocationManager.isAuthorizedForWidgetUpdates before returning clues.
Specific Region
import CoreLocation
let region = CLCircularRegion(
center: CLLocationCoordinate2D(latitude: 37.3349, longitude: -122.0090),
radius: 500,
identifier: "apple-park"
)
RelevantContext.location(region)
Point-of-Interest Category (26.0+ SDKs)
Indicate relevance near any location of a given category. Returns nil if the
category is unsupported. The factory is SDK-available on Apple platforms 26.0+,
but RelevanceKit clues still only affect Smart Stack behavior on watchOS.
import MapKit
if let context = RelevantContext.location(category: .beach) {
// Widget is relevant whenever the person is near a beach
}
Fitness and Sleep Relevance
Fitness
// Relevant when activity rings are incomplete
RelevantContext.fitness(.activityRingsIncomplete)
// Relevant during an active workout
RelevantContext.fitness(.workoutActive)
Apply the exact fitness mapping in Permissions.
Sleep
// Relevant around bedtime
RelevantContext.sleep(.bedtime)
// Relevant around wakeup
RelevantContext.sleep(.wakeup)
Apply the sleep mapping in Permissions.
Hardware Relevance
// Relevant when headphones are connected
RelevantContext.hardware(headphones: .connected)
No special permission required.
Combining Signals
Return multiple WidgetRelevanceAttribute values in the WidgetRelevance
array to make a widget relevant under several different conditions.
func relevance() async -> WidgetRelevance<MyIntent> {
var attributes: [WidgetRelevanceAttribute<MyIntent>] = []
// Relevant during morning commute
attributes.append(
WidgetRelevanceAttribute(
configuration: MyIntent(mode: .commute),
context: .location(inferred: .commute)
)
)
// Relevant at work
attributes.append(
WidgetRelevanceAttribute(
configuration: MyIntent(mode: .work),
context: .location(inferred: .work)
)
)
// Relevant around a scheduled event
for event in upcomingEvents {
attributes.append(
WidgetRelevanceAttribute(
configuration: MyIntent(eventID: event.id),
context: .date(event.date, kind: .scheduled)
)
)
}
return WidgetRelevance(attributes)
}
Order matters. Return relevance attributes ordered by priority. The system may use only a subset of the provided relevances.
Widget Integration
Relevant Widget with RelevanceConfiguration
@available(watchOS 26, *)
struct MyRelevantWidget: Widget {
var body: some WidgetConfiguration {
RelevanceConfiguration(
kind: "com.example.relevant-events",
provider: MyRelevanceProvider()
) { entry in
EventWidgetView(entry: entry)
}
.configurationDisplayName("Events")
.description("Shows upcoming events when relevant")
}
}
Associating with a Timeline Widget
When both a timeline widget and a relevant widget show the same data, use
associatedKind to prevent duplicate cards. The system repla
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
