[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ASRGHD5404RABF3AMYMFR6":3,"skill-same:01M7ASRGHD5404RABF3AMYMFR6":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":6,"updatedAt":33,"install":34,"resources":47},"01M7ASRGHD5404RABF3AMYMFR6","notebook-guidance",null,"This skill guides the use of Jupyter notebooks for data analysis, exploration, and visualization, particularly with BigQuery. It outlines best practices for notebook execution and validation (supporting both cell-by-cell execution and full notebook generation depending on tool availability), library installation, and structuring notebooks for clarity. It also covers specific rules for data cleaning, plotting, and integrating with BigQuery SQL and machine learning workflows.\nRelevant when any of the following conditions are true:\n  1. The user request involves a data analysis, data exploration, data visualization, or data insights task that requires multiple steps, queries, or visualizations to answer.\n  2. The user explicitly requests a notebook (.ipynb).\n  3. You are creating, editing, or executing cells in a Jupyter notebook.\n  4. You need to query BigQuery from within a notebook. DO NOT use the Python BigQuery client library; instead, you MUST use the `%%bqsql` magics explained in this skill.","saski\u002Farnesto","saski","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F140356?v=4","01M7ASBDSNXTRYDYB4K1PEA1RV","01M7ASBDTAKBDAAV99S1GE7HK6",6,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fnotebook-guidance\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: notebook-guidance\ndescription: |-\n  This skill guides the use of Jupyter notebooks for data analysis, exploration, and visualization, particularly with BigQuery. It outlines best practices for notebook execution and validation (supporting both cell-by-cell execution and full notebook generation depending on tool availability), library installation, and structuring notebooks for clarity. It also covers specific rules for data cleaning, plotting, and integrating with BigQuery SQL and machine learning workflows.\n  Relevant when any of the following conditions are true:\n    1. The user request involves a data analysis, data exploration, data visualization, or data insights task that requires multiple steps, queries, or visualizations to answer.\n    2. The user explicitly requests a notebook (.ipynb).\n    3. You are creating, editing, or executing cells in a Jupyter notebook.\n    4. You need to query BigQuery from within a notebook. DO NOT use the Python BigQuery client library; instead, you MUST use the `%%bqsql` magics explained in this skill.\nlicense: Apache-2.0\nmetadata:\n  version: v5\n  publisher: google\n---\n\n# Notebook Guidance\n\n## When to Use a Notebook\n\nBefore choosing to use a notebook, evaluate the task complexity using these\nheuristics.\n\nUse a notebook if you meet at least one of these criteria:\n\n*   📈 **Data Insights & Storytelling**: Use a notebook for any request to \"give\n    insights\", \"find trends\", \"explore data\", or \"analyze data\". These tasks\n    benefit from using visualizations to present the data.\n*   📊 **Visualizations are requested**: The user explicitly asks for charts or\n    plots.\n*   🔄 **Stateful \u002F Iterative Exploration**: You need to run a query, inspect\n    results, and decide the next query based on those results while keeping\n    state in memory.\n\nDo NOT use a notebook ONLY if:\n\n*   📝 **Simple Fact\u002FStatus**: The request only requires a single number (e.g.,\n    \"how many rows\") or a status check (e.g., \"when was this table updated\").\n*   🏃‍♂️ **Schema Preview**: The request is only about the schema or field\n    types.\n\n**Golden Rule of Data Storytelling:** If any analytical insight, trend, or\ncomparison is involved, favor a notebook and a visualization. A notebook is the\n\"standard\" environment for our developer workflow; do not avoid it because of\n\"overhead\".\n\n## Notebook Best Practices\n\n> [!IMPORTANT]\n>\n> **Agent execution rules**: Your behavior MUST depend on whether the\n> `notebook_execute_cell` tool is available in your current context: * **If\n> notebook `execute_cell` tool is available**: You MUST follow the incremental\n> GENERATE CELL -> EXECUTE CELL -> VALIDATE flow. * **If notebook `execute_cell`\n> tool is NOT available**: You MUST generate the complete notebook and request\n> user execution.\n\n1.  **CONDITIONAL EXECUTION FLOW**:\n    *   **If notebook `execute_cell` tool is available**: Follow the **STEP BY\n        STEP GENERATE CELL -> EXECUTE CELL -> VALIDATE OUTPUT** flow. Generate\n        ONE cell, execute it, then verify the output. If the output is data\n        (e.g. a dataframe), you MUST inspect it to confirm the logic is correct\n        before generating the next step. Batch generation of an entire notebook\n        is strictly prohibited because error propagation in notebooks is\n        expensive to fix.\n    *   **If notebook `execute_cell` tool is NOT available**:\n        *   Create the whole notebook at once.\n        *   Tell the user to run the notebook.\n        *   Tell the user to let you know once the notebook run is completed so\n            you can check the outputs to verify it's correct and fix any errors.\n2.  **IDENTIFY DATA EARLY**: Use `@skill:discovering-gcp-data-assets` or\n    BigQuery list tools to find the correct `project.dataset.table` before\n    writing ANY code. If the table ID is missing, ask the user.\n3.  **CLEAN FINAL STATE**: The final notebook MUST NOT have failed cells. If a\n    cell fails, you MUST fix it. If you tried several versions, delete the\n    failed attempts before you present the notebook to the user.\n4.  **LOGICAL CHUNK FIDELITY**: Keep cells small. One logical transformation or\n    visualization per cell. Group related cells into logical units (e.g., a\n    BigQuery `%%bqsql` magic cell followed immediately by a Python visualization\n    cell for those results). Use descriptive **markdown cells** to separate and\n    document different logical sections.\n5.  **GENERATE VISUALIZATIONS**: Always accompany data insights with\n    visualizations; charts are often more effective than raw numbers for\n    communicating trends and comparisons.\n\n## Kernel & Environment Management\n\nNotebooks run in specific **Kernels** (execution backends). You MUST ensure the\nkernel’s Python environment contains the necessary libraries (`bigframes`,\n`ipykernel`, etc.).\n\n### Kernel Types\n\n1.  **Local Python**: Standard Python 3 kernel running on the notebook host\n    (Managed instance, local machine).\n2.  **Cloud Spark Remote (Dataproc Serverless)**: Transient Spark environment\n    managed by GCP. Use for large-scale data processing.\n3.  **Cloud Spark Remote (Dataproc Cluster)**: Persistent Spark clusters for\n    shared or custom configurations.\n4.  **Colab (Managed)**: Ephemeral Google-managed runtimes.\n\n### No Active Kernel \u002F Setup Check\n\n1.  **Infer or Ask about Kernel Preferences**:\n    -   **Infer from Context**:\n        -   If the task mentions \"Spark\", \"PySpark\", or \"distributed compute\",\n            or if the active workspace is already a Spark cluster, lean towards\n            **Remote Spark**.\n        -   If the task is focused on \"BigQuery\", \"BigFrames\", or standard API\n            calls, lean towards **Local Python**.\n    -   **Ask when Ambiguous**: If multiple options fit, ask if they prefer a\n        **Local Python** or a **Cloud\u002FRemote Kernel** (e.g., Colab, Spark).\n2.  **For Local Setup**: Use `@skill:managing-python-dependencies` to verify if\n    a virtual environment exists. If not, create one. Ensure `ipykernel` is\n    installed in that environment. Install any other relevant libraries.\n3.  **For Remote Setup**: Advise the user to use the UI to select the\n    appropriate remote kernel.\n\n> [!IMPORTANT]\n>\n> **HARD STOP on kernel failure**: If a cell execution returns \"no active\n> kernel\" or any kernel-not-found error, you MUST **stop immediately**. Do NOT\n> scaffold, generate, or insert any further cells. Inform the user which kernel\n> is needed (e.g., PySpark \u002F Dataproc Serverless) and wait for explicit\n> confirmation that a kernel is active before proceeding with notebook\n> execution.\n\n### Proper Library Installation\n\n#### 1. Local Kernels\n\nBefore installing any python libraries, you MUST use\n`@skill:managing-python-dependencies` to detect how python dependencies are\nmanaged in the project.\n\n#### 2. Remote Kernels (Spark\u002FColab)\n\nSince these are often ephemeral or managed by GCP:\n\n*   **Check first (REQUIRED)**: Before writing any `%pip install` cell, run\n    `%pip list` or `import \u003Cpackage>` to confirm the package is not already\n    present. Managed runtimes (Dataproc Serverless, Colab) pre-install many\n    common packages. Only install what is confirmed missing.\n*   Use `%pip install \u003Cpackage>` in the first cell if a package is confirmed\n    missing and it's the only way to modify the runtime.\n\nWhen in doubt about the kernel type or preferred installation method, ask the\nuser for clarification.\n\n## Data Analysis & Visualization Rules\n\nGuidelines for performing exploratory data analysis, data cleaning, and\nvisualization in notebooks.\n\n### Notebook Layout\n\nThe notebook should read like a story. While you have flexibility (e.g.,\nmultiple visualizations for one data cell, or data cells building on each\nother), aim for this general flow:\n\n1.  **Title & Objective** (Markdown Cell)\n    *   What is this notebook for? (e.g., `# Retention Analysis`)\n2.  **Section Header** (Markdown Cell)\n    *   What are we looking at now? (e.g., `## Exploring User Retention`)\n3.  **Data Acquisition\u002FTransformation** (Python cell, may contain `%%bqsql`\n    magics)\n    *   Query BigQuery or transform data.\n4.  **Verification (Optional but Recommended)** (Python Cell)\n    *   `df.head()` or assert sanity checks.\n5.  **Visualization (The Goal)** (Python Cell)\n    *   Plot the insight (e.g., `df.plot()`).\n\n*Repeat steps 2-5 for each new sub-topic or insight. You can have multiple Data\ncells before a Visualization, or multiple Visualizations from one Data cell. The\nkey is to keep them grouped logically and separated by Markdown headers.*\n\n1.  **Final Summary** (Markdown Cell)\n\n    *   At the end of the notebook, add a markdown cell containing a summary\n        paragraph that summarizes the findings to the user. The summary MUST\n        follow these guidelines:\n    *   MUST NOT add Python code to the summary.\n    *   The summary MUST NOT start with a code block.\n    *   The summary MUST be strictly grounded in the numerical data verified in\n        the notebook.\n    *   The summary MUST ONLY contain the following three sections:\n        *   ### Q&A If the data analysis task contains questions (implied or\n            explicit), you MUST answer them based on the solving process. Skip\n            this section if there are no questions to answer.\n        *   ### Data Analysis Key Findings Summarize the key analysis findings\n            in bullet points, it's a plus to quote the numbers in the previous\n            steps. Only report high-value findings, skip the obvious ones.\n        *   ### Insights or Next Steps Provide 1-2 concise insights or next\n            steps in bullet points.\n\n2.  **Next Steps**: After the notebook has been successfully executed and\n    verified, and the summary is complete, notify the user and propose next step\n    suggestions.\n\n### Plotting Rules\n\n1.  You MUST use different colors for different features to ensure plots are\n    readable for humans.\n2.  When creating a plot, you MUST adjust the figure size based on the number of\n    features. The labels and legends MUST NOT overlap.\n3.  You SHOULD arrange the layout wisely. Using subplots CAN help in placing\n    different plots effectively.\n4.  You MUST use inline figures to present figures and plots along with code and\n    text in the notebook.\n5.  For clustering, use PCA to reduce to 2D before scatter plotting.\n6.  Use **Line Charts** ONLY for continuous data (e.g. time series) where\n    interpolation between points is meaningful.\n\n### Data Cleaning Rules\n\n1.  You MUST be careful about missing values and duplicated values.\n2.  You MUST NOT drop columns unless absolutely necessary. Dropping columns is\n    irreversible.\n3.  You SHOULD focus on columns directly related to accomplishing the task; not\n    every column NEEDS to be cleaned.\n\n## Specialized Notebook Guidance\n\nRefer to the following resources for guidance on specific notebook topics:\n\n### 1. BigQuery in Notebooks\n\nUse BigFrames magics `%%bqsql` for BigQuery SQL queries. These cells support\nnative BigQuery SQL execution and data export to BigFrames dataframes.\n\n> [!IMPORTANT]\n>\n> *   Unless specified by the user, **always use SQL for querying BigQuery.**\n> *   DO NOT use the standard BigQuery Python client library\n>     (`google.cloud.bigquery`) or `pandas.read_gbq`.\n> *   **Mandatory dataframe export**: Always provide a dataframe name e.g.\n>     `%%bqsql \u003Cdf_name>`. This makes it easy to use results in follow up Python\n>     cells.\n> *   Verify that `bigframes` version number `2.38.0` and above is installed in\n>     the notebook runtime environment. If it is missing, ask the user if they\n>     would like you to upgrade for them.\n\n**Example %%bqsql magic usage:**\n\n```python\n# Initialize BigFrames and load %%bqsql magics\nimport bigframes\nimport bigframes.pandas as bpd\n%load_ext bigframes\n```\n\n> [!CAUTION]\n>\n> Always use `%load_ext bigframes` exactly as shown. Do not load submodules —\n> for example, `%load_ext bigframes.magics` or `%load_ext bigframes.bigquery`\n> are not valid and must not be used.\n\n> [!IMPORTANT]\n>\n> The `bigframes` library must be installed. Determine if bigframes needs to be\n> installed by following @skill:managing-python-dependencies.\n\n```python\n%%bqsql df_sample\nSELECT * FROM `project.dataset.table` LIMIT 10\n```\n\n#### Anti-patterns (NEVER DO THESE)\n\n> [!CAUTION]\n>\n> 1.  **NO Python SDK for Queries**: Do not switch to\n>     `client.query(sql).to_dataframe()` if SQL fails. Fix the SQL syntax\n>     instead.\n> 2.  **NO Mixing Logic**: Do not put Python code in the same cell as `%%bqsql`\n>     magics.\n\n#### Working with SQL Results in Python\n\nMagic cells with `%%bqsql \u003Cdf_name>` produce a **BigQuery DataFrame**. In\nsubsequent cells, you can use `\u003Cdf_name>` directly.\n\n> [!IMPORTANT]\n>\n> You MUST use BigFrames for data exploration, manipulation, splitting etc. You\n> MUST use BQML SQL or bigframes.ml for machine learning tasks. You MUST NOT use\n> pandas or Scikit-learn.\n\n##### BigQuery DataFrame Tips\n\n*   **Avoid `.to_pandas()`**: You MUST NOT use `.to_pandas()` to download the\n    entire dataset into memory. There are some exceptions:\n    *   An error message explicitly requests you to use `to_pandas()`\n    *   You are going to visualize the data, **and** the visualization library\n        does not accept BigFrames Dataframe\u002FSeries instances. In this case,\n        reduce the amount of data you are going to download before calling\n        `.to_pandas()`\n*   **Avoid `read_gbq()` for SQL**: Do not write SQL queries and execute them\n    with `read_gbq()`. Use BigFrames Dataframe\u002FSeries methods instead.\n*   **Use BigFrames ML package for Machine Learning Tasks**: Do not use\n    Scikit-learn or other ML libraries with BigFrames dataframes. Import your\n    tools\u002Fclasses from `bigframes.ml`.\n*   **Stay in the Cloud**: Perform data cleaning, transformation, and analysis\n    via BigFrames methods to leverage BigQuery's scale.\n*   **Accessors over UDFs\u002FLambdas**:\n    *   Prefer built-in accessors (e.g., `df.col.str.*`, `df.col.dt.*`) over\n        remote UDFs.\n    *   **Do not use lambdas** with `Series.map()` or `DataFrame.apply()`.\n*   **Schema Verification**: Do not assume schema of intermediate outputs. Check\n    `.dtypes` after loading, and use `display()` with `.head()` or `.peek()`.\n*   **Visualization**: BigFrames Dataframe mostly works directly with\n    Matplotlib, Seaborn, and other plotting libraries. If your attempt didn't\n    work, try using the \"plot\" accessor. If that didn't work either, you MUST\n    sample or aggregate your data to make it small enough before calling\n    \"to_pandas()\".\n*   **Model Persistence**: To persist a model. use `model.to_gbq()`. To load a\n    persisted model, use `bpd.read_gbq_model()`.\n\n### 2. Machine Learning in Notebooks\n\nIntegration with machine learning workflows and best practices. - **Guide**: Use\n`@skill:ml-best-practices`. - **MUST READ WHEN**: The task involves machine\nlearning, training a model, clustering, classification, regression, or\ntime-series forecasting.\n\nIf any \"MUST READ WHEN\" condition is met, you MUST read the corresponding guide\nbefore proceeding.\n","# Notebook Guidance\n\n## When to Use a Notebook\n\nBefore choosing to use a notebook, evaluate the task complexity using these\nheuristics.\n\nUse a notebook if you meet at least one of these criteria:\n\n*   📈 **Data Insights & Storytelling**: Use a notebook for any request to \"give\n    insights\", \"find trends\", \"explore data\", or \"analyze data\". These tasks\n    benefit from using visualizations to present the data.\n*   📊 **Visualizations are requested**: The user explicitly asks for charts or\n    plots.\n*   🔄 **Stateful \u002F Iterative Exploration**: You need to run a query, inspect\n    results, and decide the next query based on those results while keeping\n    state in memory.\n\nDo NOT use a notebook ONLY if:\n\n*   📝 **Simple Fact\u002FStatus**: The request only requires a single number (e.g.,\n    \"how many rows\") or a status check (e.g., \"when was this table updated\").\n*   🏃‍♂️ **Schema Preview**: The request is only about the schema or field\n    types.\n\n**Golden Rule of Data Storytelling:** If any analytical insight, trend, or\ncomparison is involved, favor a notebook and a visualization. A notebook is the\n\"standard\" environment for our developer workflow; do not avoid it because of\n\"overhead\".\n\n## Notebook Best Practices\n\n> [!IMPORTANT]\n>\n> **Agent execution rules**: Your behavior MUST depend on whether the\n> `notebook_execute_cell` tool is available in your current context: * **If\n> notebook `execute_cell` tool is available**: You MUST follow the incremental\n> GENERATE CELL -> EXECUTE CELL -> VALIDATE flow. * **If notebook `execute_cell`\n> tool is NOT available**: You MUST generate the complete notebook and request\n> user execution.\n\n1.  **CONDITIONAL EXECUTION FLOW**:\n    *   **If notebook `execute_cell` tool is available**: Follow the **STEP BY\n        STEP GENERATE CELL -> EXECUTE CELL -> VALIDATE OUTPUT** flow. Generate\n        ONE cell, execute it, then verify the output. If the output is data\n        (e.g. a dataframe), you MUST inspect it to confirm the logic is correct\n        before generating the next step. Batch generation of an entire notebook\n        is strictly prohibited because error propagation in notebooks is\n        expensive to fix.\n    *   **If notebook `execute_cell` tool is NOT available**:\n        *   Create the whole notebook at once.\n        *   Tell the user to run the notebook.\n        *   Tell the user to let you know once the notebook run is completed so\n            you can check the outputs to verify it's correct and fix any errors.\n2.  **IDENTIFY DATA EARLY**: Use `@skill:discovering-gcp-data-assets` or\n    BigQuery list tools to find the correct `project.dataset.table` before\n    writing ANY code. If the table ID is missing, ask the user.\n3.  **CLEAN FINAL STATE**: The final notebook MUST NOT have failed cells. If a\n    cell fails, you MUST fix it. If you tried several versions, delete the\n    failed attempts before you present the notebook to the user.\n4.  **LOGICAL CHUNK FIDELITY**: Keep cells small. One logical transformation or\n    visualization per cell. Group related cells into logical units (e.g., a\n    BigQuery `%%bqsql` magic cell followed immediately by a Python visualization\n    cell for those results). Use descriptive **markdown cells** to separate and\n    document different logical sections.\n5.  **GENERATE VISUALIZATIONS**: Always accompany data insights with\n    visualizations; charts are often more effective than raw numbers for\n    communicating trends and comparisons.\n\n## Kernel & Environment Management\n\nNotebooks run in specific **Kernels** (execution backends). You MUST ensure the\nkernel’s Python environment contains the necessary libraries (`bigframes`,\n`ipykernel`, etc.).\n\n### Kernel Types\n\n1.  **Local Python**: Standard Python 3 kernel running on the notebook host\n    (Managed instance, local machine).\n2.  **Cloud Spark Remote (Dataproc Serverless)**: Transient Spark environment\n    managed by GCP. Use for large-scale data processing.\n3.  **Cloud Spark Remote (Dataproc Cluster)**: Persistent Spark clusters for\n    shared or custom configurations.\n4.  **Colab (Managed)**: Ephemeral Google-managed runtimes.\n\n### No Active Kernel \u002F Setup Check\n\n1.  **Infer or Ask about Kernel Preferences**:\n    -   **Infer from Context**:\n        -   If the task mentions \"Spark\", \"PySpark\", or \"distributed compute\",\n            or if the active workspace is already a Spark cluster, lean towards\n            **Remote Spark**.\n        -   If the task is focused on \"BigQuery\", \"BigFrames\", or standard API\n            calls, lean towards **Local Python**.\n    -   **Ask when Ambiguous**: If multiple options fit, ask if they prefer a\n        **Local Python** or a **Cloud\u002FRemote Kernel** (e.g., Colab, Spark).\n2.  **For Local Setup**: Use `@skill:managing-python-dependencies` to verify if\n    a virtual environment exists. If not, create one. Ensure `ipykernel` is\n    installed in that environment. Install any other relevant libraries.\n3.  **For Remote Setup**: Advise the user to use the UI to select the\n    appropriate remote kernel.\n\n> [!IMPORTANT]\n>\n> **HARD STOP on kernel failure**: If a cell execution returns \"no active\n> kernel\" or any kernel-not-found error, you MUST **stop immediately**. Do NOT\n> scaffold, generate, or insert any further cells. Inform the user which kernel\n> is needed (e.g., PySpark \u002F Dataproc Serverless) and wait for explicit\n> confirmation that a kernel is active before proceeding with notebook\n> execution.\n\n### Proper Library Installation\n\n#### 1. Local Kernels\n\nBefore installing any python libraries, you MUST use\n`@skill:managing-python-dependencies` to detect how python dependencies are\nmanaged in the project.\n\n#### 2. Remote Kernels (Spark\u002FColab)\n\nSince these are often ephemeral or managed by GCP:\n\n*   **Check first (REQUIRED)**: Before writing any `%pip install` cell, run\n    `%pip list` or `import \u003Cpackage>` to confirm the package is not already\n    present. Managed runtimes (Dataproc Serverless, Colab) pre-install many\n    common packages. Only install what is confirmed missing.\n*   Use `%pip install \u003Cpackage>` in the first cell if a package is confirmed\n    missing and it's the only way to modify the runtime.\n\nWhen in doubt about the kernel type or preferred installation method, ask the\nuser for clarification.\n\n## Data Analysis & Visualization Rules\n\nGuidelines for performing exploratory data analysis, data cleaning, and\nvisualization in notebooks.\n\n### Notebook Layout\n\nThe notebook should read like a story. While you have flexibility (e.g.,\nmultiple visualizations for one data cell, or data cells building on each\nother), aim for this general flow:\n\n1.  **Title & Objective** (Markdown Cell)\n    *   What is this notebook for? (e.g., `# Retention Analysis`)\n2.  **Section Header** (Markdown Cell)\n    *   What are we looking at now? (e.g., `## Exploring User Retention`)\n3.  **Data Acquisition\u002FTransformation** (Python cell, may contain `%%bqsql`\n    magics)\n    *   Query BigQuery or transform data.\n4.  **Verification (Optional but Recommended)** (Python Cell)\n    *   `df.head()` or assert sanity checks.\n5.  **Visualization (The Goal)** (Python Cell)\n    *   Plot the insight (e.g., `df.plot()`).\n\n*Repeat steps 2-5 for each new sub-topic or insight. You can have multiple Data\ncells before a Visualization, or multiple Visualizations from one Data cell. The\nkey is to keep them grouped logically and separated by Markdown headers.*\n\n1.  **Final Summary** (Markdown Cell)\n\n    *   At the end of the notebook, add a markdown cell containing a summary\n        paragraph that summarizes the findings to the user. The summary MUST\n        follow these guidelines:\n    *   MUST NOT add Python code to the summary.\n    *   The summary MUST NOT start with a code block.\n    *   The summary MUST be strictly grounded in the numerical data verified in\n        the notebook.\n    *   The summary MUST ONLY contain the following three sections:\n        *   ### Q&A If the data analysis task contains questions (implied or\n            explicit), you MUST answer them based on the solving process. Skip\n            this section if there are no questions to answer.\n        *   ### Data Analysis Key Findings Summarize the key analysis findings\n            in bullet points, it's a plus to quote the numbers in the previous\n            steps. Only report high-value findings, skip the obvious ones.\n        *   ### Insights or Next Steps Provide 1-2 concise insights or next\n            steps in bullet points.\n\n2.  **Next Steps**: After the notebook has been successfully executed and\n    verified, and the summary is complete, notify the user and propose next step\n    suggestions.\n\n### Plotting Rules\n\n1.  You MUST use different colors for different features to ensure plots are\n    readable for humans.\n2.  When creating a plot, you MUST adjust the figure size based on the number of\n    features. The labels and legends MUST NOT overlap.\n3.  You SHOULD arrange the layout wisely. Using subplots CAN help in placing\n    different plots effectively.\n4.  You MUST use inline figures to present figures and plots along with code and\n    text in the notebook.\n5.  For clustering, use PCA to reduce to 2D before scatter plotting.\n6.  Use **Line Charts** ONLY for continuous data (e.g. time series) where\n    interpolation between points is meaningful.\n\n### Data Cleaning Rules\n\n1.  You MUST be careful about missing values and duplicated values.\n2.  You MUST NOT drop columns unless absolutely necessary. Dropping columns is\n    irreversible.\n3.  You SHOULD focus on columns directly related to accomplishing the task; not\n    every column NEEDS to be cleaned.\n\n## Specialized Notebook Guidance\n\nRefer to the following resources for guidance on specific notebook topics:\n\n### 1. BigQuery in Notebooks\n\nUse BigFrames magics `%%bqsql` for BigQuery SQL queries. These cells support\nnative BigQuery SQL execution and data export to BigFrames dataframes.\n\n> [!IMPORTANT]\n>\n> *   Unless specified by the user, **always use SQL for querying BigQuery.**\n> *   DO NOT use the standard BigQuery Python client library\n>     (`google.cloud.bigquery`) or `pandas.read_gbq`.\n> *   **Mandatory dataframe export**: Always provide a dataframe name e.g.\n>     `%%bqsql \u003Cdf_name>`. This makes it easy to use results in follow up Python\n>     cells.\n> *   Verify that `bigframes` version number `2.38.0` and above is installed in\n>     the notebook runtime environment. If it is missing, ask the user if they\n>     would like you to upgrade for them.\n\n**Example %%bqsql magic usage:**\n\n```python\n# Initialize BigFrames and load %%bqsql magics\nimport bigframes\nimport bigframes.pandas as bpd\n%load_ext bigframes\n```\n\n> [!CAUTION]\n>\n> Always use `%load_ext bigframes` exactly as shown. Do not load submodules —\n> for example, `%load_ext bigframes.magics` or `%load_ext bigframes.bigquery`\n> are not valid and must not be used.\n\n> [!IMPORTANT]\n>\n> The `bigframes` library must be installed. Determine if bigframes needs to be\n> installed by following @skill:managing-python-dependencies.\n\n```python\n%%bqsql df_sample\nSELECT * FROM `project.dataset.table` LIMIT 10\n```\n\n#### Anti-patterns (NEVER DO THESE)\n\n> [!CAUTION]\n>\n> 1.  **NO Python SDK for Queries**: Do not switch to\n>     `client.query(sql).to_dataframe()` if SQL fails. Fix the SQL syntax\n>     instead.\n> 2.  **NO Mixing Logic**: Do not put Python code in the same cell as `%%bqsql`\n>     magics.\n\n#### Working with SQL Results in Python\n\nMagic cells with `%%bqsql \u003Cdf_name>` produce a **BigQuery DataFrame**. In\nsubsequent cells, you can use `\u003Cdf_name>` directly.\n\n> [!IMPORTANT]\n>\n> You MUST use BigFrames for data exploration, manipulation, splitting etc. You\n> MUST use BQML SQL or bigframes.ml for machine learning tasks. You MUST NOT use\n> pandas or Scikit-learn.\n\n##### BigQuery DataFrame Tips\n\n*   **Avoid `.to_pandas()`**: You MUST NOT use `.to_pandas()` to download the\n    entire dataset into memory. There are some exceptions:\n    *   An error message explicitly requests you to use `to_pandas()`\n    *   You are going to visualize the data, **and** the visualization library\n        does not accept BigFrames Dataframe\u002FSeries instances. In this case,\n        reduce the amount of data you are going to download before calling\n        `.to_pandas()`\n*   **Avoid `read_gbq()` for SQL**: Do not write SQL queries and execute them\n    with `read_gbq()`. Use BigFrames Dataframe\u002FSeries methods instead.\n*   **Use BigFrames ML package for Machine Learning Tasks**: Do not use\n    Scikit-learn or other ML libraries with BigFrames dataframes. Import your\n    tools\u002Fclasses from `bigframes.ml`.\n*   **Stay in the Cloud**: Perform data cleaning, transformation, and analysis\n    via BigFrames methods to leverage BigQuery's scale.\n*   **Accessors over UDFs\u002FLambdas**:\n    *   Prefer built-in accessors (e.g., `df.col.str.*`, `df.col.dt.*`) over\n        remote UDFs.\n    *   **Do not use lambdas** with `Series.map()` or `DataFrame.apply()`.\n*   **Schema Verification**: Do not assume schema of intermediate outputs. Check\n    `.dtypes` after loading, and use `display()` with `.head()` or `.peek()`.\n*   **Visualization**: BigFrames Dataframe mostly works directly with\n    Matplotlib, Seaborn, and other plotting libraries. If your attempt didn't\n    work, try using the \"plot\" accessor. If that didn't work either, you MUST\n    sample or aggregate your data to make it small enough before calling\n    \"to_pandas()\".\n*   **Model Persistence**: To persist a model. use `model.to_gbq()`. To load a\n    persisted model, use `bpd.read_gbq_model()`.\n\n### 2. Machine Learning in Notebooks\n\nIntegration with machine learning workflows and best practices. - **Guide**: Use\n`@skill:ml-best-practices`. - **MUST READ WHEN**: The task involves machine\nlearning, training a model, clustering, classification, regression, or\ntime-series forecasting.\n\nIf any \"MUST READ WHEN\" condition is met, you MUST read the corresponding guide\nbefore proceeding.\n",{"name":5,"license":14,"metadata":23,"description":7},{"version":24,"publisher":25},"v5","google","main","3c24fc2c035029b08c7326774bee3fef8fb95566",".agents\u002Fskills\u002Fnotebook-guidance",0,"https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto","https:\u002F\u002Fgithub.com\u002Fsaski","http:\u002F\u002Fsaski.com","2026-11-12 20:09:16",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add saski\u002Farnesto --skill notebook-guidance",{"tool":40,"command":41},"bunx","bunx skills add saski\u002Farnesto --skill notebook-guidance",{"tool":43,"command":44},"pnpm","pnpm dlx skills add saski\u002Farnesto --skill notebook-guidance","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fnotebook-guidance\u002FSKILL.md",true,[],[49,57,64,71,78,85],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":18},"01M7AT7F5FSHNAMFMF01N0QA1X","visualize","Use \u002Fvisualize for creating compact charts, diagrams, or other visuals inline as part of the conversation itself. It chooses among Markdown tables, Mermaid, inline HTML, and other supported in-transcript forms. Use Canvas for durable artifacts outside the transcript that users may revisit, refine, or share.","Unlicense","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fvisualize\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":18},"01M7AT79MHSAR3JDDMP7DGERM9","update-cursor-settings","Modify Cursor\u002FVSCode user settings in settings.json. Use when you want to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fupdate-cursor-settings\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":18},"01M7AT73WF3Y22E0FKYAMCCJES","update-cli-config","View and modify Cursor CLI configuration settings in ~\u002F.cursor\u002Fcli-config.json. Use when the user wants to change CLI settings, configure permissions, switch approval mode, enable vim mode, toggle display options, configure sandbox, or manage any CLI preferences.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fupdate-cli-config\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":18},"01M7AT6F3FBP85AJJ5BJNR8B5W","statusline","Configure a custom status line in the CLI. Use when the user mentions status line, statusline, statusLine, CLI status bar, prompt footer customization, or wants to add session context above the prompt.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fstatusline\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":18},"01M7AT6D24QFS5XRAFN8S5XJ7W","split-to-prs","Split current work into small reviewable PRs. Use when the user asks to split a chat, set of changes, branch, or PR.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fsplit-to-prs\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":53,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":18},"01M7AT69FYFN84XZKW452JV5DF","shell","Runs the rest of a \u002Fshell request as a literal shell command. Use only when the user explicitly invokes \u002Fshell and wants the following text executed directly in the terminal.","https:\u002F\u002Fgithub.com\u002Fsaski\u002Farnesto\u002Fblob\u002Fmain\u002F.cursor\u002Fskills-cursor\u002Fshell\u002FSKILL.md",[],[]]