create-yss-spec 3.5.0 → 3.5.3

package/template/.codex/skills/data-analytics/skills/market-sizing/SKILL.md

@@ -1,106 +0,0 @@
----
-name: market-sizing
-description: "Estimate TAM/SAM/SOM or another opportunity size with explicit assumptions, sensitivity and uncertainty."
----
-
-# Market Sizing
-
-Use this skill to produce a defensible estimate of a market or opportunity from connected context, public sources, transparent assumptions, and auditable calculations. The job is to define the market, choose a sound sizing method, distinguish evidence from assumptions, test sensitivity, and state what would most improve confidence.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-### Source Discovery And Verification
-
-Use the relevant semantic layer first when one exists. Treat it as the starting map for candidate metrics, tables, joins, filters, caveats, source precedence, and known conflicts.
-
-Do not stop at the semantic layer or the first plausible source. Search across the relevant available company source lanes, including structured data or data warehouses, dashboards, company docs, team communication, notebooks, code repositories, and other connected company knowledge or data that could change the answer.
-
-For source-backed analytical work, always verify through live source reads. When the answer depends on data, run fresh data queries against the available structured-data sources before drawing conclusions, even when the semantic layer already names likely tables or definitions.
-
-Use the combined evidence to determine which source controls the answer, note meaningful disagreements, and state why the selected source is authoritative.
-
-### Source Access Guardrail
-
-Before querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.
-
-If a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.
-
-If the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.
-
-Clarify with the user when a missing input would materially change the estimate or recommendation. Otherwise make a reasonable assumption, state it, and proceed.
-
-## Workflow
-
-### 1. Frame The Market Or Opportunity
-
-Define the market or opportunity boundary before estimating:
-
-- What is being sized, for example a product category, workflow, problem, use case, or category of activity.
-- Where and when it applies, for example geography, segment scope, time horizon, or market maturity.
-- Who or what counts as part of the market, for example the relevant population, unit of demand, transaction type, or included activity.
-- How the opportunity is measured, for example spend, revenue, volume, value created, or another unit that fits the question.
-- What kind of sizing answer the user needs, for example TAM/SAM/SOM, market entry, expansion upside, spend pool, revenue pool, population count, or unit volume.
-
-### 2. Choose A Starting Sizing Approach And Inputs
-
-Pick the simplest sound sizing approach for the question, then sketch the calculation chain and the major inputs the estimate will depend on.
-
-A top-down model works when reliable aggregate market data exists; a bottom-up model works when the market can be built from observable units and assumptions; a value-based model works when the estimate should start from the value created rather than a published market total. Use a mixed approach only when cross-checking would materially improve confidence. If more than one approach fits, briefly explain which one you trust most and why.
-
-Expect the first approach to change if source checks show that another model would be more defensible.
-
-### 3. Gather Sources For The Inputs
-
-Choose sources based on the inputs the estimate depends on most.
-
-Start with user-named sources when provided. Then use the strongest available evidence for each major input from the starting approach. Use `~~structured_data` when an input should come from the user's data warehouse or another structured data source. Use context lanes such as `~~company_docs`, `~~team_communication`, or `~~dashboards_or_bi` when an input needs business meaning, source-of-truth guidance, or assumptions that are not captured in structured data alone. When an input depends on the outside market, use public sources for benchmarks, population estimates, comparable markets, or proxy assumptions.
-
-Use $gather-business-context to resolve context lanes when the right source of truth, business meaning, or assumption set is unclear.
-
-If the strongest source is unavailable or thin, continue with a transparent proxy assumption only when the estimate is still useful. Label the gap and explain how it affects confidence.
-
-### 4. Separate Facts From Assumptions
-
-Keep sourced facts, inferred estimates, and judgment calls distinct in the model. When exact data is unavailable, use a defensible proxy, explain why it is reasonable, and note the confidence level. Ground assumptions in evidence about how the market actually behaves, what can realistically change, and what determines the size of the opportunity.
-
-### 5. Build The Model
-
-Make the model easy to inspect and adjust.
-
-The model should make these elements easy to audit or revise:
-
-- market definition and measurement unit
-- assumptions and source context
-- calculation chain and derived values
-- base case, material ranges, and sensitivity logic
-- validation priorities
-
-For each major input, make the source path visible: structured data, context lane, public source, user-provided input, or proxy assumption.
-
-Keep derived values traceable to formulas or code rather than hardcoded outputs.
-
-Use $jupyter-notebooks when code is needed for source harmonization, calculations, sensitivity analysis, or reusable modeling logic. Keep formulas, inputs, intermediate calculations, and sensitivity logic inspectable.
-
-Use $spreadsheets when the user requests a spreadsheet, workbook, or Google Sheets deliverable, or when a market-sizing model would materially benefit from editable assumptions, sensitivity tables, charts, or polished workbook formatting.
-
-### 6. Test Sensitivity
-
-Identify the assumptions that move the estimate most.
-
-Show how the estimate changes when those assumptions move up or down. Prefer simple, decision-useful sensitivity analysis over exhaustive scenario sprawl.
-
-Use ranges when uncertainty is material. Do not hide uncertainty behind a single point estimate when the inputs are thin.
-
-### 7. State The Estimate And Validation Priorities
-
-End with the estimate, method, key assumptions, uncertainty, and next validation priorities.
-
-Close with the market definition, estimate or range, method, main uncertainty drivers, sensitivity takeaways, validation priorities, and practical interpretation for the user's decision.
-
-If source coverage is thin, say which major inputs rely on proxy assumptions and what source would most improve them.
-
-Use $validate-data when methodology, calculations, assumptions, caveats, or source support need review before sharing.

package/template/.codex/skills/data-analytics/skills/market-sizing/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Market Sizing"
-  short_description: "Estimate market and opportunity size with transparent assumptions"
-  default_prompt: "Estimate a market or opportunity size with transparent scope, assumptions, calculations, and sensitivity."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/metric-diagnostics/SKILL.md

@@ -1,130 +0,0 @@
----
-name: metric-diagnostics
-description: "Explain a metric movement, anomaly or gap by validating the metric, comparison and likely drivers."
----
-
-# Metric Diagnostics
-
-Use this skill to diagnose why a metric changed or differs from expectation. Reproduce the metric, define the comparison, quantify the movement, validate likely drivers, and state what is verified, likely, unresolved, and useful to do next.
-
-Clarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-### Source Discovery And Verification
-
-Use the relevant semantic layer first when one exists. Treat it as the starting map for candidate metrics, tables, joins, filters, caveats, source precedence, and known conflicts.
-
-Do not stop at the semantic layer or the first plausible source. Search across the relevant available company source lanes, including structured data or data warehouses, dashboards, company docs, team communication, notebooks, code repositories, and other connected company knowledge or data that could change the answer.
-
-For source-backed analytical work, always verify through live source reads. When the answer depends on data, run fresh data queries against the available structured-data sources before drawing conclusions, even when the semantic layer already names likely tables or definitions.
-
-Use the combined evidence to determine which source controls the answer, note meaningful disagreements, and state why the selected source is authoritative.
-
-### Source Access Guardrail
-
-Before querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.
-
-If a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.
-
-If the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.
-
-## Workflow
-
-### 1. Define The Diagnostic Question
-
-Frame the diagnostic so it is clear what changed and what comparison would prove it.
-
-Define:
-
-- what the metric means in business terms
-- the time window and comparison that make the change measurable
-- the population and grain that determine what counts
-- the source that owns the metric definition
-- the diagnostic question being answered, for example movement, concentration, or reconciliation
-
-Use $gather-business-context when business context is needed to understand what the metric means, what changed around the analysis period, or which explanations are plausible.
-
-### 2. Validate The Metric Definition And Source
-
-Before explaining the movement, confirm that the metric is defined correctly and that the source data can measure it reliably.
-
-Confirm the metric definition, grain, aggregation logic, filters, joins, exclusions, freshness, lineage, and any disagreement between trusted surfaces. Keep this source check focused on issues that could change the answer.
-
-Treat memory, saved context, semantic-layer notes, and familiar table names as source candidates, not source selection. For broad metric questions, run live source discovery against available tables, dashboards, metric docs, semantic registries, or other source-of-truth surfaces before choosing the controlling source. When both are available, inspect at least one business-facing or top-line surface and one lower-level source surface, then state why the selected source owns the answer.
-
-Use $analyze-data-quality when freshness, grain, joins, missingness, schema drift, outliers, unexpected categories, or distribution shifts could affect trust.
-
-Use $jupyter-notebooks when fresh SQL, Python, statistical modeling, reusable calculations, or multi-step decomposition need an inspectable analytical record.
-
-### 3. Establish The Metric Pattern
-
-Before looking for drivers, establish the metric pattern the diagnostic needs to explain. Quantify the metric over the relevant period and scope. If the question includes a comparison, reproduce that comparison.
-
-Do not search for causes until the size, timing, and scope of the pattern are verified or explicitly marked uncertain.
-
-### 4. Choose The Diagnostic Plan
-
-Choose the smallest set of cuts and checks likely to explain the pattern or strengthen confidence.
-
-Choose driver dimensions from the metric's operating logic, business context, and source shape. Prioritize drivers the business usually monitors or can act on, not every field available in the source. If the relevant drivers are unclear, use saved context or $gather-business-context to understand how the business explains the metric and what changed around the analysis period.
-
-When using a lower-level table, do not limit the driver analysis to fields surfaced by the first query. Recreate or join the business grouping needed to answer the question, such as model family, model superfamily, segment, region, cohort, product taxonomy, or customer hierarchy. If the grouping cannot be reconstructed, say so before simplifying the analysis.
-
-Use the explanation mode that fits the question. Common examples:
-
-- **Metric change**: compare the focal window with a baseline, rank segment contributions, check peer or historical context, and test mix shift versus within-segment movement.
-- **Spike, regression, or incident**: pin down onset, peak, recovery,
-  distribution shape rather than only averages, affected slices, broad versus localized degradation, and whether traffic or failure behavior changed.
-- **Largest contributors or concentration**: define "largest", rank entities,
-  compare total share and change, and look for major movers, entrants, and exits.
-- **Reconciliation or difference analysis**: align definitions, filters, grain,
-  numerator, denominator, and exclusions; quantify the components explaining the gap and state any residual.
-
-### 5. Decompose And Validate Drivers
-
-Quantify the main drivers and validate whether they explain the pattern.
-
-Size each major driver with the strongest readily available evidence. Show whether it explains the pattern, how large it is relative to the relevant base, trend, or gap, whether it is broad or concentrated, and whether it holds under the right comparison or scope.
-
-Iterate on driver hypotheses until the explanation answers why in a way that is relevant to the business. Follow promising cross-cuts and drill-downs when they could reveal the key explanation, and stop when additional cuts are unlikely to change the conclusion or materially improve confidence.
-
-Interpret driver results in context:
-
-- Use the relevant base, comparison, or share of total to make the driver meaningful.
-- For rates, check whether the numerator, denominator, or both explain the change.
-- For additive metrics, calculate contribution share when it sharpens the story.
-- Separate composition effects from within-segment performance effects when that distinction changes the explanation.
-- Prefer mutually exclusive driver buckets when additive contributions need to be interpreted; reconcile the decomposition exactly or size and explain the residual.
-
-Treat measurement issues as possible explanations, not just cleanup details. For example, the pattern may come from logging changes, incomplete recent data, duplicated rows, or a shifted denominator rather than an underlying business change.
-
-Calibrate the explanation to the evidence, and make important uncertainty visible. Use context when it changes interpretation, such as whether the pattern is ordinary, unusual, expected, or tied to a known change.
-
-Use $visualize-data when a chart would make the diagnostic claim easier to understand or verify.
-
-### 6. State Implications And Follow-Up
-
-Lead with the answer to the diagnostic question, then state the practical implications when the evidence supports them.
-
-The answer should make clear:
-
-- the pattern being explained
-- the strongest driver explanation and supporting evidence
-- why it matters for the business
-- how much confidence to place in the explanation
-- the implication, next action, or follow-up that matters most
-
-Keep implications distinguishable from verified factual reporting so a reader can tell where evidence ends and interpretation begins. Do not claim causality from timing alone; state when an explanation is only a plausible hypothesis.
-
-Use $gather-business-context when the metric result is clear but business context is needed to interpret the `so what` or identify realistic next actions.
-
-Use $validate-data when methodology, calculations, caveats, or the evidentiary support for the diagnostic conclusion need review before sharing.
-
-Do not treat artifact or report validation as analytical validation. Before handing off, confirm the analysis has the headline metric movement, driver contribution shares or effect sizes, source/window reconciliation, exact executed SQL or query references when queries were used, and caveats that would change interpretation.
-
-Pass the diagnostic substance and supporting evidence to $build-report. Let $build-report own the report surface, presentation polish, reproducibility treatment, and sharing handoff.

package/template/.codex/skills/data-analytics/skills/metric-diagnostics/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Metric Diagnostics"
-  short_description: "Diagnose metric changes, anomalies, gaps, and discrepancies"
-  default_prompt: "Diagnose why a metric changed by reproducing it, validating drivers, and summarizing the evidence."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/product-business-analysis/SKILL.md

@@ -1,141 +0,0 @@
----
-name: product-business-analysis
-description: "Analyze product or business data to support a decision, prioritize opportunities or evaluate a change."
----
-
-# Product And Business Analysis
-
-Use this skill to answer product or business questions with data-backed evidence, context, and a recommendation. Give the audience enough trustworthy evidence, interpretation, and uncertainty framing to choose a practical next action.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-### Source Discovery And Verification
-
-Use the relevant semantic layer first when one exists. Treat it as the starting map for candidate metrics, tables, joins, filters, caveats, source precedence, and known conflicts.
-
-Do not stop at the semantic layer or the first plausible source. Search across the relevant available company source lanes, including structured data or data warehouses, dashboards, company docs, team communication, notebooks, code repositories, and other connected company knowledge or data that could change the answer.
-
-For source-backed analytical work, always verify through live source reads. When the answer depends on data, run fresh data queries against the available structured-data sources before drawing conclusions, even when the semantic layer already names likely tables or definitions.
-
-Use the combined evidence to determine which source controls the answer, note meaningful disagreements, and state why the selected source is authoritative.
-
-### Source Access Guardrail
-
-Before querying sources, building artifacts, or drawing conclusions, determine whether the answer requires a specific source of truth.
-
-If a required source is unavailable, stop that path. Tell the user what source is needed, ask them to make it available or provide a reviewed fallback, and do not treat weaker substitutes as equivalent.
-
-If the missing source is only optional enrichment, continue with the strongest available evidence and label the gap when it materially affects the answer.
-
-Clarify with the user when a missing input would materially change the analytical frame or recommendation. Otherwise make a reasonable assumption, state it, and proceed.
-
-## Workflow
-
-### 1. Start From The Decision
-
-Identify the decision, audience, and action the analysis should inform before choosing data sources or metrics.
-
-State plainly:
-
-- the question and decision the analysis should inform
-- who will use the answer and what they can act on
-- the scope and comparison that define a useful answer
-- the outcome or behavior that matters for the decision
-- any assumptions needed to proceed
-
-Do not let unclear scope turn into broad exploratory work by default.
-
-### 2. Gather Decision-Relevant Context
-
-Run $gather-business-context before deeper analysis. That skill owns source selection, retrieval, source authority, conflict handling, and compact context notes. Use this workflow to decide how the gathered context changes the analysis and recommendation.
-
-Keep the context pass proportional to the task. For self-contained prompts or cases where the user already provided enough context, the pass can be brief: confirm the decision frame, definitions, source assumptions, and any obvious gaps before moving on. Do not turn mandatory context gathering into a broad background scan.
-
-Relevant context should clarify:
-
-- intent: what the work was meant to accomplish and why
-- definitions: how the work, metric, or source is defined and measured
-- timing: what changed around the analysis period that could affect interpretation
-- constraints: decisions, caveats, or limitations that affect what action is realistic
-
-### 3. Frame The Analysis
-
-Turn the question into a focused analytical framework.
-
-Define a framework for answering the question with data:
-
-- the specific data questions that would support or change the recommendation
-- the comparisons and dimensions to inspect
-- the unit of analysis that matches the decision
-- the metric definitions and caveats needed to interpret the result
-
-Use the framework to surface plausible hypotheses or interpretations, then turn them into focused data questions. Keep the framework specific enough to avoid broad exploration and support a recommendation.
-
-Use $design-kpis when the success metric, driver metrics, guardrails, or measurement plan need to be defined before the analysis can proceed.
-
-Start by defining what the answer needs to show in plain language. Then choose the data that matches that meaning as closely as possible, including who is counted and what comparison makes the number meaningful. If a field or event captures only part of what the decision cares about, say what it captures and what it leaves out.
-
-### 4. Run Focused Quantitative Analysis
-
-Run enough quantitative analysis to support or reject the framed hypotheses and inform the decision:
-
-- **Follow the framework.** Run the analyses that could change the recommendation first. Track additional data questions that emerge, answer the ones that matter for the decision, and leave lower-impact cuts as follow-up instead of expanding into broad exploration.
-
-- **Use the right comparison.** Interpret results against the relevant baseline, denominator, or comparison point before turning them into a recommendation. For example, do not conclude that one group is the best opportunity just because it has the most total usage. Check whether usage is high because the group is larger, whether the pattern still holds after normalizing by the active base, whether the group is growing or declining, whether the usage reflects the behavior or outcome that matters, and whether business context changes the interpretation.
-
-- **Size the opportunities.** Estimate the magnitude of impact each important opportunity could have. State what is being compared, which metric represents impact, what denominator or population it uses, and whether the data is complete enough to trust. Keep material unknown or unclassified groups visible when they could change the interpretation.
-
-- **Keep quantitative work inspectable.** Use $jupyter-notebooks to record queries and analysis. Use $analyze-data-quality when source freshness, grain, joins, missingness, schema drift, or unexpected distributions could affect trust.
-
-- **Validate before concluding.** Use $validate-data before sharing stakeholder-facing recommendations, high-impact claims, or surprising results. When dashboards and direct queries both exist, reconcile them or explain why they differ.
-
-### 5. Translate Evidence Into Decision Implications
-
-Frame the findings within the broader business context. Do not present quantitative evidence and business context as two unrelated streams.
-
-Interpret the evidence through the decision lenses that best fit the question. Choose lenses that would actually change the recommendation, and skip ones that would add noise or false precision. Common lenses include:
-
-- **Current scale:** Is the opportunity or problem large enough today to matter for the decision?
-- **Momentum:** Is the signal growing, shrinking, accelerating, or newly emerging?
-- **Breadth:** Is the pattern broad-based, or does it only appear in a narrow corner of the business?
-- **Concentration:** Does the conclusion depend on a few large entities, events, or outliers?
-- **Intensity:** Is the behavior deep enough per unit to suggest real need, value, or risk?
-- **Efficiency:** Does the option create better output, margin, conversion, productivity, or quality for the input required?
-- **Addressability:** Can the team realistically act on this option with available product, GTM, operational, policy, or technical levers?
-- **Differentiation:** Does this group or use case require a distinct motion, product experience, support model, or message?
-- **Substitution:** Is there evidence that behavior, spend, time, or workload could shift from another path?
-- **Risk or dependency:** Are there quality, trust, compliance, technical, operational, or data constraints that change the recommendation?
-- **Coverage:** Are unknown, missing, or sparsely tagged records large enough to change the answer?
-
-Use these as thinking tools, not a checklist. Explain why the chosen lenses matter for this decision, and mention omitted cuts only when they would plausibly change the interpretation or help explain the result.
-
-Use the measured opportunities to explain which differences matter for the decision and which ones call for different actions. If the business context shows that the initial sizing misses the actionable part of the opportunity, add the focused sizing cut needed to make the recommendation useful.
-
-If evidence conflicts, say so directly and explain which interpretation is better supported. Do not smooth over disagreement between sources.
-
-### 6. Hand Off The Recommendation
-
-End by handing the decision-ready recommendation to $build-report. This workflow owns the analytical conclusion; $build-report owns the reader-facing structure, visuals, evidence placement, and delivery surface.
-
-Before handoff, make the recommendation explicit:
-
-- what they should believe or do next
-- why the evidence supports that recommendation
-- which caveats or dependencies matter
-- what follow-up analysis would most improve confidence
-
-If evidence is incomplete, label the recommendation as provisional and state what would change confidence. Do not overstate the conclusion just to make the answer feel decisive.
-
-Use $validate-data when methodology, calculations, caveats, or the evidentiary support for the conclusion need review before sharing.
-
-Pass narrative ingredients to the report surface, not only result tables:
-
-- direct answer and recommendation
-- key evidence and how to interpret it
-- implication for the decision
-- unresolved uncertainty and caveats
-- recommended follow-up

package/template/.codex/skills/data-analytics/skills/product-business-analysis/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Product And Business Analysis"
-  short_description: "Analyze product or business data to support decisions"
-  default_prompt: "Analyze a product or business question with data-backed evidence, context, and a recommendation."
-policy:
-  allow_implicit_invocation: true

package/template/.codex/skills/data-analytics/skills/spreadsheets/SKILL.md

@@ -1,178 +0,0 @@
----
-name: spreadsheets
-description: "Create, edit or analyze spreadsheet files or Google Sheets artifacts, including formulas, tables and charts."
----
-
-# Spreadsheets skill
-
-This skill includes requirements and guidance for producing a correct, polished spreadsheet artifact quickly that completes the user's request. When producing spreadsheets, workbooks, or Google Sheets-targeted outputs, you will be judged on layout, readability, style, analytical workbook conventions, and correctness. Follow the requirements below for how to use the APIs effectively and how to verify your output before finalizing work for the user.
-
-For analytical tasks, you are especially judged on correctness and quality. This skill improves spreadsheet construction and formatting; it does not own the analysis logic, source selection, market assumptions, or business conclusion when another workflow skill is the primary route. For analysis prompts, aim for an output that can compete with a strong analyst-built workbook, not just a functional grid. A good default shape is an executive summary or dashboard first, then assumptions/sources, then model/detail sheets. For simpler tasks like creating a template or tracker, prioritize doing the spreadsheet build and edits quickly, while ensuring the user's request is fulfilled.
-
-For additional stylistic best practices, follow: `style_guidelines.md`
-
-Read `charts.md` when creating or editing substantive charts, dashboards, or chart-ready summaries.
-
-## Skill Configuration
-
-### User Context
-
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
-
-## Google Sheets-targeted output
-
-### New Creations
-
-For a net-new Google Sheets request, create and verify a local `.xlsx` with this skill first. For a requested native Google Sheets target, discover a currently available spreadsheet-import capability, read its actual schema, then import and verify the native result. Do not assume a callable name or upload-mode parameter.
-
-Do not use Computer Use, Browser Use, blank-Google-Sheets creation plus Google Sheets write APIs, or another direct-to-Sheets construction path for net-new Google Sheets unless the user explicitly asks for that alternate workflow. If they do, mention first that output quality is expected to be best when a local `.xlsx` is imported through the Google Drive plugin.
-
-If the required cloud capability is unavailable, explain the gap and offer a verified local XLSX. Consult the host tool catalog and its installation policy before suggesting an exact plugin; never invent an ID or demand reinstall as the default repair.
-
-After successful native import, the user-facing deliverable is the Google Sheets link. Treat the local `.xlsx` as a build artifact unless the user explicitly asks to keep or receive it.
-
-### Edits
-
-Use the Google Drive plugin's Google Sheets skill for edits to existing Google Sheets. The local `.xlsx` creation and native import workflow above applies only to net-new Google Sheets deliverables.
-
-
-
-# Tools + Contract
-- Use Codex workspace dependencies for spreadsheet artifact work: resolve them through the workspace dependency loader or runtime skill, then treat the returned Node/Python runtimes, package directory, and verification details as authoritative. Do not use system `node`, system `python`, global npm packages, or repo-local installs.
-- Use `@oai/artifact-tool` JS library, which exists in the default Codex workspace dependencies node_modules, for authoring, editing, inspecting, rendering, and exporting spreadsheet `.xlsx` workbooks.
-- Run builders from a writable conversation-specific temp or workspace directory, not from the managed dependency directory. Outputs and scratch files may live under the OS temp directory.
-- Start by setting up the work directory to work with normal Node module resolution: link or junction local `node_modules` to the workspace dependency node_modules so `import "@oai/artifact-tool"` resolves.
-- Prefer one executable `.mjs` builder; patch and rerun it when iterating. Do NOT use shell heredocs or keep extra builder copies.
-- If workspace dependencies or `@oai/artifact-tool` are unavailable, report a setup blocker; do not guess paths, install packages, use system deps, alter module resolution, copy/import bundled internals, or do a broad file system search.
-- Do not search package internals or dump prototypes to discover APIs. Use the API reference below; if blocked, run at most one exact `workbook.help("<api_or_feature>")` query before building.
-- Final response: include a short user-visible summary and standalone Markdown link(s) to the selected final deliverable: local `.xlsx` artifacts or verified native Google Sheets URLs, one per line: `[Revenue Model - MNST.xlsx](/absolute/path/to/revenue_model_mnst.xlsx)`.
-- Do not mention internal tooling or support artifacts such as builders, rendered previews, JSON/CSV/log files, or scratch files unless explicitly requested.
-- Do not use alternate workbook creation/editing libraries such as `openpyxl`, `xlsxwriter`, or `pandas.ExcelWriter` unless the user explicitly asks for a non-artifact-tool fallback.
-- For analysis outside workbook authoring, use JS or spreadsheet formulas when sufficient. If Python is needed, use bundled Python libraries, save JSON/CSV intermediates, and have the JS builder create the workbook. Keep auditable/user-editable calculations as formulas.
-- For nontrivial work, use `update_plan`: build quickly, verify/render, repair meaningful issues, then finalize without long polish loops. Incrementally rendering your work and assessing overall aesthetics, formatting and correctness along the way is very important (rigorously inspect the output and be confident in quality), but do not get stuck in a long render-verify loop. As part of your plan, think about the best practices and conventions to follow for the specific type of spreadsheet you're creating and the best way to structure the workbook for readability and usability.
-
-# Analysis Workbook Shape
-When a workflow such as `$market-sizing`, `$metric-diagnostics`, `$kpi-reporting`, or `$product-business-analysis` owns the analysis, use that workflow's structure first and focus this skill on workbook quality. Good analysis workbooks usually include:
-- `Summary` or `Dashboard` for top-line answer, key metrics, charts, and interpretation.
-- `Assumptions` or `Inputs` for editable drivers, scenarios, date ranges, and user-controlled variables.
-- `Model`, `Calculations`, or `Detail` for formula-backed derivations and intermediate tables.
-- `Sensitivity` or `Scenarios` when assumptions materially change the conclusion.
-- `Sources` for compact citations, source notes, and provenance.
-- `Checks` only when correctness depends on linked calculations, source reconciliation, or model integrity.
-
-# General Rules
-- Start meaningful edits quickly; avoid long upfront API exploration.
-- Use `references/artifact_tool_api.md` when concrete API syntax is needed.
-- If these skill instructions are already loaded in context, do not spend a shell turn re-reading this `SKILL.md` from disk. Move directly to the prompt, attachments, and workbook build.
-- For workbook with multiple tabs/sheets, create/populate non-formula inputs/tables and sheets prior to populating cross-sheet formulas.
-
-## Approach for quickly building a new spreadsheet
-1. Setup: import `@oai/artifact-tool`, create workbook/sheets for new files.
-2. Build quickly: bulk-write headers/data/formulas; then formatting/validation/conditional formatting; add charts/tables only when needed.
-3. Use additional focused calls if helpful for streamed progress.
-4. Near completion: inspect key ranges, scan formula errors, render all the sheets and verify, run a validation pass
-5. Export `.xlsx`
-
-## Making edits on a spreadsheet
-If a user asks to edit or add to an existing spreadsheet:
-- For visual fix requests, start with the smallest plausible local change rather than applying sheet-wide autofit, wrapping, or restyling.
-- When making edits, ensure existing formulas and patterns are consistent. For example, if asked to add another column or row to a table and there is conditional formatting applied to the whole table, it should extend to the new column or rows as well.
-- If specific cells/rows/columns are specified in prompt, limit edits to those ranges unless a broader change is clearly necessary. The exceptions are when other parts of the spreadsheet depend on them, e.g. if there's a dynamic chart that is based on the range of values in a table and a new row is added, the chart should include that new row. Another example is if conditional formatting was already set for a table from A1:C5, and you add a new column D, the conditional formatting should be updated (or deleted and re-created) to cover A1:D5.
-- For column resizing, avoid autofitting by default: instead, inspect only relevant data range, measure the longest text entry in that range, and set columnWidthPx to an estimated width based on text length (with a reasonable min/max cap). Use autofit only when the user explicitly asks for it.
-
-## Handling queries and questions
-- The user may ask questions about the sheet instead of requesting an edit or a change. Simply answer those questions about the spreadsheet based on the context available rather than making an edit the user didn't intend for. You can use inspect to learn more or directly read values/formulas/tables etc via accessor methods.
-
-# Error Recovery
-On first error:
-1. Read error text.
-2. Run one targeted `workbook.help("<exact_api>")` query only if needed.
-3. Retry with minimal patch (not full rewrite).
-4. Continue from existing workbook state.
-
-Do not loop indefinitely on similar failures.
-
-# Quality Guidelines
-- Keep layout readable and bounded, contents visible:
-  - avoid extreme width/height from unconstrained autofit
-  - cap oversized widths/heights after `autofit` + `wrap_text`
-- Prefer formula-driven logic over manual painted cells when logic is expected.
-- Derived values must be formulas (not hardcoded) and legible.
-- Use absolute/relative references correctly for fill/copy behavior.
-- Do not use magic numbers in formulas; reference cells (e.g. `=H6*(1+$B$3)`).
-- Blank editable templates must look blank/neutral before user data is entered. Count, ranking, best/worst, IRR/RATE/XIRR, variance, and status formulas should guard on required input cells and return `""`, `0`, or a clear "No entries yet" state as appropriate. Alternatively, prefill with a few rows of example data.
-- Include at least one visual summary for tracker/planning requests when appropriate (KPI block, chart, dashboard area).
-- For dashboard, visualization, chart-ready analysis, budget/reporting, trend, schedule/timeline, and KPI prompts with plottable data, include at least one native Excel chart unless a verified export failure remains after simplifying the chart. Do not silently replace all charts with styled tables.
-- For presentation-ready analytical workbooks, plain range formatting alone is usually not enough. Prefer real Excel structures where useful: tables, freeze panes, filters, data validation, conditional formats, and at least one chart/KPI/dashboard visual when the prompt implies summary analysis.
-- In rendered previews of dashboards and summary sheets, check financial values and row labels at normal zoom. Widen columns, adjust row heights, or move chart panels until important numbers and text are not clipped, awkwardly wrapped, or hidden.
-
-# Completion Criteria
-Complete only when:
-- Workbook content is populated and formulas compute.
-- No obvious formula errors in key scanned ranges (no bad refs/off-by-one/circular errors).
-- `.xlsx` saved to `outputs/<unique_thread_id>/`.
-- Layout is organized, legible, and aligned to request style (or default formatting baseline).
-
-# Verification Rules
-Before final response, verify values/formulas and visual quality.
-
-1. Inspect key ranges:
-```js
-const check = await workbook.inspect({
-  kind: "table",
-  range: "Dashboard!A1:H20",
-  include: "values,formulas",
-  tableMaxRows: 20,
-  tableMaxCols: 12,
-});
-console.log(check.ndjson);
-```
-
-Inspect targeting:
-- Prefer sheet-qualified ranges (`"Sheet!A1:H20"`) or `sheetId`.
-
-2. Scan formula errors:
-```js
-const errors = await workbook.inspect({
-  kind: "match",
-  searchTerm: "#REF!|#DIV/0!|#VALUE!|#NAME\\?|#N/A",
-  options: { useRegex: true, maxResults: 300 },
-  summary: "final formula error scan",
-});
-console.log(errors.ndjson);
-```
-
-3. Render sheets/ranges to verify visual output (skip if already verified and no style changes):
-```js
-const blob = await workbook.render({ sheetName: "Sheet1", range: "A1:H20", scale: 2 });
-```
-Make sure you do at least one visual pass of all the sheets in the workbook before the final export.
-
-Visual requirements:
-- Fix severe defects before finalizing: blank/broken charts, clipped key headers or numbers, unreadable colors, obvious formula errors, default blank sheets, or content outside the visible working area.
-- Ensure logical labels or titles appear once, texts are all clearly visible, and merged ranges exist where labels or content intentionally span multiple columns.
-- Do one focused visual repair pass after the initial render. Do not spend additional passes on minor polish once the workbook is correct, legible, and exported; note any minor limitation briefly and finalize.
-
-4. Keep verification compact:
-- Inspect key ranges.
-- Avoid huge NDJSON dumps.
-
-5. Export:
-```js
-await fs.mkdir(outputDir, { recursive: true });
-const output = await SpreadsheetFile.exportXlsx(workbook);
-await output.save(`${outputDir}/output.xlsx`);
-```
-
-6. Finalize immediately after successful export + compact verification.
-- Do not export extra `.xlsx` variants unless asked.
-- Do not keep iterating on alternate designs once requirements are met, unless asked.
-
-# Source, PDF, and Attachment Processing
-- Use bundled runtime libraries for source extraction. For PDF or 10-K/10-Q style inputs, read PDF via bundled Python `pypdf` when available, then use one small structured extraction script to collect all required facts into a dict/JSON object. Avoid many ad hoc `rg`/`sed` passes over the same text.
-- Keep source notes compact: record file name, section/table label, and enough context to audit the number. Do not paste large PDF excerpts into the workbook unless requested.
-- Bundled Python libraries available for extraction/analysis include `pandas`, `numpy`, `pypdf`, `python-docx`, and `reportlab`.
-- Bundled JS libraries available for document/PDF work include `docx`, `pdf-lib`, and `pdfjs-dist`.
-
-# Artifact Tool API Reference
-Read `references/artifact_tool_api.md` when building or editing workbooks and you need concrete JavaScript API syntax, API discovery, import/export patterns, existing-workbook inspection, feature-specific notes, or a runnable example. Use the workflow and verification rules above first; load the API reference only when needed.

package/template/.codex/skills/data-analytics/skills/spreadsheets/agents/openai.yaml

@@ -1,9 +0,0 @@
-interface:
-  display_name: "Spreadsheets"
-  short_description: "Create and edit spreadsheet or Google Sheets-ready files"
-  icon_small: "./assets/file-spreadsheet.png"
-  icon_large: "./assets/file-spreadsheet.png"
-  brand_color: "#107C41"
-  default_prompt: "Use $spreadsheets to build or update a spreadsheet artifact with formulas, formatting, and verification."
-policy:
-  allow_implicit_invocation: false