virtual-dimensions
Use when creating, editing, previewing, or publishing Costory virtual dimensions (custom cost axes) with ordered CEL rules, leftover buckets, overlap/shadowing checks, or telemetry split-by-usage allocations. Call get_skill with skillId \"virtual-dimensions\" before create_virtual_dimension_draft or update_virtual_dimension_draft.
costory-io · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add costory-io/costory-finops-mcp-skills --skill virtual-dimensions技能说明
name: virtual-dimensions description: "Use when creating, editing, previewing, or publishing Costory virtual dimensions (custom cost axes) with ordered CEL rules, leftover buckets, overlap/shadowing checks, or telemetry split-by-usage allocations. Call get_skill with skillId "virtual-dimensions" before create_virtual_dimension_draft or update_virtual_dimension_draft."
Virtual Dimensions
A virtual dimension is a custom cost axis (e.g. "Environment", "Team", "Product line") built from ordered rules. Each rule has:
conditionCel— CEL filter selecting rows (e.g.cos_environment in ["prod"])allocation— where matched spend goes. Supports all types:dimensionValue,existingColumn,splitCost,telemetry(same shapes asgetreturns for a virtual dimension)
Rules are evaluated top-to-bottom; first match wins. A leftover rule catches everything else.
Edits happen on a draft. Publishing is explicit and triggers BigQuery refresh. Production is unchanged until publish_virtual_dimension.
When to Trigger
- Building a new custom cost axis (Environment, Team, Product line, …)
- Editing rules on an existing virtual dimension
- Previewing leftover %, breakdown, or rule overlap/shadowing
- Splitting shared cost by a usage metric (
telemetryallocation) - Publishing a draft after user confirmation
Auth
Write tools (create / update / publish) are Clerk-only — not available on the service route. Read tools work on both routes.
Several organizations: if get_context (or any tool) returns "Multiple organizations" with a list of slugs, do not pick one. Ask the user which org to use (from that list or list_organizations), then pass that slug to get_context and the following tool calls. If the user already named the org (e.g. "org acme"), use that slug directly.
Concepts
| Concept | Meaning |
|---|---|
| Draft vs published | Mutations touch the latest pending draft; published state stays live until publish |
| Draft persistence | preview_virtual_dimension_draft and virtual_dimension_overlap_matrix (when includeDraft: true) return draftPersisted: true when a pending draft exists, draftPersisted: false when analyzing published-only state in memory (not publishable). create_virtual_dimension_draft and update_virtual_dimension_draft persist only when validation passes — on success draftPersisted: true and draftValidation: { ok: true }; on failure nothing is saved (draftPersisted: false). publish_virtual_dimension requires a persisted pending draft — call update_virtual_dimension_draft for an existing virtualDimensionId (or create_virtual_dimension_draft for a brand-new VDIM) |
| Rule order | Earlier rules claim spend; later overlapping rules are shadowed |
| Leftovers | Spend not matched by any named rule — high leftover means add more rules |
| Leftover (MCP) | Auto catch-all returned as leftoverRule (not in rules). Do not include a catch-all in rules on create or update — duplicate leftovers cause ordering confusion. There is no leftover-label input on create/update — rename the leftover bucket in the web app |
| Rule ids | Create: saveVirtualDimensionDraft re-stamps all rule ids — response ids are authoritative. Update: preserves ids from input (including when seeding a draft from published state). Both: ids are sticky to logical rules — reorder by moving id + name + conditionCel + allocation together; attaching an id to a different condition silently mis-assigns spend |
| Tags | get returns tags (names) for both published and draft. Pass tagNames (strings) on create/update — not tag UUIDs |
values | Output-only — derived from rule allocations; do not send on create/update |
| Allocation shapes | dimensionValue: { allocationType: "dimensionValue", dimensionValue: "prod" }; existingColumn: { allocationType: "existingColumn", existingColumn: "cos_team" }; splitCost: { allocationType: "splitCost", reAllocationParams: { type: "custom", partitions: [{ label: "A", weight: 60 }, { label: "B", weight: 40 }] } } (weights sum to 100); telemetry: { allocationType: "telemetry", externalMetric: { provider, integrationId, metricName, aggregator, groupByFields: ["<split-by>"] }, mappingType: "mapping" | "regexMapping" | "identity", mappingParams: { mapping: { "key": "value" } }, regexTransformation: "..." } — discover externalMetric via list_metrics { includeExternal: true, search }. Do not set datasource on new reallocations (leftover stored rows may still have it — echo unchanged). mapping keys are metric value names (not cos_* dimensions); unmapped values → leftover. Echo non-dimensionValue allocations from get unchanged unless the user explicitly asks to edit advanced allocation behavior |
| CEL only | Always use conditionCel strings; never raw query-builder JSON |
| Unlabelled values | Use cos_environment == null in conditionCel (not is_null or string "null") |
| Declarative updates | update_virtual_dimension_draft takes the full desired rules array, not diffs |
name vs bqName | name is the display label (can change in drafts). bqName is the immutable BigQuery / CEL field name (e.g. virtual_environment) — set once at create_virtual_dimension_draft from the initial name and never updated, even after rename or publish. Read bqName from create/update/publish/get responses (or list_virtual_dimensions when resolving by name only) before groupBy / filterCel; never derive it from name. |
| Post-publish query | After publish, use returned bqName (not name) in query. computeStatus: REFRESHING = refresh job queued — poll get or list_virtual_dimensions until COMPLETED before querying; TO_REFRESH = draft promoted but refresh job queuing failed — retry publish_virtual_dimension or poll computeStatus until COMPLETED |