Skip to content
bitdrift Instrumentation

bitdrift Instrumentation Skill

Adds the bitdrift Capture SDK to an iOS, Android or React Native app and wires up logging, network monitoring, screen views and TTI correctly.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from bitdriftlabs/bd-skills.

$ npx skills add bitdriftlabs/bd-skills --skill bd-instrumentation

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/bd-instrumentation/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/bitdriftlabs/bd-skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/bd-instrumentation ~/.claude/skills/bd-instrumentation

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/bd-instrumentation/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Detects Android, iOS or React Native from files in the repo
  • Installs the Capture SDK or extends an existing integration
  • Independent instrumentation categories: logs, network, screen views, TTI, fields, spans
  • Nine-point validation report with concrete code fixes
  • Fetches live API details via the bd-docs skill

Instrumenting a mobile app for observability is the kind of task that is easy to do halfway: the SDK gets added, Logger.start() gets called, and six months later nobody can explain why sessions have no screen names in them. This official bitdrift skill turns that into a checklist an agent can actually follow.

It starts by detecting the target platform from real signals in the repository — build.gradle and AndroidManifest.xml for Android, .xcodeproj and Package.swift for iOS, a react-native dependency and metro.config.js for React Native — and asks which target you mean when a monorepo contains more than one. It then checks whether the Capture SDK is already present before touching anything, and reads a platform-specific reference for the install path or for the individual instrumentation categories: log forwarding, network monitoring, screen views, time-to-interactive, custom fields and spans. Each category is independent, so it can be used to extend an existing integration rather than only to bootstrap a new one.

The most useful part is the validation mode. Ask it to check an existing integration and it produces a PASS/FAIL/WARNING report against nine specific checks — SDK version, early initialisation, session strategy, network monitoring, screen tracking, TTI, crash reporter linkage with a session URL, entity ID and identity fields set after login, and dSYM or ProGuard mapping upload — with concrete code fixes for each failure.

It is designed to pair with bitdrift's bd-docs skill so API details are fetched live from the documentation rather than recalled from training data. Note the licence: bd-skills is published under PolyForm Shield 1.0.0, which is source-available rather than open source.

SKILL.md

The instructions your agent loads, as published by bitdrift.

SKILL.md

bitdrift Instrumentation

Guides integration of the bitdrift Capture SDK into mobile apps. The SDK logs everything locally on-device; the bitdrift control plane dynamically decides what to upload.

How this skill uses docs

Use $bd-docs to fetch live API details from docs.bitdrift.io at each step. The platform reference files indicate what to look up — $bd-docs handles the mechanics of discovery and fetching.

Workflow summary

Detect platform → Check if SDK is installed → Read platform reference → If new install: add dependency + Logger.start() → Add instrumentation categories the user needs.

Step 1 — Detect platform

Identify the target platform from the user's project:

SignalPlatform
build.gradle, build.gradle.kts, .kt, .java, AndroidManifest.xmlAndroid
.xcodeproj, .xcworkspace, Package.swift, Podfile, .swift, .m/.hiOS
package.json with react-native, metro.config.js, App.tsx/App.jsReact Native

If the project contains files for multiple platforms (e.g., both Android and React Native in a monorepo), ask the user which target to instrument.

Step 2 — Determine SDK status

Check whether the bitdrift Capture SDK is already installed by searching the project for:

PlatformSDK already present if you find…
Androidio.bitdrift:capture in build.gradle/build.gradle.kts, or import io.bitdrift.capture in source
iOScapture-ios in Package.swift or BitdriftCapture in Podfile, or import Capture in source
React Native@bitdrift/react-native in package.json, or import { init } from '@bitdrift/react-native' in source
Step 3 — Read the platform reference and proceed

Read the platform reference file, then follow the appropriate path:

PlatformReference file
Android (Kotlin/Java)references/android.md in this skill directory
iOS (Swift/Objective-C)references/ios.md in this skill directory
React Nativereferences/react-native.md in this skill directory

Each reference file has two sections:

  • New installation — Add the SDK dependency and call Logger.start(). Follow this when the SDK is not yet present. Once the SDK is running, proceed to the instrumentation categories below.
  • Instrumentation categories — Standalone enhancements (log forwarding, network monitoring, screen views, TTI, fields, spans, etc.). Each is independent — jump directly to whichever one the user needs. These apply whether the user just finished a new install or already had the SDK set up.
Validation checklist (all platforms)

When asked to validate an integration, check all items and produce a report with PASS/FAIL/WARNING per check, plus concrete code fixes for failures.

#Check
1SDK dependency present and up to date
2Logger initialized early in app lifecycle
3Session strategy configured
4Network monitoring active
5Screen tracking on every screen
6TTI tracked
7Crash reporter linked with session URL
8Entity ID set after login via setEntityID / setEntityId (iOS/Android only; enables bd entity targeting)
8aUser identity fields set after login via addField
9dSYM/ProGuard mapping upload configured (if applicable)
Install
Featured

Expo's official skill for building native-feeling screens: Apple HIG styling, semantic colors, SF Symbols, native controls, Reanimated, blur and liquid glass.

Vercel's React Native and Expo best-practices skill: prioritised rules for list performance, Reanimated animation, native navigation, UI patterns, state, rendering, monorepos and configuration, each with code examples.

Browse all skills →