An Introduction to Generative AI for RSEs

Basic principles and tooling

Tom Meltzer

Matt Archer

2026-03-30

Plan

• ML basics
• Transformer inference and agentic AI overview
• Tooling overview and code demo
• Opencode intro and configuration
• Create your tool call with MCP + Skills

ML: The basics

• Loss function: measures model error
• Gradient descent: moves weights down the loss surface
• Backpropagation: computes gradients layer by layer
• Overfitting: memorises training data, fails to generalise

• working in a supervised context where we have a dataset of input-output pairs and we want to learn a function that maps inputs to outputs
• differentiable loss function quantifies how well the model’s predictions match the training data
• apply gradient descent to update model parameters to reduce the loss
• this is done with backpropagation - computes gradients to move down this loss surface
• One complexities of training a model is overfitting - when the model memorises the training data instead of learning general patterns, it performs well on training data but poorly on unseen data. Regularisation techniques and careful validation are used to mitigate this.
• I’m not going to talk about the details of training large transformer models, but it’s worth noting that overfitting is less of a concern for them than for classical ML models. Despite having billions of parameters, they generalise well due to vast and diverse training data, regularisation techniques, the double-descent phenomenon, and emergent representations that capture structure rather than surface patterns.

Overfitting is a major concern in classical ML, but large transformer models largely sidestep it. They have billions of parameters (far more than training examples), yet generalise well. Key reasons: (1) vast and diverse training data makes true memorisation impractical; (2) regularisation techniques such as dropout and weight decay are baked in; (3) the double-descent phenomenon: very over-parameterised models can re-enter a good-generalisation regime; and (4) emergent representations learned across billions of tokens capture structure rather than surface patterns.

ML: The basics

%%{init: {"flowchart": {"nodeSpacing": 15, "rankSpacing": 18}, "theme": "base", "themeVariables": {"edgeLabelBackground": "#ffffff"}}}%%
flowchart TD
    A([Training data]) --> B["Forward pass"]
    B --> C[Compute loss]
    C --> D[Backpropagation]
    D --> E[Update weights]
    E -->|repeat| B
    C -->|loss small enough| F([Done ✓])

    classDef io     fill:#6c757d,stroke:#495057,color:#fff
    classDef step   fill:#4b9cd3,stroke:#2c6e9e,color:#fff
    classDef key    fill:#003b6f,stroke:#001f3f,color:#fff

    class A,F io
    class B,C step
    class D,E key

These are the main components of the training loop for a supervised learning model. The model’s parameters (weights) are updated iteratively to minimise the loss function, which quantifies how well the model’s predictions match the training data. Backpropagation efficiently computes the gradients needed for weight updates, allowing the model to learn complex patterns in the data.

• Loss function: measures model error
• Gradient descent: moves weights down the loss surface
• Backpropagation: computes gradients layer by layer
• Overfitting: memorises training data, fails to generalise

LLMs: Tokenisation

LLMs cannot process raw text, it must first be converted to numbers.

• Text is split into sub-word tokens using a learned vocabulary
• Each token is assigned a unique integer ID
• Common words are single tokens; rare words split into pieces

“I went to the”

235285 “I” 3806 “▁went” 576 “▁to” 573 “▁the”

we’re dealing with text, but the model operates on numbers. So the first step is tokenisation: converting raw text into a sequence of token IDs.

We break text into sub-word tokens as otherwise the vocabulary would be too large. We can instead use the tokens as building blocks to represent any word. This makes the vocabulary more manageable and allows the model to handle rare or technical words by breaking them into pieces.

Tokenisation is the first step in the pipeline. The tokeniser is a separate component from the LLM — it ships as a vocabulary file and a set of merge rules (BPE or SentencePiece). The vocabulary size for Gemma is ~256k tokens.

Sub-word tokenisation means common words like “the” are a single token, while rare or technical words like “backpropagation” split into pieces: ▁back, prop, agation.

LLMs: Embeddings encode meaning

The embedding matrix maps tokens to vectors; directions encode meaning.

Attention enriches each vector with context: bank (river) vs bank (finance)

3Blue1Brown, Deep Learning Ch. 5

We need to covert tokens to vectors before the model can process them.

Why can’t we just feed token in directly, why do we need embeddings? This is because the model operates in a continuous vector space, not discrete token IDs.

The embedding matrix maps each token ID to a dense vector of numbers.

These vectors capture semantic meaning — similar words have similar embeddings. For example, “king” and “queen” might be close in embedding space, while “king” and “carrot” are far apart.

\(\text{king} - \text{man} + \text{woman} \approx \text{queen}\)

In practice this relationship isn’t very accurate because queen has multiple meanings. But the point is that directions in embedding space can encode meaningful relationships.

In this example if we look at the displacement between germany and japan, we see it is approximately the same as the displacement between bratwurst and sushi.

The food / country direction generalises across many pairs: pizza / Italy, tacos / Mexico, sushi / Japan. These patterns exist before attention runs. Attention enriches each vector with context, distinguishing “bank” (river) from “bank” (finance).

Transformers: Inference I

Transformers: Inference I

Convert text to tokens

Transformers: Inference I

Convert text to tokens

Predict new tokens

This box is doing a lot of work, but we can break it down (in the next section) into a few key steps:

Transformers: Inference I

Convert text to tokens

Predict new tokens

Convert tokens to text

Transformers: Inference II

Transformers: Inference II

“I went to the”

I ▁went ▁to ▁the

Transformers: Inference II

“backpropagation”

▁back prop agation

3 tokens

Transformers: Inference II

This is the LLM - the tokenizer sits outside of the model.

Converts to token ids.

Transformers: Inference II

begin by mapping token IDs to dense vectors using the embedding matrix. This is obtained during training and captures the static meaning of each token.

Transformers: Inference II

Token	ID	Embedding (2048 dims)
I	235285	[ 0.21, -0.83, 0.54, 0.12, … ]
▁went	3806	[ -0.44, 0.31, 0.09, -0.77, … ]
▁to	576	[ 0.67, 0.02, -0.51, 0.38, … ]
▁the	573	[ 0.55, -0.19, 0.73, -0.02, … ]

Each token ID maps to a vector of numbers. A positional signal is added so the model knows the order of tokens — “I went to the” is different from “the to went I”.

Transformers: Inference II

Transformers: Inference II

transformer block

Transformers: Inference II

transformer block

The transformer block is where all the interesting stuff happens. The key idea is self-attention: rather than processing tokens in sequence (like an RNN), every token attends to every other token in parallel.

This endows the embedding vectors with contextual information.

This lets the model capture long-range dependencies and scales well on modern hardware.

The MLP layers are a little different in that they capture facts and rules of language.

Self-attention

I went to the

“I” ↔︎ “went”: subject-verb   |   “went” → “to”: verb-preposition

Let’s look at a few examples:

The attention scores determine how much each token “looks at” the others when building its contextual representation. Syntactic example: “I” and “went” are linked by subject-verb agreement; “went” and “to” by verb-preposition dependency.

Self-attention

“The bank by the river was steep”

“bank” attends strongly to “river” - meaning is of a riverbank, not financial

and similarly, “bank” attends strongly to “river” so its output vector shifts toward the riverbank meaning rather than the financial one.

attention builds up lots of these relationships.

Transformers: Inference II

Transformers: Inference II

▁the → [ 0.55, -0.19, 0.73, … ]

× unembedding matrix (2048 × 256k)

→ logits for every token in vocab

→ softmax → sample

Token	Probability
▁library	31%
▁store	18%
▁park	12%
▁doctor	8%

Only “the” matters - it has been contextualised by attention.

At this point the word ‘the’ has been enriched with context by attention.

The model then applies the unembedding matrix to this vector, giving a score (logit) for every token in the vocabulary.

Basically a dot product similarity between the contextualised vector and the vocab vectors.

softmax converts these logits to probabilities, and the model samples the next token ID from this distribution.

During inference, we actually do this for every token in the sequence. This is obviously inefficient.

Get around this with a concept called KV caching, but that’s a topic for another day.

Why is there a limit on context length?

Transformers: Inference II

Transformers: Inference II

This is run autoregressively.

Autoregressive is a fancy way of saying “feed the output back in as input.” Each iteration appends the new token ID to the sequence and feeds the full sequence back in. Eventually the model generates an end-of-sequence token or hits max_new_tokens.

Maybe my arrow is a little misleading here.

Transformers: Inference II

[235285] [3806] [576] [573] → 4376 “▁library”

[235285] [3806] [576] [573] [4376] → 736 “▁this”

full sequence fed back in each loop

Each iteration appends the new token ID to the sequence and feeds the full sequence back in. Eventually the model generates an end-of-sequence token or hits max_new_tokens.

• Since the model processes the entire sequence on every forward pass, so longer inputs require more computation and memory. This is a fundamental limitation of the transformer architecture - it’s obviously inefficent to re-process the same tokens every time.
• It was also trained on sequences up to a certain length (e.g. 2048 tokens), so it may not perform well on much longer inputs.
• kv caching grows as O(n)
• computation grows as O(n^2) due to self-attention

Transformers: Inference II

Transformers: Inference II

[235285, 3806, 576, 573, 4376, 736]

↓ vocab lookup

“I went to the library this”

just a lookup table, the inverse of tokenisation

• Tokenise: text to sub-word token IDs
• LLM: token IDs enter the model
• Embed + pos. encoding: token IDs to dense vectors with position
• Self-attention + MLP × N layers: every token attends to every other
• Predict & sample: logits to softmax to sample next token
• Autoregressive: feed token back, repeat
• Decode: token IDs to text

The crucial innovation is self-attention: rather than processing tokens in sequence (like an RNN), every token attends to every other token in parallel. This lets the model capture long-range dependencies and scales well on modern hardware.

Sampling strategies: the model doesn’t always pick the most likely next token. Temperature scales the probability distribution (higher = more random). Top-k restricts sampling to the k most likely tokens. Top-p (nucleus sampling) samples from the smallest set of tokens whose cumulative probability exceeds p.

Transformers: Summary

• Tokenise: text → sub-word token IDs
• Embed: token IDs → dense vectors (static meaning)
• Self-attention: enrich each vector with context (dynamic meaning)
  • • MLP × N layers: transform representations
• Predict & sample: last token’s vector × unembedding matrix → next token ID
• Autoregressive loop: append token, feed full sequence back in
• Decode: token IDs → text (lookup table)

The key insight: the embedding matrix gives every token a static starting vector, and self-attention makes those vectors contextual. The model is stateless — all state lives in the sequence of token IDs fed in on each loop.

Transformers: Summary

• The model is completely stateless
• All context is in the text fed to it, there is no memory
• Each forward pass re-processes the full sequence
• Longer contexts are more expensive: attention is O(n²)

This has profound implications for how you use LLMs.

Long conversations get expensive because the full history is re-processed every time.

Context length is a hard constraint. Techniques like RAG, summarisation, and memory modules are all workarounds for this fundamental limitation.

In summary: it’s essentially a goldfish.

LLM Hello World

import os
from huggingface_hub import login
from transformers import AutoTokenizer, AutoModelForCausalLM

login(token=os.environ["HF_API_KEY"], add_to_git_credential=True)

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2b")

model = AutoModelForCausalLM.from_pretrained("google/gemma-2b")

input_text = "I went to the"
input_ids = tokenizer(input_text, return_tensors="pt")

outputs = model.generate(**input_ids, max_new_tokens=10, do_sample=True, top_p=0.9)
print(tokenizer.decode(outputs[0]))

LLM Hello World

import os
from huggingface_hub import login
from transformers import AutoTokenizer, AutoModelForCausalLM

login(token=os.environ["HF_API_KEY"], add_to_git_credential=True)

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2b")

model = AutoModelForCausalLM.from_pretrained("google/gemma-2b")

input_text = "I went to the"
input_ids = tokenizer(input_text, return_tensors="pt")

outputs = model.generate(**input_ids, max_new_tokens=10, do_sample=True, top_p=0.9)
print(tokenizer.decode(outputs[0]))

• huggingface_hub / transformers: The platform and library where the ML community collaborates on models, datasets, and applications.

LLM Hello World

import os
from huggingface_hub import login
from transformers import AutoTokenizer, AutoModelForCausalLM

login(token=os.environ["HF_API_KEY"], add_to_git_credential=True)

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2b")

model = AutoModelForCausalLM.from_pretrained("google/gemma-2b")

input_text = "I went to the"
input_ids = tokenizer(input_text, return_tensors="pt")

outputs = model.generate(**input_ids, max_new_tokens=10, do_sample=True, top_p=0.9)
print(tokenizer.decode(outputs[0]))

• huggingface_hub / transformers: The platform and library where the ML community collaborates on models, datasets, and applications.
• Login: Register with Hugging Face and obtain a key to download hosted models.

LLM Hello World

import os
from huggingface_hub import login
from transformers import AutoTokenizer, AutoModelForCausalLM

login(token=os.environ["HF_API_KEY"], add_to_git_credential=True)

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2b")

model = AutoModelForCausalLM.from_pretrained("google/gemma-2b")

input_text = "I went to the"
input_ids = tokenizer(input_text, return_tensors="pt")

outputs = model.generate(**input_ids, max_new_tokens=10, do_sample=True, top_p=0.9)
print(tokenizer.decode(outputs[0]))

• huggingface_hub / transformers: The platform and library where the ML community collaborates on models, datasets, and applications.
• Login: Register with Hugging Face and obtain a key to download hosted models.
• Load tokenizer & model: Downloads Google Gemma-2b and its matching tokenizer.

LLM Hello World

import os
from huggingface_hub import login
from transformers import AutoTokenizer, AutoModelForCausalLM

login(token=os.environ["HF_API_KEY"], add_to_git_credential=True)

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2b")

model = AutoModelForCausalLM.from_pretrained("google/gemma-2b")

input_text = "I went to the"
input_ids = tokenizer(input_text, return_tensors="pt")

outputs = model.generate(**input_ids, max_new_tokens=10, do_sample=True, top_p=0.9)
print(tokenizer.decode(outputs[0]))

• huggingface_hub / transformers: The platform and library where the ML community collaborates on models, datasets, and applications.
• Login: Register with Hugging Face and obtain a key to download hosted models.
• Load tokenizer & model: Downloads Google Gemma-2b and its matching tokenizer.
• Tokenise input: Converts your text into a tensor of token IDs the model can read.

LLM Hello World

import os
from huggingface_hub import login
from transformers import AutoTokenizer, AutoModelForCausalLM

login(token=os.environ["HF_API_KEY"], add_to_git_credential=True)

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2b")

model = AutoModelForCausalLM.from_pretrained("google/gemma-2b")

input_text = "I went to the"
input_ids = tokenizer(input_text, return_tensors="pt")

outputs = model.generate(**input_ids, max_new_tokens=10, do_sample=True, top_p=0.9)
print(tokenizer.decode(outputs[0]))

• huggingface_hub / transformers: The platform and library where the ML community collaborates on models, datasets, and applications.
• Login: Register with Hugging Face and obtain a key to download hosted models.
• Load tokenizer & model: Downloads Google Gemma-2b and its matching tokenizer.
• Tokenise input: Converts your text into a tensor of token IDs the model can read.
• Generate & decode: Model predicts tokens autoregressively; tokenizer converts them back to text.

By writing model.generate(**input_ids), you are telling Python: “Take every key in this dictionary and pass it to the function as a named argument.”

Agentic AI

AI Agents are essentially some scaffolding / loop around LLM(s):

• LLM: The reasoning engine. It can plan, evaluate, or decide whether to “act” or “answer.”
• System Prompt: Defines the persona, available tools, and operational boundaries.
• Working memory: Maintains the state, including history, tool outputs, and the current goal.
• Tools: External capabilities like web search, code execution, APIs, or connecting to RAG.

• The LLM is the core reasoning engine. It may also plan out a sequence of steps before action. i.e. CoT is a simple form of agentic reasoning. More complex agents can evaluate their own output and decide whether to “act” (e.g. call a tool) or “answer” (respond to the user).

• The system prompt. I.e. if it’s financial adviser - it can’t go off track and give medical advice.

• Working memory: this is held in the contenxt window. Might have to summarise as it goes.

• Tools allow the LLM to interact with the outside. It doesn’t execute code itself. It generates a tool call, the surrounding framework executes it, and the result is appended back into the context for the LLM to re-reason with.

• LLM is like a goldfish - completely stateless. All short term memory lives in the context window. The “loop” is managed by the surrounding application code, not the model.

Agentic AI

%%{init: {"flowchart": {"nodeSpacing": 40, "rankSpacing": 80}, "theme": "base", "themeVariables": {"edgeLabelBackground": "#ffffff"}}}%%
flowchart LR
    S([System prompt]) --> C
    H([Prompt]) --> C["Context window"]
    C --> L["LLM: generate text"]
    L --> D{Tool call?}
    D -->|yes| T["Tools (incl. RAG)"]
    T -->|result appended| C
    D -->|no| O([Output])

    classDef io      fill:#6c757d,stroke:#495057,color:#fff
    classDef core    fill:#003b6f,stroke:#001f3f,color:#fff
    classDef support fill:#4b9cd3,stroke:#2c6e9e,color:#fff
    classDef decision fill:#e9c46a,stroke:#f4a261,color:#000

    class S,H,O io
    class L core
    class C,T support
    class D decision

An agentic system wraps an LLM in a loop using lots of scaffolding to enable it to solve complex tasks.

We start with two inputs. The Prompt is what the user wants, but the System Prompt is where we’ve given the agent a persona, ‘You are a researcher with access to these specific tools.’ Both of these get combined into the Context Window.

The context window is limited in size so we have to be quite strategic about what goes in there. We can’t include the entire internet or all our documentation.

The LLM looks at the context window and decides: ‘Do I need a tool to answer this?’

If the answer is ‘Yes,’ the agent doesn’t talk to the user yet. Instead, it outputs a specific string (a Tool Call) that the scaffolding recognises. The scaffolding then executes a Skill—like running a Python script or a RAG search—and appends the result back into the window.

Only when the LLM decides it finally has enough information does it generate the final response for the user.”

The result of that tool—the data it found or the code it ran—is appended back into the Context Window.

Even though LLMs are entirely stateless, this loop is how we ‘fake’ memory. The LLM now sees the original prompt, its own decision to use a tool, and the tool’s result. It ‘re-reasons’ with this new information.

The LLM itself is stateless — all state lives in the context window. The “loop” is managed by the surrounding application code, not the model.

Self Study Resources

• 3Blue1Brown, Language Models Explained:
  • Chapters 4, 5, 6, 7
• Meridian Cambridge Transformer architecture, Agents

Further Reading

Foundational concepts and Transformers

• 3Blue1Brown: Neural Networks playlist (Sanderson 2017)

• Andrej Karpathy: Neural Networks: Zero to Hero (Karpathy 2022)

• Stanford CS25: Transformers United (Stanford University 2021)

• DeepLearning.AI: Build and Train an LLM with JAX (DeepLearning.AI 2024)

Further Reading

Reinforcement Learning & Alignment

• Hugging Face: Deep RL Course (Hugging Face 2022)
• OpenAI: Spinning Up in Deep RL (Achiam 2018)

Gen-AI Concerns

• Safety
• Ethical
• Environmental

Safety

• Amazon experienced several high-profile incidents
• AI-slop crippling maintainers e.g., curl
• Supply-chain infection e.g., LiteLLM
• Hard to debug semantically correct code

And these are just from a software perspective…

Ethical

• Staff layoffs under guise of genAI
• Copyright/piracy e.g., Anthropic $1.5bn settlement
• Data sovereignty (who owns your data)

Environmental

• Massive increase in water & energy consumption
• Accelerating E-Waste and Hardware Churn

Opinion

• GenAI usage has parallels to HPC
• If genAI can help science – I want to make it:
  • greener
  • safer
  • more ethical

Tools and Workflows

Opencode (CLI)

In this half of the training we will make use of opencode

Concepts can also be applied to similar tools e.g., VSCode, GitHub Copilot CLI etc.

Opencode Installation

Installation instructions here

• Linux

curl -fsSL https://opencode.ai/install | bash

• Mac

brew install anomalyco/tap/opencode

• Windows (download .exe)

Opencode Configuration

We now need to configure opencode to run self-hosted LLMs

1. Add API key to .basrhc (or equivalent) e.g.,
   export CAMLLM_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXX
2. Configure opencode (see next slide)

Note

If you already have access to UoC’s LiteLLM (https://llm.hpc.cam.ac.uk) you can create one from the virtual keys page: Virtual Keys \(\rightarrow\) Create New Key.

Opencode Configuration

• edit/create ~/.config/opencode/opencode.json

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cam-llm": {
      "options": {
        "baseURL": "https://llm.hpc.cam.ac.uk/v1",
        "apiKey": "{env:CAMLLM_API_KEY}"
      },
      "models": {
        "mistralai/Devstral-2-123B-Instruct-2512": {
          "name": "mistralai/Devstral-2-123B-Instruct-2512"
        },
        "Qwen/Qwen3-VL-30B-A3B-Instruct": {
          "name": "Qwen/Qwen3-VL-30B-A3B-Instruct",
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
  },
  "permission": {
    "bash": { "*": "ask" },
    "edit": { "*": "allow" }
  }
}

Context Engineering

• LLMs are powerful, but suffer from context bloat
• Context window is finite resource
• LOTR + Hobbit ~ 750k tokens / 100k LOC ~ 1M tokens

Model Name	Context Size
Claude 4.6 Opus	1M
Gemini 3.1 Pro	1M – 10M
GPT-5.3-Codex	400k
Devstral-2-123B-Instruct-2512	256k

Solution

To resolve this issue, Anthropic open-sourced 2 methods:

• Model Context Protocol (MCP) [November 2024]
• Agent Skills [December 2025]

MCP

• Open-source standard
• Connect LLMs to external systems

MCP examples

For example, opencode supports 11 built-in skills (see docs)

Note

LLMs can answer questions, but cannot interact with your system.

MCP example (add)

We will build our own using fastMCP

mcp-numbers.py

from fastmcp import FastMCP

mcp = FastMCP(name="mcp-numbers")

@mcp.tool
def add(a: int, b: int) -> int:
  """Add two numbers"""
  return a + b

if __name__ == "__main__":
  mcp.run()

MCP example (add)

1. Now let’s add mcp-numbers to our opencode configuration
2. Follow instructions in mcp/README.md
3. Running /status in opencode should display
4. Try Use mcp tool "numbers_add" to add 4 and -1

MCP examples (netcdf)

• What about a more interesting example…
• Can we give LLM power to inspect netcdf .nc files?
• Let’s try with MCP.

MCP examples (netcdf)

• Inspect file mcp/mcp-netcdf.py

mcp/mcp-netcdf.py

# /// script
# dependencies = [
#   "netCDF4",
#   "fastmcp",
# ]
# ///

import netCDF4
from fastmcp import FastMCP

# Initialize the FastMCP server
mcp = FastMCP("nc-mcp")


@mcp.tool()
def get_variables(path: str) -> str:
    """
    Reads a NetCDF file from the given path and returns its variables.

    Args:
        path: The absolute or relative path to the NetCDF (.nc) file.

    Returns:
        A string representation of the NetCDF file's variables.
    """
    try:
        # Open the dataset
        dset = netCDF4.Dataset(path)

        # Capture the variables as a string to return to the client
        variables_output = ", ".join(dset.variables.keys())

        # Close the dataset to free up resources
        dset.close()

        return variables_output

    except FileNotFoundError:
        return f"Error: Could not find the file at path: {path}"
    except Exception as e:
        return f"Error reading NetCDF file: {str(e)}"


@mcp.tool()
def get_variable_shape(path: str, variable_name: str) -> dict:
    """
    Reads a NetCDF file from the given path and returns the shape of a specific
    variable.

    Args:
        path: The absolute or relative path to the NetCDF (.nc) file.
        variable_name: The name of the variable to get the shape for.

    Returns:
        A dictionary containing the shape of the specified variable.
        Example: {'temperature': (365, 180, 360)}
        Returns an error if the variable is not found.
    """
    pass


if __name__ == "__main__":
    mcp.run()

MCP examples (netcdf)

• mcp/mcp-netcdf.py contains 2 MCP tools
  • netcdf_get_variables
  • netcdf_get_variable_shape (to be implemented)
• Try using netcdf_get_variables on file simple.nc

MCP examples (netcdf)

• Implement netcdf_get_variable_shape
• See stub in mcp/mcp-netcdf.py

mcp/mcp-netcdf.py

@mcp.tool()
def get_variable_shape(path: str, variable_name: str) -> dict:
    """
    Reads a NetCDF file from the given path and returns the shape of a specific
    variable.
    ...
    """
    pass

(15 minutes for exercise)

Skills

• Define reusable behavior via SKILL.md definitions
• Agent skills let LLMs discover reusable instructions
• Skills are loaded on-demand
• Skills are “just” markdown files

Anatomy of a Skill

• Many genAI tools support skills e.g., Claude code, opencode, codex etc.

Note

opencode requires that skills are stored in a specific set of locations (A full list can be found here). We will focus on these:

• Project config: .opencode/skills/<name>/SKILL.md
• Global config: ~/.config/opencode/skills/<name>/SKILL.md

<name>/               # Required: unique skill name
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Skills Example (netcdf)

• Let’s refactor our netcdf MCP tool as a skill
• Follow instructions in skill/README.md:

cd project/root/GenAI-teaching
mkdir -p .opencode/skills/netcdf
ln -sf $(pwd)/skill/netcdf/SKILL.md .opencode/skills/netcdf/

• Run /skills in opencode to check registration

Skills Example (netcdf)

skill/netcdf/SKILL.md

---
name: netcdf-processing
description: Use this skill for any operations involving NetCDF (.nc) files, including inspecting metadata, reading variable shapes, extracting data slices, or generating new NetCDF datasets.
---

# What I do

This skill provides guidance for inspecting and generating NetCDF files using
standard command-line utilities. Use these commands to understand dataset
structures before writing extraction scripts.

# When to use this skill

Use this skill whenever a user mentions climate data, multidimensional arrays,
.nc files, or atmospheric datasets.

## Workflow Decision Tree

- **Inspecting Schema**: Use `ncdump -h` first to understand dimensions.
- **Data Access**: If the file is large, only request specific variable slices (don't read entire arrays into context).
- **Creating Files**: Use `ncgen` for small CDL templates or `netCDF4` Python scripts for large datasets.

## Viewing Metadata with `ncdump`
`ncdump` is the standard tool for converting NetCDF binary files into
human-readable text (CDL format).

* **View Header Only (Recommended):** Displays dimensions, variables, and attributes without printing raw data.
    ```bash
    ncdump -h filename.nc
    ```
* **View Specific Variable:** Look at the data for a single variable (e.g., 'temperature').
    ```bash
    ncdump -v temperature filename.nc
    ```
* **Coordinate Formatting:** Use `-c` to see the header plus the values of coordinate variables (lat, lon, time).
    ```bash
    ncdump -c filename.nc
    ```

## Creating Files with `ncgen`
`ncgen` takes a text-based CDL file and compiles it into a binary `.nc` file.

* **Generate Binary from CDL:**
    ```bash
    ncgen -o output_file.nc input_text.cdl
    ```

Skills Example (netcdf)

Try running the following command

Note

Disable netcdf MCP server before trying to test the skill. They may conflict.

Skills Exercise

• Create your own SKILL.md
• Register it in opencode
• Try using it

(15 minutes for exercise)

Skills vs. MCP

So how do I choose between Skills vs MCP?

	MCP Server	SKILL.md (Instruction)
Primary Purpose	Tool calling – Interact with external services or perform short actions.	Domain Expertise – Provides workflows, rules, and domain knowledge.
Context/Loading	Loaded immediately into context window (regardless of query) reducing effective context window size.	Lazy loaded when needed. Will still impact context window.
Timeout	Timeout ~ 1-2 minutes. Ideal for short, quick function calls	No timeout.

Taking it further

• Live demo of profiling skill

Taking it further

• opencode and other genAI tools often support agents/sub-agents (see docs)
• Agents are specialized AI assistants that can be configured for specific tasks and workflows
• They allow you to create focused tools with custom prompts, models, and tool access
• More markdown 👀

Sub-Agent

• Let’s create a sub-agent to generate PR messages
• Use opencode agent create
• Try creating your own
• Modify it and see what difference it makes

(15 minutes for exercise)

Thanks for listening

References

Achiam, Joshua. 2018. Spinning up in Deep Reinforcement Learning. OpenAI. https://spinningup.openai.com.

DeepLearning.AI. 2024. Build and Train an LLM with JAX. Online course, DeepLearning.AI. https://learn.deeplearning.ai/courses/build-and-train-an-llm-with-jax/lesson/gy364z/introduction.

Hugging Face. 2022. Deep Reinforcement Learning Course. Online course. https://huggingface.co/learn/deep-rl-course.

Karpathy, Andrej. 2022. Neural Networks: Zero to Hero. YouTube playlist. https://www.youtube.com/playlist?list=PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ.

Sanderson, Grant. 2017. Neural Networks. YouTube playlist, 3Blue1Brown. https://www.youtube.com/playlist?list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi.

Stanford University. 2021. CS25: Transformers United. Stanford University Course. https://web.stanford.edu/class/cs25/.