跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

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 as get returns 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 (telemetry allocation)
  • 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

ConceptMeaning
Draft vs publishedMutations touch the latest pending draft; published state stays live until publish
Draft persistencepreview_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 orderEarlier rules claim spend; later overlapping rules are shadowed
LeftoversSpend 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 idsCreate: 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
Tagsget returns tags (names) for both published and draft. Pass tagNames (strings) on create/update — not tag UUIDs
valuesOutput-only — derived from rule allocations; do not send on create/update
Allocation shapesdimensionValue: { 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 onlyAlways use conditionCel strings; never raw query-builder JSON
Unlabelled valuesUse cos_environment == null in conditionCel (not is_null or string "null")
Declarative updatesupdate_virtual_dimension_draft takes the full desired rules array, not diffs
name vs bqNamename 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 queryAfter 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

Strategy approval ≠

阅读完整来源 ↗