Skip to content
VEKTIS

vektis-discover

vektis-discover reads your codebase and finds every existing analytics-SDK call. It presents them as a candidate list you review in chat, then writes the approved list to .vektis/discover-output.json for vektis-instrument to consume.

Terminal window
claude /vektis-discover

This skill is read-only. It never modifies your source code. The only things it writes are .vektis/discover-output.json (atomically, on your done command) and a one-line append to .gitignore if .vektis/ isn’t already ignored.

When to use this skill

Section titled “When to use this skill”
You’re in this situationUse this skill
First time setting up VEKTIS, or major codebase restructurevektis-discover
You want to set up VEKTIS end-to-end in one go (install + discover + instrument)vektis-bootstrap
Periodic re-scan after shipping a release with new analytics callsvektis-update

What it detects

Section titled “What it detects”

The skill scans for these analytics SDKs:

SDKWhat’s detectedWhat’s skipped
Mixpanelmixpanel.track(...)mixpanel.identify, mixpanel.alias, mixpanel.people.set
Segmentanalytics.track(...), analytics.page(...)analytics.identify, analytics.alias, analytics.group
Amplitudeamplitude.track(...), amplitude.logEvent(...)amplitude.setUserId, amplitude.setUserProperties
PostHogposthog.capture(...)posthog.identify, posthog.reset, posthog.alias
GA4gtag('event', ...)gtag('config', ...), gtag('set', ...)

Identity / lifecycle calls are intentionally skipped — they aren’t feature-usage events.

The skill also covers common variants of each pattern: bracket notation (mixpanel["track"](...)), aliased imports (import mp from 'mixpanel-browser'; mp.track(...)), destructured calls (const { track } = mixpanel; track(...)), wrapper helpers, and multi-line calls.

What it walks through

Section titled “What it walks through”

  1. Pre-flight. Confirms you’re at a project root (looks for package.json, index.html, or framework config files). Refuses to run inside the VEKTIS source tree.

  2. Sweep. Walks src/, app/, pages/, components/, lib/, plus top-level project files. Skips node_modules/, build output (.next/, dist/, etc.), tests (*.spec.*, *.test.*, e2e/), source maps, and anything matched by your .gitignore. On large monorepos, pass --scope <path> to narrow the scan.

  3. Build candidates. For each detected SDK call, the skill normalizes the event name to a feature_id (lowercase, hyphenated, max 200 characters), heuristically picks a value type (count, percentage, duration, activity, currency), and records every file and line where the call appears as an insertion point.

  4. Review table. Renders a numbered markdown table in chat. You drive it with these commands:

    CommandWhat it does
    approve allAccept every row
    reject N or reject N,M,...Drop rows
    edit N feature_id=...Change a row’s feature_id
    edit N value_type=count|percentage|duration|activity|currencyChange the value type
    edit N title=...Change the human-readable title
    cancelExit without writing
    doneWrite the output file and finish

  5. Atomic write. When you type done, the skill writes .vektis/discover-output.json (a temp file then a rename — partial state is impossible) and idempotently appends .vektis/ to your .gitignore if it’s not already there.

Value-type heuristics

Section titled “Value-type heuristics”

The skill upgrades the default count to a more specific type when the signal is strong:

Pattern in your codeValue type chosenWhat gets written to metric_config
Two events sharing a stem with started + completed (e.g., checkout-started + checkout-completed)duration{ start_action, end_action }
Two events with started + succeeded/failed/completed semanticspercentage{ numerator_action, denominator_action }
Page-view calls — analytics.page(...) (Segment) or gtag('event', 'page_view', ...) (GA4)activitynull
Event names like dashboard_viewed, feature_seen, page_viewactivitynull
Event names like purchase, subscription_created, payment_completedcurrencynull
Anything elsecount{ action: '<feature_id>' }

When the skill upgrades two events to a paired duration or percentage candidate, the original two events disappear from the list — they’re now represented by the single paired row with two insertion points (one for the start/numerator, one for the end/denominator).

You can override any heuristic in chat with edit N value_type=.... See Metric Value Types for the full reference.

What gets skipped silently

Section titled “What gets skipped silently”
  • Calls with non-string first arguments — variables, expressions, or template literals can’t be slugged into a stable feature_id. The skill skips these. If you want them tracked, refactor to a string literal or call vektis.track(...) directly in your code.
  • Empty event names — mixpanel.track('') is dropped.
  • Already-instrumented calls — if a vektis.track('feature.used', { feature_id: 'X' }) already exists for a feature, the corresponding SDK call doesn’t re-surface as a candidate.

Re-running the skill

Section titled “Re-running the skill”

If .vektis/discover-output.json already exists when you launch the skill, you’ll see a prompt:

Existing .vektis/discover-output.json found (generated <timestamp>, N candidates).


  [1] Overwrite (re-scan from scratch — replaces the file on `done`)
  [2] Run /vektis-update instead (delta-only — only NEW features since last run)
  [3] Cancel

Most of the time, you want option 2 — that’s what vektis-update is for. Pick option 1 only if you want a fresh full sweep.

Empty state

Section titled “Empty state”

If your codebase has no analytics SDK calls, the skill exits cleanly with:

No analytics SDK calls detected in this codebase.

This isn’t an error — it just means there’s nothing for the skill to work with. Two ways forward:

  1. Run vektis-bootstrap if you haven’t installed the SDK yet — it’ll set up the SDK first and then route you back here.
  2. Add Dev Items manually in the VEKTIS dashboard, call vektis.track('feature.used', { feature_id: 'your-id' }) in your code, then run vektis-update to find them.

Output file shape

Section titled “Output file shape”

.vektis/discover-output.json is a stable contract consumed by other skills. The shape is documented in vektis-instrument. You don’t need to read or edit it by hand — vektis-instrument and vektis-update handle it for you.

Flags

Section titled “Flags”
  • --scope <path> — narrow the scan to a subdirectory. Useful for monorepos where you only want to instrument one app.

What this skill does NOT do

Section titled “What this skill does NOT do”
  • Modify any source file. (That’s vektis-instrument.)
  • Create Dev Items in the VEKTIS dashboard. (Also vektis-instrument.)
  • Authenticate with VEKTIS. The discover skill is purely local — it doesn’t need credentials.
  • Detect features that don’t already have an analytics SDK call. v1 covers existing-SDK detection; inferring features from click handlers without prior tracking is a v1.5 follow-up.
  • Scan iOS, Android, or Python codebases — v1 is web frontend only.
Section titled “Related”