home / skills / yelmuratoff / agent_sync / analytics

analytics skill

safe

This skill helps you manage analytics events with type-safe YAML definitions, generating code and validating changes before commits.

npx playbooks add skill yelmuratoff/agent_sync --skill analytics

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.6 KB

---
name: analytics
description: When adding, changing, validating, or using analytics events generated by `analytics_gen` (YAML as SSOT).
---

# Analytics (analytics_gen, YAML as SSOT)

## When to use

- Adding a new event for a feature or flow.
- Changing event parameters or event names.
- Validating analytics changes before a PR/commit.
- Instrumenting a BLoC/UI with type-safe analytics calls.

## Steps

### 1) Define events in YAML

Create or update `mobile/events/<domain>.yaml`.

Example:

```yaml
orders:
  screen_opened:
    description: User opened the orders screen.
    event_name: "Orders: Screen Opened"

  filter_applied:
    description: User applied a filter on the orders list.
    event_name: "Orders: Filter Applied"
    parameters:
      filter_type: string
      has_results: bool
      applied_count: int?
```

Rules of thumb:

- YAML keys are `snake_case`.
- Prefer required parameters; use optional (`?`) only when data can truly be missing.
- Deprecate with `deprecated: true` rather than deleting.

### 2) Generate code and docs

```bash
dart run analytics_gen:generate --docs --exports
```

### 3) Validate before commit

```bash
dart run analytics_gen:generate --validate-only
```

### 4) Use generated methods (no manual event strings)

```dart
analytics.logOrdersScreenOpened();

analytics.logOrdersFilterApplied(
  filterType: 'status',
  hasResults: true,
  appliedCount: 2,
);
```

### 5) Where to log

Prefer logging at the orchestration layer:

- BLoC event handlers (user intent → side effects)
- scopes/controllers that represent user actions

Avoid logging inside low-level clients/datasources.

Overview

This skill helps add, change, validate, and use analytics events defined as YAML single source-of-truth and generated into type-safe client code. It ensures event definitions are consistent, documented, and consumable from application layers without embedding raw strings. The workflow covers YAML definition, code/docs generation, pre-commit validation, and runtime usage patterns.

How this skill works

You declare analytics events and parameters in domain YAML files. A generator turns those YAML definitions into typed methods and documentation, and provides a validation mode to catch issues before commits. The produced methods are called from orchestration layers so analytics remain consistent and refactor-safe.

When to use it

Adding a new analytics event for a feature or user flow.
Changing event names or parameter shapes that affect telemetry.
Validating analytics definitions before a PR or commit.
Instrumenting BLoC, controllers, or UI orchestration with type-safe calls.
Deprecating events without deleting historical definitions.

Best practices

Keep YAML keys snake_case and readable; use clear descriptions for each event.
Prefer required parameters; mark truly optional values with an explicit optional marker.
Deprecate events with a flag instead of deleting to preserve historical integrity.
Log from orchestration layers (BLoC, controllers, scopes), not low-level clients or data sources.
Run the generator with validation before committing to catch schema and naming issues.

Example use cases

Add an orders domain YAML file to declare screen_opened and filter_applied events.
Change a parameter type (e.g., int → string) and validate the change with a pre-commit generation check.
Instrument a BLoC event handler to call the generated analytics.log... method on user actions.
Generate documentation and exports to keep product and analytics teams aligned on telemetry.
Deprecate an event in YAML rather than removing it to avoid breaking historical associations.

FAQ

How do I generate code and docs?

Run the generator with docs and exports flags to produce typed methods and documentation artifacts.

Where should I call generated analytics methods?

Call them from orchestration layers like BLoC event handlers or controllers that represent user actions, not inside low-level clients or datasources.