Your First Session

A guided walkthrough of Claude Code basics

Opening a Terminal

If you have never used a terminal before, this section is for you. A terminal is a text-based interface to your computer. Instead of clicking on folders and files, you type commands. It looks intimidating at first, but for this workshop you only need a handful of commands.

How to open it

  • Mac: Open the Terminal app (search for “Terminal” in Spotlight, or find it in Applications > Utilities)
  • Windows: Open PowerShell (search for “PowerShell” in the Start menu). If you installed Windows Subsystem for Linux (WSL), you can also search for “Ubuntu” or “WSL.”
  • Linux: You already know how to do this.

You should see a blinking cursor waiting for you to type something. This is your prompt.

Other useful commands

Most basic commands work the same on Mac, Linux, and Windows PowerShell. The main exception is listing files:

Task Mac / Linux Windows (PowerShell)
List files ls ls or dir
Go up one level cd .. cd ..
Show current directory pwd pwd
Create a new folder mkdir foldername mkdir foldername
Windows note

PowerShell supports ls and pwd as aliases, so most commands in this workshop will work as written. If something does not work, try dir instead of ls. If you installed Git for Windows, you also have Git Bash, which behaves like a Mac/Linux terminal and may be easier to follow along with.

Try typing ls after you cd into the claude_workshop folder. It should be empty for now — Claude Code will fill it in once you launch it in the next section.

If you get lost

Type pwd to see where you are. Type cd ~ to go back to your home folder and start over.

Launch Claude Code

From inside claude_workshop, launch Claude Code in your terminal:

claude

You should see the > prompt — this is Claude Code’s prompt, not your terminal’s. From here on, almost everything you type goes into Claude Code, not your terminal. Whenever a code block on this page starts with >, that’s a prompt for Claude.

Let Claude Code Set Up the Workshop

Your claude_workshop folder is empty right now. Let’s have Claude check what’s on your machine and set up everything we need for the workshop.

1. Check Python

What version of Python is installed on this machine, and is the venv
module available? If anything is missing, tell me how to fix it.

Claude Code will run python3 --version and python3 -m venv --help, report what it found, and tell you what to do if Python isn’t there or is too old. (On most machines you will already have what you need.)

2. Clone the LINCS skills repository and install the skills

Clone https://github.com/jburnford/lincs_skills.git into this folder as a
subfolder called lincs_skills/, then copy the contents of
lincs_skills/.claude/skills/ into .claude/skills/ in this workshop folder
so the slash commands like /cidoc-crm will work here.

This pulls in the seven LINCS-specific skills (CIDOC-CRM, the LINCS application profile, place/person disambiguation, validation, neo4j-to-RDF, and SPARQL templates) and installs them as project-local skills for claude_workshop.

Why the copy step?

Claude Code looks for skills under .claude/skills/ in the directory you launched it from, not inside arbitrary subfolders. The lincs_skills repo ships its skills under its own .claude/skills/, but when it sits as a subfolder of claude_workshop Claude Code does not see them. Copying them up to claude_workshop/.claude/skills/ makes the slash commands resolve.

3. Create a Python virtual environment and install workshop packages

Create a Python virtual environment at .venv/ in this folder, then
install pandas, openpyxl, matplotlib, geopandas, rdflib, requests,
and internetarchive into it. Use that venv for any Python you run for
the rest of the session.

Claude Code will run python3 -m venv .venv, ask permission, install the packages with pip into the new venv, and then keep using that venv for everything that follows. The install takes a couple of minutes (about 100–200 MB of downloads). If Claude Code seems to forget about the venv later, just remind it the same way.

The internetarchive package is what Claude will use for the second exercise below to download items from archive.org.

If pip install fails

On a locked-down machine, pip install may fail with a permissions error if Claude tries to install into system Python. If that happens, tell it: “Make sure you are installing into the .venv, not system Python.” Once it activates the venv first, the install should succeed.

4. Download the workshop data

Download workshop-data.zip from
https://github.com/jburnford/claude_code_workshop/releases/download/workshop-data-2026-04/workshop-data.zip
and unzip it into a data/ subfolder so the files end up at
data/canada_boundaries_temporal.gpkg, data/boundaries_poly.csv,
and data/boundary_changes.csv.

5. Write the workshop ground rules into CLAUDE.md

Claude Code reads any file called CLAUDE.md in the project directory at the start of every session, so it is the right place to put project-wide instructions you do not want to repeat each time. Ask Claude Code to create one for you:

Create a CLAUDE.md in this folder with the following workshop ground rules,
and follow them yourself for the rest of this session:

1. Always save Python code to a .py file inside this folder before running it.
   Do not run Python with `python -c "..."`, do not pipe scripts via stdin,
   and do not use bash heredocs to execute Python. Every script must exist
   on disk so it can be re-run, version-controlled, and inspected later.
2. Always run Python through the .venv in this folder. If the venv is not
   active, activate it before running anything.
3. When you are about to install a Python package, install it into .venv
   using pip --- never into system Python.
4. Do not insert Wikidata QIDs or other authority URIs into RDF/Turtle
   output unless you have looked them up against a live source. If you
   are not sure, mint a LINCS URI instead.
5. When the user asks for an analysis, prefer producing a script + its
   output over a one-off shell command. Reproducibility matters for
   academic work.
Why this matters

By default, Claude Code will sometimes run Python code inline using python -c "..." or by piping a script through stdin. This keeps the project folder tidy, but it leaves no trace of how a result was produced — which is fatal for academic work where you need to be able to re-run, share, and cite the exact analysis. The CLAUDE.md rule above forces every script onto disk so you (and your future self, and your reviewers) can see what was actually done.

When it’s done, your folder should look like this:

claude_workshop/
├── .claude/
│   └── skills/             ← /cidoc-crm, /lincs-profile, etc. live here
├── .venv/
├── lincs_skills/           ← cloned repo, source of the skills
├── data/
│   ├── canada_boundaries_temporal.gpkg
│   ├── boundaries_poly.csv
│   └── boundary_changes.csv
└── CLAUDE.md               ← workshop ground rules, auto-loaded each session

You only ever do this setup once. From now on, any time you reopen the workshop, you just cd claude_workshop && claude and pick up where you left off — the ground rules in CLAUDE.md are reapplied automatically.

Try Some Basic Commands

Now that the workshop folder is set up, try a few simple things to get a feel for how Claude Code works.

Ask it to read a file

Read lincs_skills/README.md and summarize what's in this repository.

Claude Code reads the file directly from disk — no copying, no pasting. It reports back and waits for your next instruction.

Ask it a question

What is CIDOC-CRM and why is it used for cultural heritage data?

It draws on its general knowledge. Later, when we load the CIDOC-CRM skill, its answers become much more precise.

Essential Commands

Command What it does
/help Show available commands
/exit End the session
/clear Clear conversation history
/compact Compress conversation to save context space

How Permissions Work

Claude Code asks before taking any action on your system. You will see prompts like:

Claude wants to run: python3 analyze.py
Allow? (y/n/a)
  • y — allow this one time
  • n — deny
  • a — allow this type of action for the rest of the session
Tip: “Accept All” during the workshop

Pressing a when prompted saves time during the workshop. But get in the habit of reading what Claude Code wants to do before approving, especially for commands. The permission system is a safeguard, not a guarantee — if you approve a destructive command without reading it, there is no undo.

A Real Task: Quebec Arrivals, 1817–1839

Toy examples get boring fast. Let’s give Claude Code a real historical dataset and watch it figure out the rest. The Quebec Arrivals Database is an open dataset of 17,783 ship arrivals at Quebec City between 1817 and 1839, transcribed from The Quebec Gazette / La Gazette de Québec. It lives on Zenodo at https://doi.org/10.5281/zenodo.15068764.

Copy this into Claude Code:

Download the Quebec Arrivals dataset from
https://doi.org/10.5281/zenodo.15068764 into a data/ folder.
Then tell me the top 5 merchants and the top 5 ports of departure,
and how each of them changed over the period covered by the dataset.

Hit Enter and watch what happens.

Claude Code will figure out how to resolve the DOI, download the Excel file, read it, group and count the columns, and report back. It may need to install a small Python package to parse .xlsx — approve the permission when prompted. If it asks how you’d like the changes-over-time presented, suggest a table or a chart.

Now Refine It

Once it has answered, push it further. Each follow-up builds on what it already knows:

Show me each merchant's arrival count year by year between 1820 and 1835 as a table.
Show me the dominant port of departure for each year as a list, sorted chronologically.
Save a chart of the top 5 ports by year as data/ports_over_time.png.

This is the analysis pattern you will use throughout the workshop: hand Claude Code a dataset, ask for specific summaries or visualisations, then refine. The historical interpretation — what the patterns mean — is your job, not Claude’s.

A Second Task: Grab 10 Things from the Internet Archive

The first task was about analysis. This one is about file wrangling — using Claude Code to talk to a public API and pull files down to your machine. No setup, no API keys, no installed packages — just describe what you want in plain English.

Copy this into Claude Code:

Download 10 items about Saskatoon from the Internet Archive into a new
data/archive/ folder. For each item, save the title, date, and a short
description so I can see what you got.

That’s it. No URL, no field names, no script. Hit Enter and watch what happens.

Claude Code will:

  • Figure out that the Internet Archive has a search API (and which endpoint to use)
  • Write a small script or shell loop to query it
  • Ask permission to run the script
  • Create the data/archive/ folder
  • Pull the items and report back with a summary

You will see permission prompts along the way. Read each one — if it looks reasonable, press y (or a to allow that command for the rest of the session).

Now Refine It

Once it’s done, try adding follow-up instructions. Each one builds on what Claude Code already knows about the folder you just created:

Show me the titles and dates as a table
Skip any item over 50 MB and re-download
Now do the same thing for "Regina" instead of "Saskatoon"

You don’t have to finish your thought before pressing Enter. If Claude Code does something you didn’t intend, just tell it:

Actually, only keep items from before 1950

It remembers what you’ve done so far and adjusts.

What just happened

In a handful of plain-English prompts, you:

  1. Hit a real third-party API
  2. Got a working script written and executed for you
  3. Saved real files to your machine
  4. Iteratively shaped the result without ever opening a code editor

This is the workshop in miniature. You describe a goal, Claude Code picks an approach, you inspect the result, and you refine. The same pattern works for everything that follows.

Ask Questions — Lots of Them

The best way to learn is by asking Claude Code questions. If you do not understand something — a Python error, a file format, what a column means — ask. If you are not sure how to approach a task, describe what you want and let Claude Code suggest an approach. There is no cost to curiosity here. The more you ask, the more you learn, and the better Claude Code understands what you are trying to do.

When It Gets Something Wrong

Claude Code will sometimes make mistakes. Correct it directly:

That's not right --- the JSON response wraps the list under
response.docs, not at the top level. Re-read the file and try again.

It adjusts and remembers the correction. This is a normal part of working with any LLM.

Exercise: Explore on Your Own (5 minutes)

Pick whichever dataset you found more interesting and push it further. A few ideas:

Quebec Arrivals

  1. Ask Claude Code to count the arrivals by month across the whole period and produce a table.
  2. Ask it to map the top 10 ports of departure to modern country names.
  3. Ask it to filter to ships carrying timber and list the top 10 ports for the timber trade.

Internet Archive

  1. Re-run the search with a different term — your hometown, a historical figure, a publication.
  2. Ask Claude Code to pull the OCR text from any “texts” items and report the most common nouns.
  3. Ask it to produce a citation table with author, title, year, and format for all 10 items.

When you are comfortable with the basics, move on to GIS Data Exercises.