CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

notebook-guidance

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. Relevant when any of the following conditions are true: 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. 2. The user explicitly requests a notebook (.ipynb). 3. You are creating, editing, or executing cells in a Jupyter notebook. 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.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

70%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is a well-structured, highly actionable rulebook with an exemplary validated execution workflow (per-cell validation, hard stops, clean-final-state feedback loops). Its weaknesses are redundancy and a time-sensitive version pin that hurt token efficiency, and a monolithic all-inline layout that inlines reference-grade BigQuery and kernel detail instead of splitting it into bundle files.

Suggestions

De-duplicate the conditional execution rules: state the execute_cell-available vs. not-available branches once (in the numbered list) and trim the IMPORTANT block to a one-line pointer, removing the duplicated GENERATE -> EXECUTE -> VALIDATE text.

Move the BigQuery DataFrame Tips, kernel type catalog, and ML integration sections into reference files under references/ (e.g. references/bigquery.md, references/kernels.md) and keep SKILL.md as a concise overview with clearly signaled links, per the progressive-disclosure model.

Replace the pinned "bigframes version number 2.38.0 and above" with a version-check command or move it to a maintained reference file so the time-sensitive detail does not go stale in SKILL.md.

DimensionReasoningScore

Conciseness

The body is mostly efficient rules without explaining concepts Claude already knows, but it includes unnecessary repetition — the execute_cell conditional flow is stated in full both in the IMPORTANT block and again in numbered item 1 — plus somewhat padded kernel inference guidance and a time-sensitive version pin ("`bigframes` version number `2.38.0` and above") that is not in a deprecated/old-patterns section. This places it at 'mostly efficient but could be tightened' rather than 4 (only minor trims needed) or 2 (noticeably padded with unnecessary explanations).

3 / 5

Actionability

Guidance is largely executable: copy-paste-ready code blocks ("%load_ext bigframes", "%%bqsql df_sample / SELECT * FROM `project.dataset.table` LIMIT 10", "%pip list"), specific methods ("model.to_gbq()", "bpd.read_gbq_model()", ".dtypes", ".head() or .peek()"), and concrete anti-patterns. It stops short of 5 because the plotting rules, data cleaning rules, and the required summary format have no worked examples, leaving minor gaps.

4 / 5

Workflow Clarity

The multi-step process is clearly sequenced with explicit validation checkpoints and feedback loops: "GENERATE CELL -> EXECUTE CELL -> VALIDATE OUTPUT" with mandatory inspection of each output, a "HARD STOP on kernel failure" recovery rule, check-before-install ("run `%pip list` or `import <package>` to confirm"), "CLEAN FINAL STATE" (fix and delete failed cells), and schema verification ("Check `.dtypes` after loading"). It matches the top anchor; the no-batch/destructive cap does not apply since batch generation is explicitly prohibited.

5 / 5

Progressive Disclosure

The body is well-sectioned with headers and IMPORTANT/CAUTION callouts, and its cross-skill pointers ("@skill:managing-python-dependencies", "@skill:ml-best-practices" with a "MUST READ WHEN" condition) are clearly signaled and one level deep. However, no bundle files exist and roughly 310 lines of content — including reference-style material like the BigQuery DataFrame Tips list and the kernel type catalog — are inlined in SKILL.md when they would be better split into separate reference files, matching 'could be better organized; content that should be separate is inline' rather than 4.

3 / 5

Total

15

/

20

Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that explicitly and comprehensively answers both what the skill does and when to use it, with a numbered trigger list and specific technical anchors like `%%bqsql` and .ipynb. Its main weaknesses are meta-level verbs instead of concrete capability actions, a few missing natural trigger phrases (trends, charts), and one overly broad trigger condition that risks overlap with general data-analysis skills.

DimensionReasoningScore

Specificity

The description lists many specific topical areas — "notebook execution and validation", "library installation", "structuring notebooks for clarity", "data cleaning, plotting", "BigQuery SQL and machine learning workflows", and the concrete "use the `%%bqsql` magics" — with only minor coverage gaps. It falls short of 5 because the primary verbs are meta-level ("guides", "outlines", "covers") describing the document rather than concrete capability actions, and it is clearly above 3 since far more than 1-2 concrete actions/domains are named.

4 / 5

Completeness

Both questions are explicitly answered: the "what" (guides notebook use for analysis/exploration/visualization with BigQuery, execution/validation, library installation, data cleaning, plotting, ML integration) and a maximally explicit "when" — "Relevant when any of the following conditions are true" followed by four numbered concrete trigger conditions. This matches the anchor for explicit what AND when with concrete trigger phrases, not 4, since the "when" could not reasonably be more explicit.

5 / 5

Trigger Term Quality

Good natural keyword coverage including "data analysis", "data exploration", "data visualization", "data insights", "notebook (.ipynb)", "Jupyter notebook", and "BigQuery", with a file extension and synonyms present. It is not 5 because common user phrasings such as "find trends", "charts", or "plots" are missing, and it is above 3 since the term families are well represented.

4 / 5

Distinctiveness Conflict Risk

The notebook/BigQuery niche is clear with distinct triggers ("requests a notebook (.ipynb)", "creating, editing, or executing cells in a Jupyter notebook", "query BigQuery from within a notebook", "`%%bqsql` magics"), giving minimal conflict with unrelated skills. It is not 5 because condition 1 ("any ... data analysis, data exploration, data visualization, or data insights task that requires multiple steps") is broad enough to overlap with general data-analysis or charting skills.

4 / 5

Total

17

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

saski/arnesto

Path

.agents/skills/notebook-guidance/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.