Design your own agent — and write the plan

The whole session on one page

What you leave with

A section of a real LaTeX document, in a project the whole room contributed to, describing an agent tool you actually want to build — with citations to the papers or documents you brought, and a list of the things you could not support.

Not a toy. The plan is the thing you would hand a collaborator, or give to Claude Code next week as the brief for building it.

sources/        whatever you collected — papers, decks, posts, SOPs, code
sources/notes/  one structured note per source
refs/refs.bib   the sources you will cite
writing/        myplan.tex — the deliverable
.claude/        three subagents, two skills, one permission boundary
IDEAS.md        starter questions for the part that matters
tools/          five Python tools that check things and fix nothing

0 · Setup — two minutes, in the room

cd Demo10_agent_design
python3 tools/doctor.py
python3 tools/snapshot.py

doctor.py needs python3 and Claude Code. It names everything else as optional and says why. You should see four ok lines under Core and nothing missing.

snapshot.py is the undo button: it zips your notes, refs and plan into .snapshots/ so an agent cannot lose work you wanted to keep, and --restore puts them back. Source PDFs are skipped — they are the one thing no agent will overwrite. That safety net is what makes it reasonable to let an agent write files at all.

1 · Collect your sources — 10 min

cp ~/Downloads/*.pdf sources/

Not just papers. Anything that describes the work your agent would help with, or the problem it would solve:

Two or three is plenty. This is not a literature review; you want enough that the tool you design has something concrete to be about.

Decks and Word files need one command

A .pptx or .docx is a zip of XML. pdftotext fails on one, nothing renders it, and strings finds nothing once the zip is compressed — so out of the box they are simply unreadable.

python3 tools/totext.py sources/deck.pptx      # slides + speaker notes
python3 tools/totext.py sources/report.docx
python3 tools/totext.py sources/post.html      # script, style, nav stripped

Standard library only, nothing to install. Verified against a real 62-slide deck: 62 slides and 62 speaker-note blocks out, in order. A deck that is entirely images extracts nothing — export it as PDF and let Claude read the pages.

Nothing to hand? sources/README.md lists three real open-access papers (CC BY 4.0, you may cite them) that share one question and disagree about it.

2 · Turn them into notes — 20 min

claude
/agents          # notes, writer, citecheck

Then once per document:

It works out how to read the thing, writes sources/notes/<name>.md against a fixed eight-section template, sets kind: to what it actually is, and adds one row to sources/_index.md.

The template fits a blog post as well as a paper, and the sections that go thin are the point:

Writing “none — asserted, not shown” is a finding, not a hole in your note. check_notes.py only expects numbers in ## Evidence given when kind: is paper or preprint; it does fail on an empty one, whatever the kind.

Check it with a tool that repairs nothing

python3 tools/check_notes.py

It reports and fixes nothing, deliberately — a checker that edits is one that can make its own findings disappear. Two of its warnings are worth triggering on purpose so you see them:

Then read one note like a reviewer

## My take is empty. It always is. No agent writes there. In six months it is the only section you can trust to be your own thinking.

## Problem and aim comes before ## Claim. A note that opens with the claim has already accepted the document's framing. What did they think was missing, and was the gap real?

## What it is is the provenance line, and it earns its place on the things that are not papers. A vendor post claiming a tool saves 40% is evidence of a claim, not of 40%.

## Relevance to my tool is the bridge to step 4. It is the agent's guess at why you collected this. Argue with it — the argument is most of what step 4 needs.

3 · A .bib entry for anything you will cite — 5 min

Only for real publications. Skip this entirely if your documents are internal; a plan with no citations is a fine plan.

Easiest route: on the paper's own page, find Cite or Export citation and choose BibTeX. Every major publisher has this.

No publisher page? Paste the DOI into doi2bib.org and copy what comes back.

Paste the entry into refs/refs.bib, then rename the cite key so it starts with your first name and a colon:

@article{alice:horne2012,          # was horne2012pharmacogenetic
  title  = {Pharmacogenetic warfarin dose refinements},
  year   = {2012},
  doi    = {10.1160/TH11-06-0388},
}

python3 tools/bibcheck.py

Duplicate keys across every file you give it, keys with no prefix, and entries with no DOI. Keep the doi field — it is the only identifier that survives moving between tools, and it is how citecheck joins your notes to your citations. Google Scholar's BibTeX export does not include one, which is why it is not the route recommended here.

4 · Design your agent, out loud, with Claude — 15 min

Open IDEAS.md for starter questions, then talk:

The skill is under instruction to ask you four questions and wait before proposing anything:

1. What is the input, concretely? If the answer is abstract, it asks for a real example.
2. What is the output, and how would you know it was wrong? If the answer is “I would read it carefully”, the design is not finished. What is the check?
3. What must it never be able to do? Not should not — could not. That answer becomes a missing tool or a deny rule, not a sentence in a prompt.
4. How often, and who else sees the output? Runs once → just ask. Runs weekly → a skill. Other people depend on it → the failure modes have to be written down.

Then it proposes, and the proposal has to place every rule in the lowest layer that can hold it:

If every rule in the proposal lands in “context”, say so and try again. That is the most common failure of a first design, and catching it here costs fifteen minutes instead of a term.

Starter questions, if the room goes quiet

• What did you do more than three times last month that felt mechanical?
• What do you explain to every new student, in the same words?
• Which step in your analysis do you most often get wrong, or skip?
• What do you not do, because doing it properly would take a week?

Vague targets produce plans that read well and cannot be built. Push for the concrete version:

The skill ends by naming the one assumption that, if wrong, makes the whole design pointless, and how you could check it this week. Every design has one.

5 · Draft the implementation plan — 25 min

Six subsections, and two of them are the ones people skip: Design, which must name the layer for each rule and say why not a weaker one, and How it can fail, which needs at least three failure modes each paired with the check that catches it. A plan with no failure modes has not been thought about.

What comes back marks where every claim came from:

The last three are LaTeX comments, so they never typeset — but they stay in the source where you and anyone reading it can see them. Leave the gaps in. They are the plan telling you what you still have to find out, and \subsection{Open questions} is where they get promoted to prose. Deleting them so it reads finished is the one move that turns an honest plan into a confident wrong one.

Check the citations with an agent that cannot edit

It works cheapest-first: your notes, then the .bib as a lookup, and it opens a PDF only when those cannot settle the claim. It distinguishes confirmed by a note you read from confirmed by a note nobody read — the second is fidelity to your own summary, which is not the same as truth.

Expect several cannot verify verdicts and treat them as correct.

head -6 .claude/agents/citecheck.md

Look at the tools: line — Read, Glob, Grep, Bash. There is no Write. Now ask it to fix something and watch it decline, not because it was told to but because there is nothing to decline with. That is the bottom layer, and it is the only one that cannot be talked out of.

Last check before you upload

python3 tools/texcheck.py writing/myplan.tex

Three things, and they are specifically the three that break somebody else's build:

It does not need LaTeX installed. It is a text check, because requiring a TeX install would have excluded half the room — and because what it is looking for is visible in the source anyway.

6 · Upload to the shared Overleaf project — 10 min

The link is on the slide. It opens the project with edit access.

1. Rename your file. In Overleaf, select the groups folder, then Upload:

   groups/firstname-lastname.tex     # e.g. groups/alice-nguyen.tex

   Upload it as myplan.tex and you will silently overwrite whoever went before you. Say the filename out loud before anyone uploads.

2. Paste your entries into refs.bib, at the end. Your keys are prefixed, so nothing can collide.
3. Add one line to main.tex, in the marked block:

   \input{groups/firstname-lastname}

Overleaf is a real-time collaborative editor, so twenty people each adding one line to main.tex is exactly what it is built for. Watch the PDF rebuild with your section in it — that is the moment the session is for.

7 · The instructor assembles — 10 min

Live, on the projector. Compile, look at what twenty people produced in one document, and see what broke.

Something usually does, and that is the useful part. The three failures in order of likelihood are in the instructor notes below, with the fix for each.

8 · If time: a skill of your own — 15 min

A skill is a folder with a SKILL.md in it. Open .claude/skills/design/SKILL.md — that is the entire format: frontmatter with a name and a description, then instructions.

citecheck is an agent because the point is what it cannot do. design is a skill because the point is the order it works in.

For the instructor

The package ships an instructor/ folder with main.tex, a worked example-plan.tex, and the setup steps. Fifteen minutes, once, before the session.

1. New Project → Blank Project. Upload main.tex, replacing the default.
2. Create a groups folder and upload example-plan.tex into it. It gives the class something to look at and proves the \input wiring works before anyone depends on it.
3. Create refs.bib at the top level and paste in the header comment from the package's refs/refs.bib, so the key-prefix rule is visible to anyone who opens it.
4. Recompile. Title page, table of contents, one example section. If it does not work now it will not work with twenty people in it.
5. Share → link sharing → anyone with the link can edit. Put the link on a slide, not in the downloadable package.

When it breaks

What it teaches

• Three layers, and they are not interchangeable. CLAUDE.md is a request, settings.json is a refusal, a subagent's missing tool is an absence. Put each rule in the lowest layer that can hold it. The design conversation in step 4 is an hour of practice at exactly this.
• A verifier that can edit is one you cannot trust. It can make its own findings disappear. citecheck has no Write, and neither does check_notes.py.
• The agent that files may not browse; the agent that writes may. A note written from an abstract looks exactly like one written from the paper. The only reliable prevention is removing the tool.
• [GAP:] is a result. Deleting the gaps so a plan reads finished is how a confident, wrong document gets written.
• Folders may encode lifecycle, never classification. The test: can one thing be in two of these at once? If yes, it is a field.
• A requirement you can delete is better than one you document. This package needed Git for Windows, Git Bash and WSL instructions for exactly one reason: two of its five tools were shell scripts. Porting them to Python removed three dependencies and a paragraph of caveats. Look for that shape in your own design.
• The cheap check that runs before the expensive one. texcheck.py is a text scan with no LaTeX; bibcheck.py is a regex over a .bib. Between them they catch the three failures that would otherwise surface as a broken compile in front of twenty people.

Making it yours

• The seven note sections in .claude/agents/notes.md are a starting point. Rewrite them for what you actually need to remember about a paper in your field.
• IDEAS.md is yours. The sentence you write at the bottom before the session is worth comparing with the plan you have at the end of it.
• The design skill's four questions are the part most worth adapting. If your group has a fifth question it always asks, add it.
• Want the reference manager, the Word exit, and git? That is Demo 10x — same shape, more machinery.