skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
lytics/agent-skills51 installs

segment-manager

Segment CRUD, validation, and sizing operations. Use when the user wants to list, view, create, update, delete, validate, or size segments.

How do I install this agent skill?

npx skills add https://github.com/lytics/agent-skills --skill segment-manager
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides a secure interface for managing Lytics segments. It follows security best practices by using environment variables for authentication and implementing a mandatory confirmation gate for destructive write operations.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Segment Manager

Purpose

Full segment lifecycle management -- list, get, create, update, delete, validate FilterQL, and estimate segment size.

Environment

Requires authenticated API access. See ../references/auth.md for credential resolution.

API Endpoints

List Segments

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&kind=segment&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Query params: table, kind, valid, sizes

Get Segment

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}?sizes=true&inline=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Query params: sizes (include size data), inline (inline included segments)

Get Segment Ancestors

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}/ancestors" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Create Segment

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Segment Name",
    "slug_name": "segment_slug",
    "description": "What this segment represents",
    "segment_ql": "FILTER condition FROM user ALIAS segment_slug",
    "kind": "segment",
    "table": "user",
    "is_public": true,
    "tags": [],
    "save_hist": true
  }'

Update Segment

curl -s -X PUT "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... updated fields ... }'

Delete Segment

curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/${SEGMENT_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Validate FilterQL

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", visitct > 5) FROM user ALIAS test'

Returns 200 on valid, error message on invalid.

Estimate Segment Size (ad-hoc FilterQL)

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER condition FROM user'

Body is raw FilterQL text, not JSON.

Get Existing Segment Size

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Segment Field Info -- Audience Snapshot

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

Returns per-field analytics within a segment: value distributions, coverage rates, numeric stats, and histograms. Query params: fields (comma-delimited), limit (default 20, max 1000), table, cached. For detailed analysis, use the audience-snapshot skill.

Reevaluate Segment

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment/reevaluate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"id": "segment_id"}'

Segment Payload

Required fields for creation:

{
  "name": "Display Name",
  "slug_name": "url_friendly_slug",
  "description": "Human-readable description",
  "segment_ql": "FILTER ... FROM user ALIAS slug",
  "kind": "segment",
  "table": "user",
  "is_public": true,
  "save_hist": true
}

Optional fields:

{
  "tags": ["tag1", "tag2"],
  "groups": ["group_id"],
  "expires_at": "2025-12-31T00:00:00Z",
  "emit_trigger": false,
  "schedule_exit": false
}

Segment Kinds

KindDescriptionUse Case
segmentStandard audience segmentGeneral audience targeting
aspectBuilding block segmentReusable filter components
goalBusiness objectiveConversion tracking
listTemporal export listOne-time or recurring exports
conversionCampaign trackingAttribution measurement
metricMetric segmentAnalytics/reporting
managedSystem-managedInternal platform use
candidateDecisioning exclusionExclude from decisioning

Behavior

For Read Operations (list, get, size)

Execute immediately and display results.

For Write Operations (create, update, delete)

Use the confirmation-gate pattern:

  1. Build complete payload
  2. Show human-readable summary
  3. Show raw API payload
  4. Wait for user confirmation
  5. Execute on approval

Validation Flow

Before creating/updating a segment:

  1. Validate the FilterQL with POST /api/segment/validate
  2. If invalid, parse error and attempt to fix (max 3 retries)
  3. Once valid, estimate size with POST /api/segment/size
  4. Present validation + size results before proceeding

Error Handling

  • Invalid FilterQL: Parse the validation error, identify the issue, suggest fix
  • Slug conflict (409): Suggest alternative slug name
  • Empty segment (size 0): Warn user, suggest broadening criteria
  • Very large segment: Note the size and ask user to confirm intent

Dependencies

  • Uses: ../references/auth.md, ../references/api-client.md, ../references/confirmation-gate.md
  • References: ../references/filterql-grammar.md

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/lytics/agent-skills/segment-manager">View segment-manager on skillZs</a>