Module 1 of 10

How AI coding agents work

A video for this module is coming.

What you'll do

You will learn the few ideas behind everything else in this guide: what an agent is, how Shipyard fits in, and the habits that stop it from wandering off or running up your usage. You will also get one prompt you can paste into any project to see where it stands. No setup is needed for this module.

An agent, in plain words

A chatbot answers questions. An agent also does things. Claude Code is an agent that lives in your terminal (the text window where you type commands). You describe what you want. It reads your files, writes code, runs commands, looks at the result and tries again.

That changes how you work with it. You are less the person typing and more the person who decides what to build and checks the result. Three habits come from that.

Plan first, then build

Ask for a plan before any code. Read it. Change what you do not like. Then say "go". You get far fewer wrong turns than when the agent starts building straight away. Shipyard does this for you: /shipyard:new-app writes a plan and waits for your "go" before it builds anything.

Describe the outcome, not the technology

Say who the app is for and what they should be able to do. Let the agent pick the tools. If you force a language or a framework too early, you can send it down a path that does not fit. A rambling voice note is fine. The agent can pull the facts out of it.

Make it prove it

"Done" from an agent is a claim, not evidence. Ask it to run the app, run the tests, and tell you what it checked and what it could not check. Shipyard builds this in. Its verify step opens your live app, signs in as a test user, checks that users cannot see each other's data, takes phone screenshots, and reports what it skipped.

The pieces around the agent

These four words come up all the time. Each is a way to give the agent more abilities.

• Skill. A folder with written instructions that the agent loads only when a task matches. Think of a big reusable prompt, sometimes with small scripts beside it. Anything you do repeatedly can become a skill.
• Plugin. A bundle of skills (and sometimes checks) that you install with one command. Shipyard is a plugin with six skills: setup, new-app, design, launch, video and ops.
• MCP (Model Context Protocol). A standard way to connect the agent to other tools: a browser, your email, a calendar, your own app. Each connection adds a list of tools the agent has to carry in every message.
• Subagent. A helper the main agent starts for one small job, such as searching files or running tests. It does the job in its own space and reports back.

Each skill and each MCP connection uses a little of your usage every turn, because the agent has to know it exists. So keep few of them switched on. Shipyard's six skills stay small for this reason, and load their detail only when you use them.

Keeping it cheap and clear

Claude Pro has limits that reset every few hours and every week, and they are shared with chatting on claude.ai. A few habits go a long way.

• One chat per topic. Long mixed conversations get slower, cost more and become less accurate. Start a new chat for anything unrelated.
• Watch the context. The context is how much of the conversation the agent can hold at once. When it fills up, older parts are summarised and details can be lost. Put screenshots and documents in your project folder and tell the agent where they are, instead of pasting them in.
• Idle chats cost more to resume. After a while without activity, the next message makes the agent re-read the whole conversation.
• Cheaper helpers for simple work. The strongest model is best for planning, security and final checks. Mechanical jobs like searching, renaming and running tests can go to a cheaper model. Shipyard tells its helpers to use one model cheaper than the main one, and keeps sign-in, data privacy, keys and payments on the main model.
• Check /usage. On build days, skip chatting on claude.ai and look at your usage in Claude Code with /usage.

CLAUDE.md: standing instructions

CLAUDE.md is a plain text file the agent reads at the start of every session. There is one for all your projects (in a folder called .claude in your home folder) and one per project. Use it for rules you would otherwise repeat.

During setup, Shipyard shows you a short set of working habits and asks if you want them added to your global file. It never adds them without a yes. The habits include: check before saying done, explain technical words, never ask for keys in the chat, never push straight to a branch that publishes automatically, and use cheaper helpers for mechanical work. Every app Shipyard creates also gets its own rules file (AGENTS.md) that the agent follows while building.

Audit my project

Not everything you build will come from Shipyard. This prompt works on any project and changes nothing. Paste it into Claude Code from the project's folder.

Audit this project. Read the code and change nothing.

Check and report on:
1. Secrets: any keys or passwords in files that are saved to git, any secret placed behind a public prefix such as NEXT_PUBLIC_, .env files tracked by git.
2. Sign-in: anything that sets or changes a password from an email address alone, redirects that are not checked, which pages and API routes are public.
3. Data privacy: does each person only see their own data? Is row level security switched on for every table? Can a user edit a field like is_admin on their own row? Is the server key used in browser code?
4. Costs: any AI or paid API call without a spending cap.
5. Tests and checks: do tests exist and run, and does anything run them before code is merged?
6. Deploy: do changes go straight to the branch that publishes the site?
7. Basics: privacy and terms pages, a 404 page, phone layout, fake numbers or reviews.

Sort the findings into "Fix now" (secrets, data leaks, account takeover), "Should fix" and "Nice to have". For each one give a plain sentence about what could go wrong for the users, and the file name as evidence. End with what you could not check.

Shipyard's upgrade mode (module 2) runs this same kind of audit for you, then fixes the findings one at a time with your approval.

Done when

• You can explain in one sentence each: agent, skill, plugin, MCP, subagent.
• You know to ask for a plan first and to ask what was checked.
• You have the audit prompt saved somewhere you can find it.

If something goes wrong

• The agent says it cannot run a command. It usually can. Remind it that it has access to the terminal and ask it to try. Only if it still fails, read the error it shows.
• Answers get slow or forgetful. The chat is too long. Start a new one and point the agent at the files in your project folder.
• Your usage runs out early. Check /usage. Common causes are very long chats, many MCP connections, and big pasted documents. See costs for what to expect.
• You pasted a key into the chat. Treat it as stolen. Create a new key at the provider and delete the old one. Chats are saved, so the key is stored with them.

Check yourself