Skip to main content
skill CX Codex

add-geolocation — Claude Code skill: what it does, how to install

The add-geolocation skill sets up background GPS tracking with durable storage and Dataverse sync in a mobile app. The /add-native geolocation command invokes it.

MIT ★ 1,167 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add microsoft/power-platform-skills
/plugin install mobile-app@power-platform-skills
Open on GitHub

What add-geolocation does

The skill checks that the project already includes @microsoft/power-apps-native-bglocation and that Dataverse has the msdyn_locationrecords table with the required columns. It then creates or updates src/native/geolocation.ts, using geoService and BgLocationClient. Screens should import this wrapper rather than the package itself.

Tracking runs in the background, and its configuration requires trackInBackground and persistAcrossRestarts. Authentication uses MSAL. The target table and mapped fields must pass verification first; if the table or a required column is missing, the skill stops. It does not install packages or change native configuration. For a single foreground coordinate read, use /add-native location instead.

What it helps with

  • add background GPS tracking to a mobile app
  • keep location data across app restarts
  • send tracking data to Dataverse
  • check the Dataverse table and columns for location records

Example prompts for the agent

  • Add background GPS tracking to this app with /add-native geolocation.
  • Set up background location tracking and Dataverse sync using /add-native location-tracking.
  • Configure @microsoft/power-apps-native-bglocation for background tracking with /add-native background-location.

How to install add-geolocation

1Plugin marketplace

/plugin marketplace add microsoft/power-platform-skills
/plugin install mobile-app@power-platform-skills

This installs the whole mobile-app plugin with all its skills

2Skills CLI (Vercel)

npx skills add microsoft/power-platform-skills --skill add-geolocation -a claude-code

3Manually: put the files in place

~/.claude/skills/add-geolocation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/add-geolocation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about add-geolocation

How do I install add-geolocation in Claude Code?

Add the marketplace with /plugin marketplace add microsoft/power-platform-skills, then install the plugin with /plugin install mobile-app@power-platform-skills.

What does add-geolocation do?

It configures background GPS tracking, durable storage, and Dataverse sync for a mobile app. The /add-native command invokes the skill.

What must be in place for Dataverse location tracking?

The project must already include @microsoft/power-apps-native-bglocation, and Dataverse must have the msdyn_locationrecords table with the required columns. The skill checks these before changing src/native/geolocation.ts.

Source text

SKILL.md · MIT
---
name: add-geolocation
description: Internal implementation skill invoked by /add-native for native background GPS tracking with durable storage and Dataverse sync using @microsoft/power-apps-native-bglocation.
user-invocable: false
disable-model-invocation: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion
model: sonnet
---

**Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** - read first.

**Working directory:** before any project read or command, execute
[native-artifact-compatibility.md Step 0](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md#0-bind-every-operation-to-the-app-root).
Inherit `/add-native`'s resolved absolute `working_dir`; bind every shell call and
file tool to it, even when this helper starts from another directory.

# Add Geolocation

Internal helper for `/add-native geolocation`, `/add-native location-tracking`, `/add-native background-location`, `/add-native gps-tracking`, and `/add-native @microsoft/power-apps-native-bglocation`.

Use this only for continuous/background GPS tracking with native durable storage and inline Dataverse upload. For a single foreground coordinate read, use `/add-native location` (`expo-location`) instead.

Hard rules:
- Auth is MSAL-only. Do not expose OneAuth or an auth selector.
- Use `geoService(dataSource, app_id)` and `BgLocationClient`.
- Do not use `GeolocationExtension`, HostingSDK, PCF, Launch URI, or CordovaV2 bridge paths.
- Do not install packages or edit native config.
- The control is not usable until its Dataverse target table and mapped columns are verified.

## 1. Verify app and package

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f app.config.js && test -f power.config.json && test -f package.json && test -d src || { echo "BLOCKED: working_dir is not an initialized app" >&2; exit 1; }
node -e "const p=require('./package.json'); const m='@microsoft/power-apps-native-bglocation'; if (!p.dependencies?.[m]) { console.error('MISSING: ' + m); process.exit(1); } console.log('OK: geolocation package present');"
```

If either check fails, stop. The template/app must already ship the native package.

## 2. Verify the Dataverse target table first

This control uses the package default Dataverse entity set:

```text
msdyn_locationrecords
```

Do not ask the user for a table name and do not invent a custom table. `msdyn_locationrecords` must already exist before the control can be used.

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
ENV_JSON=$(node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$(node -e "console.log(require('./power.config.json').environmentId)")")
ENV_URL=$(node -e "const j=JSON.parse(process.argv[1]); process.stdout.write(j.environmentUrl || '')" "$ENV_JSON")

TABLE="msdyn_locationrecords"
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "$ENV_URL" GET \
  "EntityDefinitions?\$filter=EntitySetName eq '$TABLE'&\$select=LogicalName,EntitySetName"
```

Required result:
- One row returned: capture `LogicalName` and verify columns.
- Empty `value: []`: stop. Mark `BLOCKED (target table missing)`. Do not create the table, do not route to `/add-dataverse`, and do not report the control as usable. Tell the user to run the geolocation-control table provisioning/setup mechanism, then re-run `/add-native geolocation`.
- Auth/environment error: stop. Mark `UNVERIFIED (target table not checked)`. Do not report the control as usable.

When the table exists, verify every mapped column exists:

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" "$ENV_URL" GET \
  "EntityDefinitions(LogicalName='<logicalName>')/Attributes?\$select=LogicalName,AttributeType"
```

Required default `fieldMap` columns from the package README:

```text
msdyn_locationrecordid, msdyn_appid, msdyn_latitude, msdyn_longitude,
msdyn_altitude, msdyn_accuracy, msdyn_heading, msdyn_speed, msdyn_timestamp
```

If any active `fieldMap` column is missing, stop. Mark `BLOCKED (target columns missing)` and tell the user to fix the control table through the geolocation-control table provisioning/setup mechanism.

## 2a. Reconcile requested artifacts

Read and execute [native-artifact-compatibility.md](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md)
Steps 1–3 for the geolocation row before any writes or reuse. Inherit the current
approval/mode from `/add-native`; do not repeat a valid scoped approval.
Inspect `src/native/geolocation.ts` for all requested tracking/status/location
exports, `GeoTrackingTarget`, MSAL-only `geoService`/`BgLocationClient`, required
`connectionUrl`/`trackInBackground`/`persistAcrossRestarts`, durable storage, and
Dataverse sync. Reuse Step 2's verified `msdyn_locationrecords` columns; one-shot
location or a wrapper targeting another table is not compatible. An incompatible
artifact outside approval returns `NEEDS_CONTEXT` to the owner, or asks standalone;
missing table/columns remain `BLOCKED`, never a usable-control success.

## 3. Write `src/native/geolocation.ts`

Apply Step 2a's decision for `src/native/geolocation.ts`: create when requested
and missing, reuse unchanged only if compatible, or make only the approved scoped
update. Preserve custom code, exports, and callers; do not overwrite from the
example. Screens import this wrapper, not the package directly.

The target config must require the README's two tracking flags:
- `trackInBackground: boolean`
- `persistAcrossRestarts: boolean`

```ts
// src/native/geolocation.ts
import {
  geoService,
  BgLocationClient,
  AuthMethod,
  ConnectionType,
} from '@microsoft/power-apps-native-bglocation';
import type {
  DataverseDataSource,
  LocationData,
  PermissionStatus,
} from '@microsoft/power-apps-native-bglocation';

export type { LocationData, PermissionStatus } from '@microsoft/power-apps-native-bglocation';

export type GeoTrackingTarget = Omit<DataverseDataSource, 'authMethod' | 'connectionType'>;

export type GeoResult<T> =
  | { ok: true; value: T }
  | {
      ok: false;
      reason: 'NATIVE_MODULE_MISSING' | 'PERMISSION_DENIED' | 'TRACKING_FAILED';
      message?: string;
    };

let activeClient: BgLocationClient | null = null;

function client(): BgLocationClient {
  return activeClient ?? new BgLocationClient();
}

function dataSource(target: GeoTrackingTarget): DataverseDataSource {
  return {
    ...target,
    authMethod: AuthMethod.MSAL,
    connectionType: ConnectionType.Dataverse,
  };
}

function fail(error: unknown): Extract<GeoResult<never>, { ok: false }> {
  const message = error instanceof Error ? error.message : String(error);
  if (/native|module|not.*link|undefined is not an object|null is not an object/i.test(message)) {
    return { ok: false, reason: 'NATIVE_MODULE_MISSING', message };
  }
  if (/permission|denied|authoriz|not granted/i.test(message)) {
    return { ok: false, reason: 'PERMISSION_DENIED', message };
  }
  return { ok: false, reason: 'TRACKING_FAILED', message };
}

export async function startTracking(
  app_id: string,
  target: GeoTrackingTarget,
): Promise<GeoResult<void>> {
  try {
    activeClient = geoService(dataSource(target), app_id);
    await activeClient.startTracking();
    return { ok: true, value: undefined };
  } catch (error) {
    activeClient = null;
    return fail(error);
  }
}

export async function stopTracking(): Promise<GeoResult<void>> {
  try {
    await client().stopTracking();
    activeClient = null;
    return { ok: true, value: undefined };
  } catch (error) {
    return fail(error);
  }
}

export async function isTracking(): Promise<GeoResult<boolean>> {
  try {
    return { ok: true, value: await client().isTracking() };
  } catch (error) {
    return fail(error);
  }
}

export async function getPermissionStatus(): Promise<GeoResult<PermissionStatus>> {
  try {
    return { ok: true, value: await client().getPermissionStatus() };
  } catch (error) {
    return fail(error);
  }
}

export async function getCurrentLocation(): Promise<GeoResult<LocationData>> {
  try {
    return { ok: true, value: await client().getCurrentLocation() };
  } catch (error) {
    return fail(error);
  }
}
```

## 4. Usage shape

Integration guidance for the owner; do not edit screens in this helper.

Screens must pass `connectionUrl`, `trackInBackground`, and `persistAcrossRestarts`. Do not pass `tableName` or `fieldMap`; the control uses the default `msdyn_locationrecords` table and default `msdyn_*` field map. `intervalMs`, `distanceFilterMeters`, and `notification` are optional.

```ts
const target: GeoTrackingTarget = {
  connectionUrl: 'https://org.crm.dynamics.com',
  trackInBackground: true,
  persistAcrossRestarts: false,
};

await startTracking('my-wrap-app', target);
```

## 5. Type-check and summary

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npx --no-install tsc --noEmit
```

Execute the shared compatibility contract's Step 4 after type-checking. Recheck
all requested tracking APIs/flags, MSAL auth, durable storage/sync, and failure
paths. Type-check success alone is insufficient; do not fix screen/generated
files. Only after the requested artifact contract, table + columns, and
TypeScript all pass, return the shared compatibility result and actual
created/updated/reused paths before reporting:

```text
Geolocation status : READY
Package present    : @microsoft/power-apps-native-bglocation
Wrapper            : src/native/geolocation.ts
Required config    : connectionUrl, trackInBackground, persistAcrossRestarts
Auth               : MSAL only
Target table       : <TABLE> verified
Native config      : not changed
```

If table verification failed, report `BLOCKED` or `UNVERIFIED` instead and do not update `memory-bank.md` as if the control is ready.

© Microsoft · MIT · microsoft/power-platform-skills

Similar skills

All skills for Mobile →

From the same set157

The whole set →
add-pdf-viewer add-pdf-viewer configures a native PDF viewer wrapper for HTTPS links and file:// URIs in Power Platform mobile projects. CX Codex +1 ★ 1,167repo stars add-pen-input The add-pen-input skill creates or checks a wrapper for handwriting and signature capture in a mobile app. /add-native routes pen, ink, drawing, and handwriting requests to it. CX Codex +1 ★ 1,167repo stars canvas-app-planner canvas-app-planner is a Microsoft subagent for Claude Code that turns approved Canvas App edits into implementation contracts for each screen while preserving existing logic and layout. CX Codex ★ 1,167repo stars assemble-ppmplugin assemble-ppmplugin is a Claude Code skill that assembles a .ppmplugin bundle from a manifest and Android/iOS binaries, validates them, and packages the result. It runs after /generate-ppmplugin-manifest and build skills. CX Codex +1 ★ 1,167repo stars diagnose-deployment diagnose-deployment is a Claude Code skill that finds Power Pages upload and Dataverse solution import errors. Run it to investigate a failed deployment or ask for fixes to detected issues. CX Codex +1 ★ 1,167repo stars assign-offline-profile assign-offline-profile binds users and teams to a Dataverse Mobile Offline Profile so mobile apps can download and sync offline records. CX Codex +1 ★ 1,167repo stars canvas-app Create or revise a Power Apps Canvas App with Canvas Authoring MCP. The skill covers screen changes, responsive layouts, and compile-error fixes. CX Codex +1 ★ 1,167repo stars set-app-registration-native set-app-registration-native wires a Power Apps Wrap mobile app to an Entra ID app registration by writing auth.config.json. Discovers existing registrations in the tenant and checks API permissions. CX Codex +1 ★ 1,167repo stars

Project sponsors

Companies that keep this analytics open