Use when a user pastes a Snowflake Quickstart URL or asks to learn/walk through a Quickstart. Fetches the source content from GitHub, parses it into stages, checks the learner's environment, and delivers a guided build experience with two modes (learner or builder). Triggers: quickstarts.snowflake.com, snowflake.com/en/developers/guides/, walk me through this quickstart, teach me this quickstart, learn this guide, I want to do this quickstart. Do NOT use for general SQL help or non-Quickstart tutorials.
Instrucciones de origen · Vista previa de solo lectura
name
quickstart-guide
title
Learn Snowflake Quickstarts
summary
Paste a Snowflake Quickstart URL and get a guided, interactive learning experience.
description
Use when a user pastes a Snowflake Quickstart URL or asks to learn/walk through a Quickstart. Fetches the source content from GitHub, parses it into stages, checks the learner's environment, and delivers a guided build experience with two modes (learner or builder). Triggers: quickstarts.snowflake.com, snowflake.com/en/developers/guides/, walk me through this quickstart, teach me this quickstart, learn this guide, I want to do this quickstart. Do NOT use for general SQL help or non-Quickstart tutorials.
Take a Snowflake Quickstart URL and deliver a guided, interactive learning experience. The learner pastes a link; you fetch the content, plan the build, check their environment, and teach it live.
When to Use
Trigger this skill when the user's input contains a URL matching either pattern:
Also trigger when the user says something like "walk me through [quickstart name]" or "teach me [quickstart topic]" alongside a URL.
Workflow
Step 1: Detect and Extract Slug
Parse the URL to extract the Quickstart slug.
New pattern:https://www.snowflake.com/en/developers/guides/<slug>
Extract everything after /guides/ up to the next / or end of string
Old pattern:https://quickstarts.snowflake.com/guide/<slug>
Extract everything after /guide/ up to the next / or end of string
Note: old slugs may use underscores where new ones use hyphens
Store the extracted slug for Step 2.
Step 2: Fetch Quickstart Content
Retrieve the source markdown from GitHub. The Quickstart source lives at:
https://github.com/Snowflake-Labs/sfquickstarts under site/sfguides/src/<folder>/
Fetch sequence:
Get the folder listing. Use web_fetch on:
https://api.github.com/repos/Snowflake-Labs/sfquickstarts/contents/site/sfguides/src/<slug>
This returns a JSON array of file objects.
If 404, try slug variations:
Replace hyphens with underscores (or vice versa)
Try the original slug with/without trailing characters
Repeat the folder listing request with the alternate slug
Fetch the raw markdown. From the JSON array response, access and read the raw markdown content by fetching the value for the download_url key of the .md file.
Verify the content. Read the first ~20 lines of the fetched markdown. Check that the field in the frontmatter matches the URL slug. If it doesn't match, you may have the wrong Quickstart — try another variation.
id:
Fallback. If GitHub fetch fails entirely (repo restructured, file moved), fall back to web_fetch on the original URL the user pasted. Parse whatever structured content is available from the rendered page.
If fetch fails completely: Tell the learner the content couldn't be retrieved. Ask if they have the content locally or can provide an alternative URL.
Step 3: Parse and Plan Stages
Load references/quickstart-parsing.md for detailed structure rules.
From the fetched markdown, extract:
Metadata from frontmatter: id, summary (title), authors, categories, duration
Prerequisites from the Prerequisites/Setup steps: roles, privileges, warehouses, external tools
Logical stages by mapping Quickstart steps:
Overview/Prerequisites → inputs for diagnostics (Step 5)
Core tutorial steps → Stages 2-N (one per major deliverable)
Steps with external dependencies (SPCS, third-party tools) → optional stages
Conclusion → use as source material for the recap in Step 8
Code blocks (SQL, Python, YAML) — these are what gets executed or written to files
Final deliverable — what the learner will have when done
Target 4-8 stages total. Combine small steps; split large ones.
Step 4: Check for Companion Repo
Many Quickstarts have a companion GitHub repo containing SQL scripts, Python code, YAML configs, or data files. Check for one.
Detection:
Look for a fork repo link: field in the Quickstart frontmatter
Scan the markdown body for GitHub URLs pointing to a Snowflake-Labs/sfguide-* repo (typically in a Prerequisites or Setup step)
If a companion repo is found:
Use the GitHub API to list its top-level contents:
https://api.github.com/repos/<owner>/<repo>/contents/
Note the key files (.sql, .py, .yaml, .json, notebooks).
Present the finding to the learner: "This Quickstart has a companion repo at [url] containing [list key files — e.g., setup.sql, app.py, model.yaml]."
Ask the learner via ask_user_question:
Clone it — "Download the full repo to my machine. I'll use the files directly." Best if you want to keep the code after the session.
Reference it (lightweight) — "Don't download anything. Access individual files from GitHub as needed." No git clone — files are fetched on demand during the build, same way the Quickstart markdown was fetched.
If Clone: Ask where to clone (suggest current directory as default). Run git clone <url> <path>. Reference files from the cloned path during execution.
If Reference (lightweight): During Step 7 execution, fetch individual files on demand via the GitHub API (download_url from the contents listing) — the same pattern used for the Quickstart markdown itself. No local clone needed.
If no companion repo is found: Skip this step silently.
⚠️ STOPPING POINT: Wait for the learner's choice before proceeding.
Step 5: Lightweight Diagnostics
Check that the learner's environment can handle this Quickstart.
Does the role have CREATE SCHEMA/TABLE/VIEW privileges?
Is a warehouse set and active?
Does the Quickstart need specific features (Cortex, SPCS, Streamlit)?
Does the Quickstart need access to SNOWFLAKE_SAMPLE_DATA or ACCOUNT_USAGE?
Present findings:
If ready: "Your environment looks good for this Quickstart."
If gaps: List what's missing with specific GRANT statements to fix each one.
⚠️ STOPPING POINT: If issues found, present them. Ask the learner: "Want to fix these first, or proceed anyway?" Do not block — let them choose.
Step 6: Introduce and Choose Mode
Attribution:
"This is the [title from summary field] Quickstart."
Explain the deliverable:
Summarize what the learner will have at the end — the tables, services, apps, or models they'll build.
Nudge (CLI/Desktop only): Suggest opening Snowsight alongside the session, rendering their account URL from the diagnostics results: "You may want to open Snowsight to explore objects as we build them: https://app.snowflake.com/<org_name>/<account_name>"
Set up learning database:
CREATE DATABASE IF NOTEXISTS LEARN_SNOWFLAKE_QUICKSTARTS;
Ask permission before creating. Then create a schema named after the slug:
CREATE SCHEMA IF NOTEXISTS LEARN_SNOWFLAKE_QUICKSTARTS.<slug_as_identifier>;
Choose mode using ask_user_question:
Learner mode — Step by step. I'll explain what we're building at each stage, execute it, recap, and check in before moving on.
Builder mode — Build everything at once. I'll execute all stages and give you a full summary at the end.
Load references/teaching-guide.md for mode-specific behavior.
⚠️ STOPPING POINT: Wait for mode selection before proceeding.
Step 7: Execute Learning Journey
Execute each stage from the plan created in Step 3.
Detect the execution surface:
If the working directory is under /workspace/ → Snowsight workspace
Otherwise → CLI
Learner mode (CLI):
For each stage:
Explain what will be built and why
Render the SQL/Python/code directly in the terminal with explanatory comments so the learner can read and understand it
Use ask_user_question to give the learner agency before executing — e.g., "Run it", "Explain more", "I want to make changes"
Execute via sql_execute
Brief recap: what was created, key results (row counts, object status)
⚠️ STOPPING POINT — pause between stages
Learner mode (Snowsight workspace):
For each stage:
Explain what will be built and why
Write code to .sql or .py files with explanatory comments
Prompt the learner to run the file
Brief recap after they've run it
⚠️ STOPPING POINT — pause between stages
Builder mode (any surface):
CLI: execute all stages directly via sql_execute without pausing
Snowsight: write all files and tell the learner to run them in sequence
Only stop for optional stages (ask include/skip)
Full summary at the end
Handling outdated content:
If the Quickstart uses deprecated syntax or old patterns, flag it:
"Note: This Quickstart uses [old pattern]. The current recommended approach is [new pattern]. I'll use the modern approach."
Use the correct current approach — don't blindly replicate deprecated code.
Handling errors:
If a stage fails during execution:
Read the error
Diagnose the likely cause (permissions, missing prerequisites, syntax)
Suggest a fix or workaround
Ask the learner how to proceed
Step 8: Recap and Cleanup
After all stages complete:
Recap: Briefly congratulate the learner and summarize what they built — the key objects created, the concepts covered, and what they now have running in their account. Keep it concise (3-5 sentences). Draw from the Quickstart's Conclusion step if available.
Cleanup: Then ask the learner: "Want to keep everything, or clean up?"
If cleaning up: drop the schema (which drops all objects within it)
DROP SCHEMA IF EXISTS LEARN_SNOWFLAKE_QUICKSTARTS.<slug_as_identifier> CASCADE;
Never drop the LEARN_SNOWFLAKE_QUICKSTARTS database itself
Never drop or alter any Snowflake-provided databases
Stopping Points
⚠️ After companion repo detection (Step 4) — wait for clone/reference choice
⚠️ After diagnostics (Step 5) if environment issues found
⚠️ After mode selection (Step 6) — wait for learner's choice
⚠️ Between stages (Step 7, learner mode only)
⚠️ Before optional stages (both modes) — ask include/skip
