{"id":50149,"plugin_id":"plugin_asdk_app_6abf2061a1248191a70d61197a20542a","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:42:16.408Z","digest":"b516a96da67d3294f1d37dfc3430c92a86695ed448dd5fdcc465621024f973a4","against":null,"payload":{"description":"Designs Hive Analytics segment conditions, estimates the matching user count, saves the segment, and optionally\nextracts a point-in-time snapshot. It also lists existing segments/snapshots and refreshes snapshots. Follow\naxyl-analytics-common first.\n\nTRIGGER when:\n- The user asks to create a segment (for example, \"create a segment of paying iOS users\")\n- The user asks how many users meet certain conditions (simulation only, no save)\n- The user asks to list existing segments/snapshots or take or refresh a snapshot\n\nDO NOT TRIGGER when:\n- The request is a metric breakdown by dimension or a user ranking → axyl-drill-down-metrics\n- The request is to create chart, funnel, retention, or dashboard content → axyl-create-content\n- The request is only to send a push; this skill stops at segments and snapshots\n- The request is development work unrelated to analytics\n","included_files":[{"relative_path":"references/condition_patterns.md","size_in_bytes":9101},{"relative_path":"references/snapshot_policy.md","size_in_bytes":6467}],"name":"axyl-create-segment","skill_md_contents":"---\nname: axyl-create-segment\nmetadata:\n  version: \"1.0.0\"\ndescription: |\n  Designs Hive Analytics segment conditions, estimates the matching user count, saves the segment, and optionally\n  extracts a point-in-time snapshot. It also lists existing segments/snapshots and refreshes snapshots. Follow\n  axyl-analytics-common first.\n\n  TRIGGER when:\n  - The user asks to create a segment (for example, \"create a segment of paying iOS users\")\n  - The user asks how many users meet certain conditions (simulation only, no save)\n  - The user asks to list existing segments/snapshots or take or refresh a snapshot\n\n  DO NOT TRIGGER when:\n  - The request is a metric breakdown by dimension or a user ranking → axyl-drill-down-metrics\n  - The request is to create chart, funnel, retention, or dashboard content → axyl-create-content\n  - The request is only to send a push; this skill stops at segments and snapshots\n  - The request is development work unrelated to analytics\n---\n\n# axyl-create-segment\n\n> **CRITICAL — Always review the common rules in [axyl-analytics-common](../axyl-analytics-common/SKILL.md) first.**\n> **CRITICAL — `create_segment` and `create_segment_snapshot` are write operations. Never run them without WRITE_APPROVAL.**\n> **CRITICAL — Always show the estimated user count with `simulate_segment` before saving. Do not ask for approval without showing the count.**\n> **CRITICAL — Use only `list_segment_meta` results for condition property names and values (NO_GUESSING). A selectable value not in the metadata is rejected, but a wrong range threshold is not checked and can produce a segment matching no one.**\n> **CRITICAL — Take `segment_idx` and `snapshot_idx` only from upstream tool results. Do not guess them.**\n> **CRITICAL — Show the user only the condition summary (`summary`). Do not expose internal code values such as `value_range_type`, `date_type`, or `start_value` (the display rules in axyl-analytics-common).**\n\n---\n\n## Tools\n\n- **Schema (read):** `list_segment_meta`\n  → [list_segment_meta.md](../axyl-analytics-common/references/list_segment_meta.md)\n- **Verification (read):** `simulate_segment`\n  → [simulate_segment.md](../axyl-analytics-common/references/simulate_segment.md)\n- **Save (write):** `create_segment`\n  → [create_segment.md](../axyl-analytics-common/references/create_segment.md)\n- **Snapshot (write):** `create_segment_snapshot`\n  → [create_segment_snapshot.md](../axyl-analytics-common/references/create_segment_snapshot.md)\n- **Query (read):** `list_segment_snapshots`\n  → [list_segment_snapshots.md](../axyl-analytics-common/references/list_segment_snapshots.md)\n\nSegment tools need `org_idx` to verify access to the target project, but because segments are not workspace assets,\n`workspace_idx` is not needed. Follow Step 1-1: confirm `org_idx` with `list_organizations(company_cd, appid_group)` using the candidate project, then take\n`appid_group` and `game_name` from the **same row** of `list_projects(company_cd, org_idx)`.\n\n## Reference Documents\n\n- [Condition design patterns](references/condition_patterns.md) — examples of decomposing a natural-language request into `property_groups`\n- [Snapshot policy](references/snapshot_policy.md) — criteria for judging freshness and size, and the segment-to-snapshot 1:N structure\n\n---\n\n## Workflow\n\n### Prerequisite — Review the common rules\n\nPROJECT_ID_GATE, SCHEMA_FIRST (for new conditions), WRITE_APPROVAL, and NO_GUESSING from axyl-analytics-common apply.\nWorkspace selection does not apply, but pass every segment tool an `org_idx` whose access to the target project has been verified.\n\n### Phase 0 — Classify the request\n\n```\nSplit the request four ways.\n\nA. Create a segment from new conditions   → Phase 1 → 2 → 3 → optionally 4 → 5 if extracting\nB. Only want the user count (no save)     → Phase 1 → 2, then stop\nC. Take a snapshot of an existing segment → Phase 1 → 4 → 5\nD. List existing segments and snapshots  → Phase 1 (Step 1-1 only) → list_segment_snapshots, then stop\n```\n\nFor A or B, if the conditions are unclear, ask the user here. Do not proceed on a guess.\nFor decomposition examples, see [references/condition_patterns.md](references/condition_patterns.md).\n\n### Phase 1 — Gates and schema (axyl-analytics-common)\n\n```\nStep 1-1. PROJECT_ID_GATE       → confirm company_cd, then org_idx and appid_group / game_name\n                                  → list_projects for a candidate appid_group, then list_organizations(company_cd, appid_group):\n                                    one candidate → use it;\n                                    several → show them all and wait for the user's choice ⛔;\n                                    none → follow PROJECT_ID_GATE's \"No organization for the project\" ⛔\n                                  → list_projects(company_cd, org_idx): take appid_group and game_name\n                                    from the same row. If the project is not in them, return to organization selection\nStep 1-2. For A or B, SCHEMA_FIRST → list_segment_meta(company_cd, org_idx, appid_group)\n                                  → the usable property_category / property_name\n                                  → value_type (enum: a list of selectable values / range: a range input)\n                                  → period_yn (only Y properties can carry a period condition)\n```\n\nFor C or D, skip Step 1-2 because no new conditions are being designed. For D, call\n`list_segment_snapshots(company_cd, org_idx, appid_group)`, present each segment's condition summary and URL together\nwith each snapshot's status, age, user count when complete, and URL, then stop without requesting WRITE_APPROVAL.\n\nFor A or B, if the property you want is not in the metadata, that condition cannot be built. Propose an alternative\nproperty or stop.\n\n### Phase 2 — Simulation (required before saving)\n\n```\nStep 2-1. Convert the request into property_groups (using only property_names and values from the metadata)\nStep 2-2. Call simulate_segment — exactly once, with the conditions the user stated ⛔\nStep 2-3. Present the result to the user and stop\n            - estimated count / total count / proportion (%)\n            - conditions (the condition summary that will be saved)\n            - condition_details (which condition narrowed the scope)\nStep 2-4. If the count is zero, or looks too small or too large for the purpose\n            → **only propose** adjustments and wait for the user to choose ⛔\n            → if the user chooses an adjustment, call Step 2-2 again with those conditions (once)\n```\n\n> **Do not arbitrarily change the conditions and re-simulate.** Adjusting a threshold or period yourself because the count\n> seems low or high produces a different segment from the one the user asked for. Show the result as is\n> and ask \"Would you like to adjust the conditions?\" — the judgment is the user's.\n>\n> `user_proportion` is expressed in **percent (%)**. `0.0004` is 0.0004%, not 0.04%.\n> If the request is B (check the count), stop here — do not save.\n\n**Proposal format** (do not act on it; get a choice)\n\n```\nThe current conditions match N users. (X% of M total)\nWhich condition narrowed it: <grounded in condition_details>\n\nShall we proceed as is, or adjust the conditions?\n  A. Save as is\n  B. Relax the threshold (for example, at least 10 → at least 1)\n  C. Widen the period (for example, today → the last 7 days)\n  D. Remove a condition (for example, drop the OS condition)\n```\n\n- Ground each proposed adjustment in the condition that **actually narrowed the scope** in `condition_details`. Do not build it on a hunch.\n- Omit A when the count is zero — a zero-user segment is not saved.\n- If the count is excessive, propose the opposite — adding conditions or shortening the period.\n- Do not set thresholds yourself. Whether \"N users is too few\" depends on the purpose, so present the figure and leave the judgment.\n\n### Phase 3 — Save the segment (definition only)\n\n```\nStep 3-0. Duplicate check: list_segment_snapshots(company_cd, org_idx, appid_group)\n            → compare the normalized raw condition structure; if an equivalent segment exists, show its summary and url and let the user\n              choose to reuse it or save anyway\nStep 3-1. [WRITE_APPROVAL] Wait for explicit approval to save ⛔\n            (ask only after presenting the count and conditions from Phase 2)\nStep 3-2. Call create_segment → collect segment_idx\n            - title: a name that reveals the conditions (for example, \"iOS Chinese-language paying users\")\n            - use the default (\"\") for set_base_snapshot → saves the definition only, creates no snapshot\nStep 3-3. Show the user the returned conditions (summary sentence) and url (console link)\n            → POST_WRITE_LINK: use the url the tool gave, exactly as given (never assemble it yourself)\n```\n\n> A segment is only a **condition definition**. Up to this step, no target user set exists.\n> **Ask separately** whether to go on to Phase 4 and take a snapshot.\n\n### Phase 4 — Extract a snapshot (same for new and existing)\n\n```\nStep 4-1. For an existing segment, call list_segment_snapshots(company_cd, org_idx, appid_group)\n            → identify it from the normalized raw condition structure; use conditions[].summary only for display\n            → check the existing snapshots' job_status / snapshot_age_days / snapshot_user_cnt\n            → if a recent snapshot exists and the user did not explicitly ask for a new one, show its elapsed days and let\n              the user choose to reuse it or extract a new one (an explicit request for a new snapshot goes to Step 4-2)\nStep 4-2. [WRITE_APPROVAL] Wait for explicit approval: \"Shall we create a snapshot as of now?\" ⛔\n            - explain that a snapshot freezes the users who currently match these conditions\n            - even a segment just created in Phase 3 is asked again here, with no exception\nStep 4-3. create_segment_snapshot(company_cd, org_idx, segment_idx, title)\n            - title: make the point in time clear (for example, \"260730_logged_in_today\")\n            - before the call, note the segment's existing snapshots (from Step 4-1) to tell the new one apart later\n```\n\nFor the judgment criteria, see [references/snapshot_policy.md](references/snapshot_policy.md).\nIf the user does not want a snapshot, leave the segment definition and stop — Phase 4 alone can be redone later.\n\n### Phase 5 — Confirm completion\n\n```\nCheck that snapshot's job_status with list_segment_snapshots. The new snapshot is the one the call returned, or a snapshot\nwith the approved title that was not among the existing ones noted before the call. Never report an older snapshot's count\nor link as the new one; if none matches, treat it as \"not in the list\".\n(For a segment made from a user classification, give the user the returned url to check in the console instead.)\n  ├─ \"complete\" → return snapshot_idx / snapshot_user_cnt to the user\n  ├─ \"start\"    → extraction is in progress. Advise querying again shortly (do not re-extract)\n  └─ not in the list → right after the call, wait briefly and check once more (do not call create again);\n                       still absent → leave it pending and advise checking again later; retry only after\n                       service/operator confirmation (ask the user to confirm with the Analytics operator — no tool\n                       reports it) and a fresh WRITE_APPROVAL\n```\n\n- **POST_WRITE_LINK**: the tools return a `url` for both segments and snapshots. Include the link when reporting completion.\n  Right after `create_segment_snapshot` there may be no `snapshot_idx`, so the segment link may come back;\n  once extraction finishes, provide the snapshot `url` from `list_segment_snapshots`.\n- A snapshot does not complete immediately. Do not state a user count right after the return.\n- With `job_status=\"start\"`, `snapshot_table_name`/`snapshot_user_cnt` are still empty. Do not report a user count.\n\n---\n\n## Full Chain\n\n```\n[Classify the request] → PROJECT_ID_GATE\n  │\n  ├─ A. New segment\n  │     list_segment_meta (SCHEMA_FIRST)\n  │     → simulate_segment (once) → [present the count · confirm whether to adjust] ⟲ re-call only if the user chooses\n  │     → list_segment_snapshots (duplicate check: equivalent normalized raw conditions)\n  │     → [WRITE_APPROVAL: save] → create_segment (definition only)\n  │     → [optional, separately approved snapshot] create_segment_snapshot\n  │        → list_segment_snapshots (check job_status)\n  │\n  ├─ B. Count only\n  │     list_segment_meta (SCHEMA_FIRST) → simulate_segment → present the result and stop (no saving)\n  │\n  ├─ C. Snapshot of an existing segment\n  │     list_segment_snapshots (check conditions and freshness) → [WRITE_APPROVAL: snapshot]\n  │     → create_segment_snapshot → list_segment_snapshots (check job_status)\n  │\n  └─ D. List existing segments and snapshots\n        list_segment_snapshots → present condition summaries, status/count/age, and returned URLs → stop\n```\n\n---\n\n## Prohibited Behavior ❌\n\n| Situation | Prohibited behavior | Correct behavior |\n|------|----------|-----------|\n| Before saving | Calling `create_segment` without a simulation | Check the count with `simulate_segment` → WRITE_APPROVAL |\n| Property name or value unclear | Writing the condition on a guess | Confirm with `list_segment_meta` and use only the returned values |\n| Estimated count is zero | Saving anyway | Stop the save. Point to the bottleneck condition via `condition_details` and propose a redesign |\n| Count is low or high | Arbitrarily changing conditions and re-simulating | Present the result and get a choice: \"Would you like to adjust the conditions?\" |\n| Adjusting conditions | Changing a threshold or period without user confirmation | Present the change, get approval, then re-call once with those conditions |\n| Displaying a proportion | Converting `0.0004` to \"0.04%\" | Write the value as `%` as given (0.0004%) |\n| Choosing a segment | Judging the target from the name, description, or localized `summary` alone | Match the normalized raw condition structure; use `summary` only for display |\n| `segment_idx` | Guessing or inventing it | Use the `create_segment` return value or a `list_segment_snapshots` result |\n| Old snapshot | Using it without checking the elapsed days | Check `snapshot_age_days` and propose a refresh if needed |\n| Right after a snapshot | Reporting a definite user count | Report the count after confirming `job_status='complete'` |\n| Unconfirmed snapshot | Passing \"in progress\" off when it is not in the list, declaring failure from an immediate empty result, or re-extracting because it is not visible yet | Report whether it is `job_status='start'` or absent; after a request, re-check once and leave an absent result pending. Retry only after service/operator confirmation that the previous request cannot create a snapshot, plus fresh WRITE_APPROVAL |\n| After saving a segment | Extracting a snapshot too, without approval | Get separate approval for the snapshot in Phase 4 |\n| User-facing display | Exposing raw values such as `value_range_type` or `start_value` | Display the condition summary (`summary`) sentence |\n| After saving or extracting | Reporting only `segment_idx` with no link | Return the `url` the tool gave alongside (POST_WRITE_LINK) |\n| Links | Assembling the URL yourself | Use the tool's returned `url` as is |\n| Saving tokens | Using `with_labels=false` for a user-facing query | Keep `with_labels` at its default (true) — turning it off leaves labels and summaries empty, with only raw values |\n| Period condition | Specifying `date_type` on a `period_yn=\"N\"` property | Explain that the property does not support a period, let the user choose whether to remove it or change the property, then re-simulate the chosen conditions |\n\n---\n\n## Exception Handling\n\n| Situation | Response |\n|------|------|\n| The property you want is not in the metadata | Propose an alternative property, or explain that \"a segment cannot be built with that condition\" and stop |\n| A condition is rejected (property, value, or period) | Do not substitute values or drop conditions yourself. Relay the server's message, recheck the available properties and values with `list_segment_meta`, let the user choose, run `simulate_segment` with the chosen conditions, and obtain WRITE_APPROVAL again before saving |\n| Simulated count is zero | Do not save. **Propose** relaxing conditions or widening the period **and get a choice** (do not re-call arbitrarily) |\n| Simulated count is excessive | State the size and **propose** adding conditions or shortening the period. Do not change conditions without approval |\n| `condition_details` is an empty list | Only the detail query failed. The estimated count is still valid, so proceed with it |\n| `snapshots` is an empty list | No snapshot yet. Right after an extraction request, re-check once before concluding; if none was requested, offer to extract. Never re-call `create_segment_snapshot` while unsure |\n| `job_status=\"start\"` | Extraction is in progress. Advise querying again shortly. Do not report a count or re-extract |\n| No condition labels | The property metadata query failed. Explain with the raw condition values, or interpret them yourself with `list_segment_meta` |\n| `create_segment_snapshot` is rejected for the chosen segment | Relay the server's message and reconfirm the segment with `list_segment_snapshots`; if it no longer exists, propose creating a new one with `create_segment` |\n| `create_segment` fails, or the session expires during the call | The segment may have been saved. Before calling again, check `list_segment_snapshots` for a segment with equivalent conditions that was not in the Step 3-0 list (an equivalent segment that already existed does not count); save again only if none exists, with fresh WRITE_APPROVAL |\n| Not connected to the Hive Axyl MCP server (first install, never signed in), or the sign-in session expired | Apply MCP_CONNECTION_GATE in axyl-analytics-common. Cannot retry without user action |\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}