Activity: Edit a Quarto Book with an Agent

In this activity you’ll practice the full clear–handoff–notes workflow from Skills 101. You’ll use an AI coding agent to plan and execute edits to a real Quarto book — the same template this documentation is built on.

Before you start

Make a copy of the practice repository

Do this on GitHub’s website.

  1. Open the NOAA Quarto book template.
  2. Click Use this template → Create a new repository.
  3. Owner: your personal GitHub username, not an organization.
  4. Repository name: my-quarto-book, or any name you like. The steps below use my-quarto-book.
  5. Choose Public and click Create repository.
  6. Make sure to copy all branches (there is a checkbox).

Clone your repository into the JupyterHub.

Open a terminal in the JupyterHub and type this (replace YOUR-USERNAME):

cd ~
git clone https://github.com/YOUR-USERNAME/my-quarto-book.git

You now have ~/my-quarto-book on the JupyterHub.

Connect to GitHub so you can push changes

You chose how the agent reaches GitHub in Setup.

  • Token for one repository: your token must include my-quarto-book. If you made the token before this repository existed, open https://github.com/settings/personal-access-tokens, click your token, and add my-quarto-book under Repository access. Or make a new token for it and log in again with gh auth login.
  • Full access: nothing more to do.
  • No access: you can still do this activity. The agent works and commits on the hub; you just cannot push to GitHub.

Start your agent in your repository

Important

Always start your agent from inside your project folder (cd ~/my-quarto-book first). The folder you start it in is what your agent treats as the project boundary.

Open a new terminal and start your agent:

cd ~/my-quarto-book
claude-agent-coders

This time, say yes to trusting the folder: this is the repository you want the agent to work in.

cd ~/my-quarto-book
agy-agent-coders

Try a first prompt

Type this:

What is this repository? List the main files and what they do.

If the agent reads your files and answers, you are set up.

What to expect while working:

claude-agent-coders starts in auto mode: routine work runs without asking, and a second model blocks risky actions. Auto mode does allow pushing to main, so keep your work on a branch. See Guardrails.

With agy-agent-coders:

  • Everyday commands run automatically: everyday tasks—inspecting files (ls, cat, grep, etc.), creating directories (mkdir, touch), R, Quarto, Python, and read-only git/GitHub actions run without asking. It also automatically accepts edits to files inside your project repository.
  • Unlisted commands ask for approval: Anything not on the team’s auto-approved list (copying, moving, or deleting files, pip, or running other software) will prompt for your confirmation before running. This is normal and expected.
  • Safety guards: Destructive actions like git reset --hard, force pushes (git push --force), git clean -f, recursive deletions (rm -r) outside your project directory, pushing to main, and deleting a repository are blocked. Merging a pull request, deleting a branch, and closing an issue make the agent stop and ask you first.

Phase 1: Plan the edits

Goal: Have the agent explore the book and help you plan what to change. Save the plan to notes/. Then clear.

What to do

Ask the agent to look at the book and help you come up with a plan for turning it into something of your own — a project page, a lab notebook, workshop notes, whatever you like. For example:

Read the files in this Quarto book and help me plan how to turn it into [a guide for my lab / notes for my project / a workshop site]. What chapters should I add, remove, or rename? What needs to change in _quarto.yml?

Work with the agent to refine the plan. Go back and forth until you’re happy with it.

Save the plan

When the plan feels ready:

Create a notes/ directory and save our plan to notes/plan.md.

Clear

You’ve finished phase 1. The plan is on disk. Tell the agent you’re about to clear:

I’m about to clear this session. Is there anything else we should save to notes/ before I do?

Then clear:

/clear
Tip

Why clear now? The conversation has gotten long — you’ve been exploring files and discussing options. Clearing resets the context so your next requests are cheaper and more focused. The plan in notes/ has everything the agent needs to continue.

Phase 2: Execute the plan (Draft 1)

Goal: Have the agent read the plan and execute it. Think about how to approach the work. Clear when done, with a handoff note.

Pick up the plan

Start a fresh prompt:

Read notes/plan.md and the current book structure. We’re going to execute this plan to create a first draft.

Think about how to execute

Before diving in, consider: should you ask the agent to do everything at once, or go step by step?

All at once works when:

  • The plan is clear and specific
  • Changes are independent (renaming chapters doesn’t depend on writing content)
  • You trust the agent to make reasonable choices

Step by step works better when:

  • You want to review as you go
  • Steps depend on each other (write chapter 1 before chapter 2 references it)
  • You’re not sure how the agent will interpret something

A reasonable middle ground: ask the agent to do a logical group of changes, review, then continue. For example:

Start by updating _quarto.yml with the new chapter structure from the plan. Don’t write the chapter content yet — just set up the structure.

Then after reviewing:

Now write first drafts of the new chapters.

Do the work

Execute the plan however you chose. Review what the agent produces. Ask it to fix anything that’s off.

Render and check

When the draft is done:

Render the book with quarto render and check for errors. Fix any problems.

Clear with a handoff note

You’ve finished draft 1. Before clearing, have the agent write a handoff:

Write a handoff note to notes/handoff.md. Summarize what we did, what the book looks like now, and what still needs work.

Review the handoff note — does it capture everything the next session would need? Then clear:

/clear

Phase 3: Wrap up

Goal: Practice picking up from a handoff note, then leave a final handoff for what’s next.

Resume from the handoff

Start a fresh prompt:

Read the notes in notes/ and tell me where we are with this book.

The agent should be able to orient itself from the handoff note and tell you the current state without you having to re-explain anything.

Leave a final handoff

Update the handoff note in notes/ with what’s left to do and where to find the information needed to finish. This is the end of the clinic session.

Discussion

After the activity, think about:

  • Did clearing and resuming work? Could the agent pick up from the handoff note without losing important context?
  • How did you break up the work? All at once vs. step by step — what worked better?
  • What made a good handoff note? What was missing? What was unnecessary?
  • How would this workflow help in your real work? Think about projects that span multiple days or involve handoffs between people.
Note

The point of this activity isn’t to produce a perfect book — it’s to practice the workflow. A messy first draft with clean handoff notes is a better outcome than a polished book with no notes.