Skip to main content

Part 2 — First Steps with an AI Agent

Friendly Introduction to Agentic AI for Social Scientists

Published

November 6, 2026

Part 2 — First Steps with an AI Agent

Your agent is set up. Now put it to work: on your Word drafts, on a PDF you know well, and on a small analysis whose numbers you check yourself

Before you start

This is Part 2 of the mini course Friendly Introduction to Agentic AI for Social Scientists. It assumes you have done Part 1 — Setup: the Claude desktop app works, your first-project folder is open in the Code tab in Manual mode, Python is set up, and Typora opens .md files.

Part 2 takes about an hour. The step numbers continue from Part 1.

NoteWhat you will have at the end

Step 6 — Working on Word documents

Most of your writing lives in Word, and so does your coauthors’. The agent can read Word files, comment on them, edit them and produce new ones. The routine below keeps you in control: the agent never touches your original, and you see every change it made as tracked changes in Word.

Getting started. Copy a Word document you know well into your project folder, in a subfolder docs/ (a paper draft, a grant proposal, a referee report you wrote). Use something that is not confidential.

Ask for comments, not changes

The safest first use. Nothing is edited.

Read docs/draft.docx. Do not change it.
Give me the ten most important comments on the argument, structure and
clarity, most important first. For each, say which section or paragraph
it refers to. Save the list as docs/draft_comments.md.

Open the comments in Typora. Some will be useful, some generic, a few wrong. That ratio tells you a lot about how to use the agent.

Ask for edits, then review them as tracked changes

Make a copy of docs/draft.docx called docs/draft_v2.docx. In the copy only:
fix grammar and typos, and split sentences longer than 40 words.
Do not change the argument, the citations or the numbers.
Keep all formatting, footnotes and comments.
When done, list the kinds of changes you made.

Then let Word show you exactly what changed:

  1. Open Word (the desktop program; Word in the browser cannot compare). On the Review tab, click Compare, then Compare… on Windows or Compare Documents on Mac.
  2. As Original document, choose draft.docx. As Revised document, choose draft_v2.docx.
  3. Word opens a new document with every change of the agent as a tracked change. Accept or reject them one by one, as you would with a coauthor.

This is a standard Word feature, so there is nothing new to learn. It is also a good habit for checking: if the agent changed something you did not ask for, you will see it.

Write in Markdown, finish in Word

For new text (a memo, a section, a report), it is good practice to draft and revise in Markdown with the agent, and convert to Word only at the end. The agent works best with plain text, and its changes are easy to follow there.

Convert docs/memo.md to docs/memo.docx.
Use docs/my-template.docx for the styles (fonts, headings, margins).

For my-template.docx, take any Word file whose look you like (your university’s template, a past paper) and put it in docs/. The agent copies its styles, not its text.

Margin comments

You can also ask: “Put your comments as Word comments in the margin of docs/draft_v2.docx.” This usually works. If the result looks odd, go back to the list of comments in a Markdown file, which always works.

Step 7 — Give the agent standing instructions: AGENTS.md

Each session with the agent starts from zero. It does not remember yesterday. So we write down, once, what it should always know: who you are, how you like to work, what it must never do. This file is called AGENTS.md and sits in the project folder. The agent reads it at the start of every session.

I prepared a starter file based on how I work with agents. Ask the agent to fetch it and set up the folders:

Download this file exactly (use a download command, do not retype it) and
save it as AGENTS.md in this folder:
https://raw.githubusercontent.com/gabors-data-analysis/da-w-ai/main/friendly-agentic-ai-intro/starter/AGENTS.md

Then create the folders it describes (data/raw, data/clean, code, output, docs)
and summarize the instructions for me in five bullet points.

Then open AGENTS.md in Typora and edit the “About me” section: your field, what you work on, anything the agent should know about you. It is your file.

# Instructions for the AI agent in this project

The agent reads this file at the start of every session. Edit it freely.
When the agent makes the same mistake twice, add a line here.

## About me

- I am a social scientist (EDIT: field, e.g. sociology, political science, economics).
- I have used AI as a chatbot, mostly for text. I have not written code before.
- Explain what you do in plain language. The first time you use a technical term,
  give a one-line definition.
- Use Python for code, unless I ask for R or Stata.

## How to work with me

- For any task with more than a few steps, first show me a short plan and wait for my OK.
- Do the smallest thing that answers my request. Ask before adding extras.
- Work in small steps. Stop at natural break points and tell me what you did and what is left.
- If my request is unclear, ask one question rather than guessing.
- When you finish, say what you did not do or could not check.

## Safety with my files

- Never delete files. If something should go, move it to `_old/` and tell me.
- Never change anything in `data/raw/`. Raw data stays as it arrived.
- Never overwrite a Word, Excel or PDF file I gave you. Save your changes as a new
  file with `_v2` (or the next number) at the end of the name.
- Install Python packages only inside this project's environment (`.venv`).
  Ask before installing anything for the whole computer.
- Do not upload my files or data to any website or online service.

## Data and numbers

- Never make up numbers, references, quotes or sources. If you cannot verify something, say so.
- When you report a number, say where it comes from (which file, which script, which web page).
- Check your own results: count rows before and after each step, and compare a few
  values by hand with the source.
- Log analytical choices in `DECISIONS.md` (see the `decision-log` skill).

## Folders and files

- `data/raw/` original data, never edited
- `data/clean/` cleaned data, produced by code
- `code/` scripts, numbered in the order they run: `01_get_data.py`, `02_clean.py`, ...
- `output/` figures (PNG) and tables
- `docs/` notes, memos and drafts. Write new text in Markdown (`.md`);
  convert to Word only when I ask.
- Every result must be reproducible: running the scripts in order rebuilds all outputs.

## Writing

- Plain, direct prose. Short sentences. No hype words (delve, crucial, landscape,
  comprehensive, shed light on).
- Say what the data shows, then the caveats. Talk about associations, not effects,
  unless the design allows a causal reading.

## PDFs

- To read a PDF, first extract its text to a `.txt` file, then work from the text
  (see the `read-pdf` skill).

The main rules, in short: show a plan before longer tasks; do the smallest thing that answers the request; never delete files (move them to _old/); never overwrite your Word files or raw data; never invent numbers or references; say where every number comes from; check results by hand; log analytical decisions.

It is good practice to grow this file slowly. When the agent makes the same mistake twice, add one line to AGENTS.md. After a month it will reflect how you work, and that is worth more than any template.

Step 8 — Add two skills

A skill is a recipe the agent follows for one type of task. It is a Markdown file called SKILL.md in its own folder. The agent sees a short description of each skill and uses it when the task matches. You can also call a skill by name: type / and its name in the prompt box.

Here are two to start with:

  • decision-log keeps a file DECISIONS.md with every analytical choice: which observations were dropped, how a variable was defined, which method. For each choice it records the alternatives and the basis (evidence, convention, your instruction, or just a default). You read this log before you trust the results.
  • read-pdf makes the agent extract a PDF’s text into a .txt file first and work from that, citing page numbers. This avoids the most common failure with PDFs: answering from a partly read document without telling you.
---
name: decision-log
description: Keep a DECISIONS.md log of the analytical choices made during data work (which observations to keep, how a variable is defined, which method, which chart), so the researcher can review the reasoning before trusting results. Use whenever cleaning data, building a sample, defining variables, choosing a method or designing a table or figure, even if the user does not mention it. Also use when the user asks "what did you decide?" or "review the decisions".
---

# Decision log

Every result rests on judgment calls the reader never sees. The researcher needs to
check those calls *before* looking at results. This skill keeps them in one file,
`DECISIONS.md` in the project folder, written as the decisions are made.

## What to log

Log a decision when a reasonable analyst could have chosen differently AND the choice
could change the results or how we read them. Examples:

- dropping observations (missing values, outliers, small groups, a year or a country)
- defining a variable (what counts as "employed", income in levels or logs, which year's prices)
- merging tables (which key, what to do with rows that do not match)
- choosing a method (mean or median, which regression, which controls)
- designing an exhibit (what goes in the main chart, what is left out)

Do not log mechanical steps with no real alternative, or formatting.

## Format

Create `DECISIONS.md` on first use. Keep a summary table on top and a short entry for each
decision below it. Number entries D1, D2, ... and never renumber or delete them.

```markdown
# Decision log

| ID | Date | Decision | Basis | Status |
|----|------|----------|-------|--------|
| D1 | 2026-11-06 | Drop respondents younger than 18 | user | decided |

## D1 - Drop respondents younger than 18
- **Decision point:** The survey includes 16-17 year olds; the question is about adult voters.
- **Chosen:** Keep age 18 and above (drops 412 of 9,870 rows).
- **Alternatives:** keep all (rejected: they cannot vote); keep 16+ (only where voting age is 16).
- **Basis:** user instruction, 2026-11-06.
- **Affects:** all tables and figures. Easy to reverse.
```

The **Basis** field matters most. Be honest about it:

- `evidence` a check was run (name the file or the numbers)
- `convention` common practice in the field (name the source)
- `user` the researcher asked for it (give the date)
- `default` chosen for convenience, not tested. This label is the most useful one for the
  reviewer, because it shows where to look first.

**Status** is `decided`, `provisional` (to make progress, revisit later) or `needs-review`.

## How to work

1. Write the entry when the decision is made, not at the end.
2. If a decision drops a lot of data, changes the main finding, or is hard to undo,
   mark it `needs-review` and tell the user in plain words before going on.
3. If a decision is reversed, add a new entry and mark the old one `superseded by Dn`.
4. When the user asks to review the log, list first the `default` and `provisional`
   decisions that many results depend on.
---
name: read-pdf
description: Read a PDF (paper, report, book chapter, questionnaire, codebook) reliably by first extracting its text into a .txt file and then working from that text. Use whenever the user asks to read, summarize, quote, compare or extract information or tables from a PDF.
---

# Read a PDF: text first

Reading a PDF directly is unreliable: long files get cut, columns get mixed up, and the
agent may answer from a partial view without saying so. So we always extract the text
first, save it, and work from the saved text.

## Steps

1. **Extract the text.** Use the Python package `pymupdf` in this project's environment
   (install it with the project's package manager if missing). Save the text next to the
   PDF with the same name and a `.txt` ending, for example `paper.pdf` -> `paper.txt`.
   Mark each page with a line like `=== page 7 ===` so page numbers can be cited.
2. **Check the extraction.** Report the number of pages and the number of characters.
   If a page has almost no text (under ~200 characters), it is probably a scanned image.
   For those pages, render them to PNG (150 dpi is enough) and read the images.
   Tell the user which pages were read as images.
3. **Work from the `.txt` file**, not the PDF. For long documents (more than ~40 pages),
   read it section by section rather than all at once.
4. **Cite page numbers** for every claim, number or quote taken from the document.
   Quote exactly; never paraphrase inside quotation marks.
5. **Tables:** when the user needs a table, copy it into a CSV in `data/raw/` and then
   check three numbers from the CSV against the page image.

## What to tell the user at the end

- what was extracted (pages, characters, any pages read as images)
- where the `.txt` file is
- anything that could not be read well (garbled tables, formulas, footnotes)

Install them with this prompt:

Download these two files exactly (use a download command, do not retype them):
https://raw.githubusercontent.com/gabors-data-analysis/da-w-ai/main/friendly-agentic-ai-intro/starter/skills/decision-log/SKILL.md
https://raw.githubusercontent.com/gabors-data-analysis/da-w-ai/main/friendly-agentic-ai-intro/starter/skills/read-pdf/SKILL.md

Save them as .claude/skills/decision-log/SKILL.md and
.claude/skills/read-pdf/SKILL.md inside this project folder.
Then tell me in two sentences what each skill does.

Note the dot in .claude. Folders starting with a dot are hidden by default, so you may not see it in Explorer or Finder. That is normal. Start a new session (the + or New session button) and type / to check that both skills show up.

Try the PDF skill. Put a paper you know well into the folder, then ask: “Use the read-pdf skill on [file name]. What is the research question, the data, the main result? Give page numbers.” Check one of the page numbers yourself. Then try the harder question: “What are the three weakest points of this paper?” and judge the answer as a referee would.

Step 9 — A first real task with data

Now everything comes together. Start a new session. This time, before you send the prompt, switch the permission mode to Plan. In Plan mode the agent only thinks and proposes; it changes nothing until you agree.

Using the World Bank's open data (its API, no key needed), get for all
EU countries for 2023:
- female labour force participation rate (% of women 15+)
- GDP per capita, PPP

Save the raw download in data/raw, write the code in code/, and make
one scatter plot (GDP per capita on the x axis, participation on the y axis,
with country labels) saved in output/. Then write a half-page memo in
docs/memo.md: what the chart shows, and three caveats.
Keep the decision log as you go.

Read the plan. If something looks off, say so in plain words. When you are happy, switch back to Manual and tell it to go ahead.

Then check it. This is your job, not the agent’s.

  1. Open the chart. Does it look plausible? Are the countries where you expected?
  2. Pick two countries and look their numbers up yourself on data.worldbank.org. Do they match the CSV?
  3. Read DECISIONS.md. Which countries were missing for 2023, and what did the agent do about it? Did it use a different year, drop them, or tell you?
  4. Read the memo. Does it say “effect” or “causes” anywhere? It shouldn’t. A cross-country scatter shows an association.

If you find a mistake, tell the agent what you found, and add a line to AGENTS.md if it is the kind of mistake that could happen again. Finally, ask for the memo as a Word file (Step 6).

Habits that make it work

These are the habits I rely on every day. None is technical.

  1. Plan first, then act. For anything longer than a few minutes, use Plan mode or ask for a plan. Fixing a plan costs one sentence. Fixing finished work costs an afternoon.
  2. Small steps, then stop and look. Ask for one thing, check it, then ask for the next. An agent left running on a vague task produces a lot of plausible-looking work that you then have to read.
  3. Check the numbers. The agent can be confidently wrong. Compare a few values with the source by hand, every time. A smaller result you checked beats a larger one you did not.
  4. Never let it delete or overwrite. Raw data and your original documents stay untouched; old files go to _old/. Then every mistake can be undone.
  5. One session per task. Long sessions get muddled, just like long chats. When you switch to a new task, start a new session. What matters across sessions goes in AGENTS.md, DECISIONS.md or a notes file.
  6. Ask it to explain. “Why did you do that?”, “What does this line do?”, “What could go wrong here?” are all good questions. You are responsible for the work, so you need to understand it.

Troubleshooting

Problem What to do
Word Compare shows changes everywhere The agent probably rebuilt the whole document. Ask it to start again from a fresh copy and change only the text, keeping everything else as it was
The skills don’t show up when I type / Start a new session. Skills are loaded when a session starts
The agent seems stuck, or keeps doing the wrong thing Click stop. Say plainly what you want. If the session is long, start a new one
It made a mess of my files Ask: “List every file you created or changed in this session.” Then ask it to move the unwanted ones to _old/
An error I don’t understand Paste it in and ask: “Explain this error simply, then fix it.” This works far more often than you would expect

More setup problems are in Part 1, and a short glossary is on the course page.

Where to go next