Setup
Before beginning the exercises, configure a dedicated project directory with an active coding agent. You only need to perform this setup once; subsequent tutorial modules assume this environment is in place.
Each demo step specifies its required starting state, allowing you to jump directly into any exercise (Restore a starting point).
Quickstart
An automated setup script installs the sample data and configures a coding agent (Kiro CLI). Use the command for your platform.
macOS, Linux, or Windows via WSL (bash):
curl -fsSL https://peterchang77.github.io/agent-ai-skills/install.sh | bash -s -- --scenario clinical
Windows (PowerShell, no WSL needed):
& ([scriptblock]::Create((irm https://peterchang77.github.io/agent-ai-skills/install.ps1))) -Scenario clinical
The script performs the following actions:
- Prompts for configuration preferences: Confirms the destination directory (defaulting to
~/workshop-demo), asks whether to set up intermediate checkpoints, and checks whether to install the agent. - Retrieves the benchmark dataset: Downloads the synthetic clinical dataset, verifies data integrity against SHA-256 checksums, and unpacks the archive into your chosen directory.
- Configures the agent: Downloads and runs the official agent installer after displaying the source URL. This step is skipped if an agent is already detected.
- Ensures idempotent execution: Re-running the script updates missing files without overwriting local modifications unless you explicitly pass the
--forceflag (-Forcein PowerShell) (which creates a timestamped backup before replacing files).
Once the script completes, change into the project directory and launch your agent:
cd ~/workshop-demo
On Windows PowerShell the default folder is $HOME\workshop-demo.
If you chose a custom folder, use that path wherever this guide references ~/workshop-demo. Advanced flags can be passed after bash -s -- (for example, bash -s -- --scenario clinical --dir ~/my-folder --yes --checkpoints --no-agent); pass --help to inspect all options. In PowerShell, run the script as a script block to pass options: & ([scriptblock]::Create((irm https://peterchang77.github.io/agent-ai-skills/install.ps1))) -Scenario clinical -Dir C:\work -Yes -Checkpoints -NoAgent.
[!NOTE] Review network scripts before execution: you can inspect the installer source at install.sh or install.ps1. The workshop dataset is completely synthetic; before using institutional or clinical data, consult Privacy and data handling.
Custom setup
If you prefer to configure your workspace manually, use an alternative agent, or operate within a restricted computing environment, follow these steps:
1. Install an agent
Install your preferred agent harness following the vendor's official documentation. Most tools provide straightforward command-line installation instructions. Always review third-party scripts before execution. For architectural trade-offs between different harnesses, see Harnesses and models. Verify institutional approval before analyzing sensitive or regulated datasets (Privacy and data handling).
2. Create a project directory
An agent scopes its filesystem context to the directory where it is launched. Always initialize a dedicated folder for your project:
mkdir -p ~/workshop-demo # create project directory
cd ~/workshop-demo # enter directory
pwd # verify current path
On Windows PowerShell:
mkdir $HOME\workshop-demo # create project directory
cd $HOME\workshop-demo # enter directory
pwd # verify current path
Use ls (also available in PowerShell) to audit local contents. For additional guidance on permissions, directory navigation, and shell safety, refer to the Linux command line guide.
3. Verify local software dependencies
Check whether essential system utilities and compilers are available:
uv --version # Python environment and package manager
pdflatex --version # required for PDF report compilation
pandoc --version # required for Word document conversion
These commands work the same in PowerShell. On Windows, pdflatex is provided by MiKTeX or TeX Live.
During Prepare your environment, the agent will audit these dependencies and propose installation commands for missing tools (Environment). Always inspect and approve system-level installations deliberately.
4. Populate scenario data
Follow Your scenario's data below to unpack or build the dataset files. (The automated quickstart performs this step for you.)
Restore a starting point
Each demo exercise defines the prerequisite state it expects, such as the raw data kit or an intermediate checkpoint representing earlier analytical progress. A checkpoint is a self-contained snapshot of the project directory.
To reset your workspace to a clean checkpoint:
rm -rf ~/workshop-demo && mkdir ~/workshop-demo # ensure the target folder is disposable before removing
cp -r <scenario folder>/checkpoints/<name>/. ~/workshop-demo/
cd ~/workshop-demo
On Windows PowerShell:
Remove-Item -Recurse -Force $HOME\workshop-demo -ErrorAction SilentlyContinue # ensure the target folder is disposable first
Copy-Item -Recurse <scenario folder>\checkpoints\<name> $HOME\workshop-demo
cd $HOME\workshop-demo
If you ran the quickstart with --checkpoints, snapshots are pre-downloaded to ~/workshop-demo-checkpoints/<name>/ ($HOME\workshop-demo-checkpoints\<name> on Windows), which replaces <scenario folder>/checkpoints/<name> in the snippet above.
After copying the files, start the agent inside that folder. Maintaining an untouched copy of the data archive allows quick resets between exercises, while version control provides the same safety for your ongoing work.
Expected variance in agent outputs
Large language models generate non-deterministic outputs. Two runs will frequently follow slightly different execution paths, generate different helper filenames, or format code uniquely. This variance is expected. Each demo module provides explicit validation criteria and reference benchmarks so you can verify that the final analytical result is correct regardless of the specific route taken.
Your scenario's data
Scenario: Clinical: clinic network
A synthetic dataset for a three-clinic network, with every common file format and deliberate problems to find. It is
safe to share and is not real patient data. The files live in scenarios/toy/kit/ in this repository.
The story. You are the analyst. The memo in clinic_notes.txt asks three things: which clinics meet their
HbA1c targets; whether the Hillcrest call pilot increased HbA1c rechecks (and a one-page abstract with references);
and, if time allows, whether Northside's Saturday hours reduced urgent visits.
Get the kit
The quickstart installer downloads these files for you. To copy them by hand instead, from the repository's agent-workshop/ folder:
cp -r scenarios/toy/kit/. ~/workshop-demo/
cd ~/workshop-demo && ls
On Windows PowerShell:
mkdir $HOME\workshop-demo -Force
Copy-Item -Recurse scenarios\toy\kit\* $HOME\workshop-demo
cd $HOME\workshop-demo; ls
| File | Format | What it is |
|---|---|---|
clinic_notes.txt |
TXT | An operations memo with the three questions to answer |
data_dictionary.md |
MD | Column meanings and units |
clinic_visits.csv |
CSV | About 7,500 visits across three clinics, with data-quality problems |
pilot_calls.csv |
CSV | Patients called by the Hillcrest follow-up pilot |
clinic_targets.xlsx |
XLSX | 2025 targets and planned staffing, formatted for people |
pilot_protocol.docx |
DOCX | The pilot's eligibility rules and outcome definition |
patient_newsletter.pdf |
A text-only patient newsletter | |
clinic_directory.html |
HTML | A web page with clinic hours and announcements |
staffing.db |
SQLite | Monthly staffing by clinic |
visit_notes.csv |
CSV | 200 short free-text visit notes (for the bulk-inference step) |
visit_notes_labeled_sample.csv |
CSV | Correct categories for the first 30 notes |
Checkpoints
Restore one of these (how) to start a step without doing the earlier ones.
Checkpoint (in scenarios/toy/checkpoints/) |
Contains |
|---|---|
| (the kit itself) | The original files only |
cleaned |
Kit + scripts/clean_visits.py, data/clean/visits_clean.csv, out/cleaning_flow.md, notes/cleaning-decisions.md |
cohort |
cleaned + AGENTS.md, out/cohort.csv, out/cohort_flow.md |
analyzed |
cohort + scripts/analyze_pilot.py, out/pilot_results.md, references.bib, refs/search-log.md |
scenarios/toy/extras/ holds a reference PubMed helper (pubmed_refs.py) and a verified references.bib for the
literature steps, in case you cannot reach the network.
Everything here is synthetic. The numbers illustrate methods and are not findings about any real population.