SkillAgentSearch skills...

metrickit

Use when collecting or analyzing production iOS or iPadOS performance telemetry with MetricKit, including iOS 27 MetricManager async metric or diagnostic reports, hang or crash triage, custom signposts, extended launch measurement, durable export, or iOS 26 MXMetricManager compatibility.

Install / Use

npx skills add dpearson2699/swift-ios-skills --skill metrickit

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Tags

Our assessment of metrickit

metrickit scores 89/100 on our quality scale, 1674th of 4,700 Development & Engineering skills we index (top 36%).

Its SKILL.md is 14 KB long, well organised into 16 sections with 6 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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
11/15

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-10-31 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 found

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.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

metrickit compared with similar skills

All 4 of these similar skills score higher than metrickit; compare them before choosing.

SkillScoreStarsUpdatedFormat
metrickit (this skill)by dpearson2699891.1k4mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install metrickit?
Run npx skills add dpearson2699/swift-ios-skills --skill metrickit. The install tabs above show the steps for each supported agent.
Which AI agents does metrickit 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 metrickit 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 metrickit 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.

name: metrickit description: Use when collecting or analyzing production iOS or iPadOS performance telemetry with MetricKit, including iOS 27 MetricManager async metric or diagnostic reports, hang or crash triage, custom signposts, extended launch measurement, durable export, or iOS 26 MXMetricManager compatibility.

MetricKit

Use MetricKit for low-overhead production telemetry that complements local Instruments and Xcode Organizer analysis. On iOS and iPadOS 27, prefer the Swift-first MetricManager report sequences. Keep MXMetricManager only in an explicit iOS 26 compatibility branch.

Beta-sensitive: The iOS/iPadOS 27 surface below is based on Apple's current beta documentation. It has not been locally compiler-verified because Xcode 27 is unavailable in this environment. Re-check the linked Apple documentation and compile with the shipping Xcode 27 SDK before release.

Load MetricKit Extended and Compatibility Patterns when implementing durable ingestion, detailed report analysis, or the iOS 26 compatibility path.

Contents

MetricManager Setup

At app launch, create and retain one long-lived MetricManager. Start exactly one consumer task for metricReports and one for diagnosticReports.

Both properties expose nonthrowing AsyncSequence values:

  • metricReports: some AsyncSequence<MetricReport, Never>
  • diagnosticReports: some AsyncSequence<DiagnosticReport, Never>

Apple documents that concurrent consumers of one sequence can receive nondeterministic subsets. Fan out only after the single consumer receives and durably stores a report; delayed subscription can miss reports.

import MetricKit

@available(iOS 27.0, *)
final class MetricsService {
    private let manager = MetricManager()
    private var metricTask: Task<Void, Never>?
    private var diagnosticTask: Task<Void, Never>?

    func start(
        persistMetric: @escaping @Sendable (MetricReport) async -> Void,
        persistDiagnostic: @escaping @Sendable (DiagnosticReport) async -> Void
    ) {
        guard metricTask == nil, diagnosticTask == nil else { return }
        let manager = manager

        metricTask = Task {
            for await report in manager.metricReports {
                await persistMetric(report)
            }
        }

        diagnosticTask = Task {
            for await report in manager.diagnosticReports {
                await persistDiagnostic(report)
            }
        }
    }

    deinit {
        metricTask?.cancel()
        diagnosticTask?.cancel()
    }
}

The persistence closures are application-specific. Implement them with the durable-first workflow below rather than dropping, logging only, or directly uploading each report. If state-scoped metrics are needed, construct the manager with the documented init(enabledStateReportingDomains:) initializer and the required domains.

Receiving Metric Reports

MetricReport is Codable and Sendable. It describes an interval through:

  • timeRange: DateInterval
  • optional environment metadata
  • intervalEntries for full-day and shorter interval measurements
  • stateEntries for measurements associated with application states

Metric reports normally arrive on a daily cadence. Persist the complete report before extracting individual results.

For daily analysis, read the documented fullDayEntry and switch over its MetricResult values:

let entry = report.intervalEntries.fullDayEntry

for result in entry.values {
    switch result {
    case .hangTime(let metric):
        analyzeHangTime(metric)
    case .peakMemory(let metric):
        analyzePeakMemory(metric)
    case .timeToFirstDraw(let metric):
        analyzeLaunch(metric)
    case .signpostInterval(let metric):
        analyzeSignpost(metric)
    @unknown default:
        preserveUnknownMetric(result)
    }
}

Use @unknown default so a beta or future result does not make the ingestion pipeline brittle. Preserve the raw encoded report even when the current app does not understand a result.

Receiving Diagnostic Reports

DiagnosticReport is Codable and Sendable. It contains a timeRange, required environment metadata, and one DiagnosticResult.

Diagnostics are individual, event-based reports intended for prompt delivery when MetricKit produces them. Do not assume every crash, hang, or resource event generates a report; system sampling and eligibility still apply.

After durable storage, route the result explicitly:

switch report.result {
case .crash(let diagnostic):
    analyzeCrash(diagnostic)
case .hang(let diagnostic):
    analyzeHang(diagnostic)
case .cpuException(let diagnostic):
    analyzeCPUException(diagnostic)
case .diskWriteException(let diagnostic):
    analyzeDiskWrites(diagnostic)
case .appLaunch(let diagnostic):
    analyzeLaunch(diagnostic)
case .memoryException(let diagnostic):
    analyzeMemory(diagnostic)
@unknown default:
    preserveUnknownDiagnostic(report)
}

The iOS/iPadOS 27 diagnostic types are CrashDiagnostic, HangDiagnostic, CPUExceptionDiagnostic, DiskWriteExceptionDiagnostic, AppLaunchDiagnostic, and MemoryExceptionDiagnostic. The memory-exception case is new in iOS 27.

Useful fields include:

| Diagnostic | Important fields | |---|---| | CrashDiagnostic | callStackTree, exception type/code/reason, signal, virtual-memory region, termination category/reason | | HangDiagnostic | callStackTree, hangDuration | | CPUExceptionDiagnostic | callStackTree, totalCPUTime, totalSampledTime | | DiskWriteExceptionDiagnostic | callStackTree, totalBytesWritten | | AppLaunchDiagnostic | callStackTree, launchDuration | | MemoryExceptionDiagnostic | callStackTree |

Key Metric Results

Choose a small telemetry vocabulary that matches the investigation rather than exporting every result. Prioritize the relevant categories: responsiveness and terminations; runtime, CPU, memory, network, and storage; or launch, display/GPU, and custom intervals.

Aggregate by app version and environment metadata, compare distributions rather than single values, and correlate regressions with releases. Avoid treating a daily aggregate as a precise trace of one user action.

Load the Key Metric Result Catalog when mapping exact MetricResult cases into a parser or dashboard.

Call Stack Trees

The iOS 27 CallStackTree replaces MXCallStackTree. It is Codable and Sendable and exposes:

  • forEachFrame for frame traversal
  • callStackThreads for thread-oriented analysis
  • binaryInfo for image and binary metadata

Store the complete diagnostic report before flattening or symbolication. Preserve binary identifiers and offsets so server-side symbolication can use matching archives and dSYMs.

Custom Signpost Metrics

Create an OS log through the manager, then use mxSignpost for begin/end measurement:

let log = manager.logHandle(category: "ImagePipeline")

mxSignpost(.begin, log: log, name: "Decode")
await decodeImage()
mxSignpost(.end, log: log, name: "Decode")

MetricKit exposes the aggregate as MetricResult.signpostInterval. Do not search for a signpostMetrics array on MetricReport.

Use mxSignpost when MetricKit resource measurement is required. Apple documents that intervals created with OSSignposter and a MetricKit log handle do not populate the resource-measurement fields that mxSignpost provides.

Keep high-volume local tracing separate from the small set of stable production intervals used for MetricKit aggregation.

Durable Export and Upload

Treat report delivery as an at-least-once ingestion problem:

  1. Encode the complete MetricReport or DiagnosticReport with JSONEncoder.
  2. Atomically enqueue the bytes in an app-owned durable outbox.
  3. Record report type, schema version, app version, and a stable deduplication key.
  4. Acknowledge local processing only after the enqueue succeeds.
  5. Upload later with retry, backoff, batching, and retention limits.
  6. Mark the outbox item uploaded only after the server accepts it.
let data = try JSONEncoder().encode(report)
try await durableOutbox.enqueue(data, kind: .metric)

durableOutbox is an application-owned abstraction, not a MetricKit API. Do not perform a synchronous network upload inside the sequence consumer.

Durable local storage is the recovery mechanism for reports received through the modern sequences; do not make successful ingestion depend on an assumed modern backfill API.

Extended Launch Measurement

Use trackLaunchTask(id:onTrackingError:_:) on the manager for work that extends beyond time to first draw:

await manager.trackLaunchTask(
    id: "bootstrap-data",
    onTrackingError: { error in
        recordLaunchTrackingError(error)
    }
) {
    await bootstrapApplication()
}

The API is @MainActor and has synchronous and asynchronous overloads. The task closure's result and thrown error propagate to the caller; a MetricManager.LaunchTaskError is reported through onTrackingError without interrupting the tracked work. Results appear as MetricResult.extendedLaunch.

Use stable LaunchTaskID values and track only launch-critical work.

iOS 26 Compatibility

For an app that still deploys to iOS 26, use an availability boundary:

  • iOS/iPadOS 27: use MetricManager and consume both async report sequences.
  • iOS/iPadOS 26 and earlier supported releases: use MXMetricManager.shared, an MXMetricManagerSubscriber, and the legacy payload callbacks.

The legacy APIs remain the only documented branch with pastPayloads and pastDiagnosticPayloads. MXMetricManager is deprecated in iOS 27, so isolate it behind availability checks rather than mixing legacy payloads into the modern pipeline.

Load iOS 26 Compatibility for the full subscriber, legacy signpost, past-payload, and extended-launch patterns.

Xcode Organizer

Use Xcode Organizer to inspect Apple-aggregated production metrics, hangs, crashes, and regressions before building a custom backend. Use direct MetricKit ingestion when the product needs custom correlation, retention, alerting, or integration with an existing observability system.

Do not expect development-device runs to reproduce the population, cadence, or aggregation of production reports.

Scope Boundaries

| Task | Use instead | |---|---| | Reproduce a problem locally or record a detailed trace | debugging-instruments | | Diagnose retained objects or memory graph paths | ios-memgraph-analysis | | Tune SwiftUI invalidation, identity, or scrolling code | swiftui-performance | | Study structured EnergyKit impact data | energykit | | Design general logging and os_signpost strategy | swift-logging |

MetricKit identifies production symptoms and trends. Route the actual code fix to the skill that owns the affected subsystem.

Common Mistakes

| Mistake | Correction | |---|---| | Uploading directly in the sequence loop | Encode and enqueue locally first; upload asynchronously later. | | Assuming every diagnostic event produces a report | Treat diagnostics as sampled, system-produced evidence. | | Looking for pastPayloads on `MetricManag

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.1k
CategoryDevelopment
Updated3mo ago
Forks58

Languages

Python

Trust signals

86/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium1 info
metrickit — Universal Skill: Install & Safety Check | SkillAgent