Creating written tutorials can be a time-consuming and error-prone process, especially when done manually. The AGENTS.md file provides a structured approach to automate this process using AI assistants like Claude, ChatGPT, or Cursor AI.

This tutorial walks you through the complete workflow of using AGENTS.md to convert input Jupyter notebooks into properly formatted Snowflake Guides that follow official guidelines.

The AGENTS.md file provides instruction and sets of rules to AI coding agents, following the standard format defined at https://agents.md/. This standardized format ensures that AI assistants can reliably interpret and follow project-specific guidelines.

The Snowflake Guides AGENTS.md as proposed herein combines this standard format with specific instructions from two official Snowflake resources:

1. Get Started with Guides - The official Snowflake Guides creation guide
2. Markdown Template - The official template structure from the sfquickstarts repository

While the official markdown template can be used directly to create guides, the AGENTS.md file adds additional value by including:

By the end of this tutorial, you'll be able to:

The AGENTS.md file is an instruction set that guides AI assistants through the Snowflake Guide conversion process. It contains:

This section covers the key structural elements that make up a properly formatted Snowflake Guide.

Every guide begins with metadata. Here's what it looks like:

The official Snowflake Guides template defines the specific structure that every guide must follow:

1. Overview (with subsections)

   • What You'll Learn
   • What You'll Build
   • Prerequisites

2. Main Content Sections (H2 headings)

3. Conclusion And Resources

   • What You Learned
   • Related Resources

Categories must come from the approved lists stored in AGENTS.md. Here's how the agent selects them:

"Quickstart" is a content type category that must be included in every guide:

Other content types include: Community Solution, Partner Solution, and Certified Solution.

For the Semantic View guide, we matched:

1. Product Categories - AI, Analytics, Data Engineering, Platform
2. Technical Use-Cases - Ingestion, Transformation, Business Intelligence
3. Prioritized Features - Cortex Analyst, Snowpark, Dynamic Tables
4. Industries - Financial Services, Healthcare, Retail

Before finalizing, the agent runs the generated guide through this checklist provided in AGENTS.md:

The AGENTS.md specifies exactly how to package the generated guide.

1. Folder name = id field value
2. File name = id field value + .md
3. Package = ZIP file containing the folder
4. Delivery = Download ZIP file (i.e. depending on the AI assistant, it may only allow Copy/paste of file contents)

Let's walk through how the Semantic View guide was created:

Enter the following into the chat box:

After a few moments, the AI will ask:

I'll go ahead and enter my name:

Next, the AI asks:

I'll proceed with referencing the file by entering @ followed by the Jupyter notebook filename (without spacing after the @ character):

The AI performs the following tasks:

After initial generation, we refined:

Ran through the validation checklist and confirmed all items passed.

Upon completion, the AI will say:

This is followed by details of the generated guide:

Here are some key best practices:

The input notebook serves as the single source of truth for generation of Snowflake Guides. A well-structured notebook contains two essential components that form the core of any guide:

The AI extracts both components from the notebook and transforms them into the guide format—documentation becomes explanatory prose, and code snippets are preserved exactly as written.

Example: The Semantic View guide was generated from this Jupyter notebook:

The AGENTS.md enforces strict rules to prevent AI hallucination and ensure all content comes exclusively from the provided input notebook:

Why this matters:

Example: If the source notebook shows a specific SQL query, that exact query must appear in the guide—not a "cleaned up" or "improved" version.

After AI generates the guide, fact-checking against official documentation is critical. The AGENTS.md includes explicit guidance for this in the Iteration section:

What to verify:

1. Technical claims - Verify SQL syntax, function names, and parameter descriptions against Snowflake Documentation
2. Links - Ensure all URLs in Related Resources are valid and point to current documentation
3. Terminology - Confirm Snowflake-specific terms match official naming conventions

Example from Semantic View guide:

During fact-checking, we verified the CREATE SEMANTIC VIEW components against the official documentation:

Images and screenshots can be added after the guide has been generated through:

1. Manual addition - Capture screenshots and add them to the markdown with proper formatting:

   ![description of image](https://www.snowflake.com/content/dam/snowflake-site/developers/guides/create-snowflake-guides-with-agents-md/image-name.png)
   

2. Additional vibe coding rounds - Ask the AI to suggest where images would be helpful and what they should show, then capture and add them

Image requirements from AGENTS.md:

1. Format SQL keywords - Use backticks: JOIN, WHERE, GROUP BY
2. Keep H2 headings short - 3-4 words maximum
3. Use tables for structured data - Quick reference, comparisons
4. Add summaries - Brief descriptions before/after code blocks

1. Verify all links - Check that documentation URLs are valid
2. Include multiple resource types - Docs, quickstarts, GitHub repos
3. Add context - Explain why each resource is relevant

1. Review generated content - AI may need corrections
2. Add missing context - Output examples, explanations
3. Fact-check technical claims - Verify against official docs

Once your guide is validated and ready, submit it to the official Snowflake repositories on GitHub.

1. Fork the snowflake-demo-notebooks repo
2. Create a folder with your notebook name (use underscores, e.g., Snowflake_Semantic_View_Business_Ready_Queries)
3. Add your .ipynb file and any supporting files
4. Submit a Pull Request

1. Fork the sfquickstarts repo
2. Navigate to site/sfguides/src/
3. Extract your ZIP file (creates the folder with your markdown file)
4. Submit a Pull Request

Congratulations! You've successfully learned how to use the AGENTS.md file to create Snowflake Guides. You now understand the complete workflow from providing a source document to generating a properly formatted, validated guide.

AGENTS.md:

Official Snowflake Guides Resources:

Example Guides:

Example Notebooks:

Publishing Your Work:

Happy creations!