DEV Community: Mohd Yusuf Khan

CLAUDE.md best practices: what to include and skip, with a template

Mohd Yusuf Khan — Mon, 02 Nov 2026 19:30:08 +0000

Originally published on Homingo Learn.

CLAUDE.md is the note Claude Code loads into every session. Short, concrete and current, it saves you repeating yourself; long and vague, it costs context every session and is followed less reliably.

What CLAUDE.md is (and is not)

CLAUDE.md is a Markdown file of standing instructions that Claude Code loads into context when a session starts. It is delivered as context, not as enforced configuration: Claude reads it and tries to follow it, and the more specific and short it is, the more reliably that happens. Anything that must happen every single time belongs in a hook (format after every edit) or a permissions deny rule (never read .env) instead.

Where CLAUDE.md files go

Project: ./CLAUDE.md or ./.claude/CLAUDE.md, committed so the whole team shares it.
Personal, all projects: ~/.claude/CLAUDE.md.
Personal, this project: ./CLAUDE.local.md (add it to .gitignore yourself).
Organisation: a managed policy file that IT deploys to every machine (for example /etc/claude-code/CLAUDE.md on Linux).

Files in the folder you start Claude in and in every folder above it load at launch and are joined together, broadest first, so the instructions closest to your working folder are read last. A CLAUDE.md in a subfolder loads only when Claude reads or edits a file in that subfolder. Run /context to see which files loaded (they are listed under Memory files) and /memory to open them.

How to create a CLAUDE.md with /init

Run /init in your project: Claude reads the codebase and drafts a CLAUDE.md with the build and test commands and the conventions it finds. If one exists, it suggests improvements instead of overwriting it. Treat the draft as a starting point: cut what Claude could read from the code anyway and add what it could not know.

What belongs in CLAUDE.md

Write down what you would otherwise explain again: the second time Claude makes the same mistake, the correction you typed last session, the thing a new teammate would need on day one. In practice:

Commands: how to build, test, lint and run one test, with the exact command.
Conventions that differ from the defaults: “use pnpm, not npm”, “API handlers live in src/api/handlers/”.
Sources of truth: which file wins when two disagree, which files are generated and must not be edited.
Pitfalls and their reasons: one line each, with the why, so Claude can apply it to cases you did not list.
Boundaries: what to ask before doing (new dependencies, migrations, anything that deploys).

Make each line checkable. “Use 2-space indentation” beats “format code properly”; “run npm test before committing” beats “test your changes”.

What to skip in CLAUDE.md

Anything Claude can read from the code: folder trees, dependency lists, descriptions it can rebuild in seconds. Keep the non-obvious architectural decisions and their reasons.
Multi-step procedures and one-area knowledge: move them into a skill (only its short description is always loaded; the body loads when needed) or a path-scoped rule.
Rules that must never be broken: enforce them with permissions or hooks; a sentence can be missed.
History and changelogs: what changed last month is git’s job.
Secrets: never. Project files are committed, and anything in a memory file can end up in Claude’s context.

CLAUDE.md template and example

The skeleton first, then a filled-in example. Keep the sections; swap the lines for your project.

CLAUDE.md skeleton

# <Project name>

## Commands
- `<build command>`: what it does
- `<test command>`: run after every change to <area>
- `<single test command>`: run one test file

## Sources of truth
- <file or folder> decides <thing>; never edit <generated folder>

## Conventions
- <a rule that differs from the defaults, with the why>

## Ask first
- <actions that need a yes: dependencies, migrations, deploys>

## Pitfalls
- <the mistake Claude made twice, and the right way>

Filled in for a Remotion repository that renders vertical videos from a spec file:

CLAUDE.md

# Vertical video repo

## Commands
- `npm run studio`: preview compositions in the browser
- `npm run render -- ep05`: render episodes/ep05 to out/ep05.mp4
- `npm test`: spec schema and caption length checks (run after every spec edit)

## Sources of truth
- episodes/<id>/spec.json decides every shot: change the spec, never the files in
  src/generated/ (rebuilt on each render)
- Output is 1080x1920 at 30 fps; captions stay inside the safe area in @docs/safe-area.md

## Conventions
- One React component per shot type in src/scenes/; props come only from the spec
- Colours come from src/theme.ts, never hard-coded

## Ask first
- Adding a dependency, changing the spec schema, deleting anything in episodes/

## Pitfalls
- out/ is gitignored (large files; every render rebuilds it): never force-add it
- If a render fails on a missing font or asset, report it; do not install anything
  or change the spec to work around it

Note the @docs/safe-area.md import: the referenced file is loaded with CLAUDE.md, so long reference material can live in its own file. Imports help organisation but do not save context, because the imported file loads every time.

Imports and path-scoped rules

@path/to/file imports another file (relative to the importing file; up to four levels deep). For instructions that only matter in one part of the codebase, use .claude/rules/: one Markdown file per topic, and a paths list in the frontmatter makes a rule load only when Claude works on matching files.

.claude/rules/scenes.md

---
paths:
  - "src/scenes/**/*.tsx"
---

# Scene components
- Every animated value is driven by the frame number, never by timers
- Keep text inside the safe area described in docs/safe-area.md

Does Claude Code read AGENTS.md?

Yes, in recent versions: if a repository has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in the working folder or above it, Claude Code reads the AGENTS.md. Once a CLAUDE.md exists, it reads only the CLAUDE.md files by default. To keep one file for every coding tool, write the shared rules in AGENTS.md and put @AGENTS.md in your CLAUDE.md, with any Claude-only lines below it.

How long should CLAUDE.md be? Size and upkeep

Aim for under 200 lines per file. Longer files cost context in every session and lower adherence; Claude Code warns at startup when a file is over the recommended length.
Remove contradictions. If two lines (or two files) disagree, Claude may pick either. Re-read the file when you add to it.
Leave notes for humans in HTML comments. Block-level  comments are stripped before the file reaches Claude, so they cost no tokens.
Prune with each change. When a rule stops being true, delete it in the same commit that changed the code.

CLAUDE.md vs auto memory, skills, subagents and hooks

Claude Code also keeps auto memory: notes Claude writes for itself about your preferences and corrections, in a MEMORY.md index per repository (the first 200 lines or 25KB load each session). Use the /memory command to browse it. The division of labour: CLAUDE.md for the rules you write, auto memory for what Claude learns, skills for procedures and reusable prompts (custom slash commands now live there too), subagents for independent checks and hooks for guarantees. After /compact, the project-root CLAUDE.md is read again from disk, so rules given only in chat are the ones that get lost: if it matters, write it down.

Details follow the official memory documentation as of November 2026.

If you make short vertical videos with Claude Code, the skill below packages a complete spec-first method for them: story, episode spec, camera, light and grade, a Remotion starter and pre-post QA.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.

Claude Code custom slash commands: how to create them (with examples)

Mohd Yusuf Khan — Mon, 02 Nov 2026 18:34:19 +0000

Originally published on Homingo Learn.

Custom slash commands in Claude Code turn a prompt you type every day into a one-word command, with arguments and live project context filled in before Claude reads it.

Custom commands and skills: the same thing now

Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and behave the same way; existing command files keep working. Claude can also run either one by itself when its description matches the task, unless you set disable-model-invocation: true. The single-file command is the quickest to write. Choose the skill folder when the command needs reference files or scripts next to it (see how to write a SKILL.md). If both exist with the same name, the skill wins.

How to create a custom slash command (.claude/commands)

The file name becomes the command name. Subfolders become a namespace: .claude/commands/video/qa.md is /video:qa. Commit .claude/commands/ to share commands with the team; personal ones go in your home folder as skills (~/.claude/skills/<name>/SKILL.md).

.claude/commands/explain-error.md

---
description: "Explain an error message and propose the smallest fix"
argument-hint: "[error text]"
---

Explain this error in two sentences, find where it comes from in this repository,
and propose the smallest change that fixes it. Do not edit files until I agree.

Error: $ARGUMENTS

Type /explain-error TypeError: cannot read properties of undefined and everything after the command name replaces $ARGUMENTS. If a command has no placeholder, Claude Code appends the arguments at the end as ARGUMENTS: ....

Arguments: $ARGUMENTS, $0 and named arguments

$ARGUMENTS: everything typed after the command.
$0, $1 … (or $ARGUMENTS[0]): single arguments, counted from zero (older guides start at $1, so check old command files). Quote an argument that has spaces: /new-episode ep05 "a lighthouse keeper hears knocking" gives $0 = ep05 and $1 = the whole premise.
Named arguments: list them in the frontmatter (arguments: [id, premise]) and write $id and $premise in the body. Easier to read than positions.
A literal dollar sign needs a backslash: \$1.00.

.claude/commands/new-episode.md

---
description: Start a new episode spec from the template
argument-hint: "[episode-id] [premise]"
arguments: [id, premise]
---

Create episodes/$id/spec.json from episodes/_template/spec.json.

Premise: $premise

1. Write the hook shot first: frame 0 must show a situation that raises a question.
2. Fill the remaining shots so each one adds information or raises a new question.
3. Write one caption per shot, at most 7 words.
4. Run `npm test` and fix every spec error before you stop.

Run shell commands in a slash command (! syntax)

Write ! followed by a command in backticks, at the start of a line or after a space: the command runs before the prompt is sent, and its output replaces the placeholder. For several commands, use a fenced code block whose opening fence is followed by !. Claude reads the current state instead of spending turns finding it. These commands are checked against your permission rules and do not prompt, so pre-approve them with allowed-tools; if one fails, the whole command is aborted.

.claude/commands/review-changes.md

---
description: Review my uncommitted changes against the project rules
allowed-tools: Bash(git status *) Bash(git diff *)
---

## Changed files
!`git status --short`

## Diff
!`git diff HEAD`

Review the diff above against CLAUDE.md. List every problem as
file:line, what is wrong, and the fix. Nothing else.

New untracked files show in git status but not in the diff; run git add -N on them first if the review should read them. In a repository with no commits yet, use git diff instead of git diff HEAD.

Frontmatter fields worth knowing

description: shown in the / menu. Without it, the first line of the body is used.
argument-hint: the hint shown while you type, such as [episode-id].
allowed-tools: tools Claude may use without asking during this command, for example Bash(ffprobe *). Deny rules still win.
model and effort: run a routine command on a smaller model or lower effort.
disable-model-invocation: true: only you can trigger it. Use it for anything with side effects, such as a deploy or a publish.
user-invocable: false: the opposite; hidden from the / menu, for background knowledge only Claude should load.
context: fork (with agent to pick the type): run the command in a subagent with its own context.

Field names must match exactly: Claude Code ignores an unknown field without an error, so a typo silently does nothing.

.claude/commands/video/qa.md (run as /video:qa ep05)

---
description: Technical QA of a rendered episode before posting
argument-hint: "[episode-id]"
allowed-tools: Bash(ffprobe *)
model: haiku
disable-model-invocation: true
---

Run ffprobe on out/$0.mp4 and report width, height, frame rate, duration and
whether an audio stream exists. PASS only if it is 1080x1920, r_frame_rate is exactly
30/1, and it is between 15 and 90 seconds long. One line per check, then PASS or FAIL.

Commands, skills, subagents or hooks?

A command when you start the job yourself and the prompt is the same each time.
A skill when the method is longer or needs files beside it.
A subagent when the work would fill your main conversation with file reads, or needs a reviewer that did not write it. Define one first (a file-qa agent, say), then the command can simply say “use the file-qa subagent on out/$0.mp4”, or set context: fork to run the command itself in a subagent.
A hook when something must happen every time, with no prompt at all.

Command not showing up?

Type / and look for the name: the menu lists every command, and every skill not marked user-invocable: false.
Check the folder: .claude/commands/ in the project you started Claude in (or a skill folder with a SKILL.md inside).
Check for a clash: a skill with the same name wins over a command file.
Check the frontmatter: it must open and close with --- and be valid YAML.

Common mistakes

A shell line missing from allowed-tools. Add the exact pattern.
Unquoted multi-word arguments. Without quotes, each word is its own $N.
Side effects Claude can trigger. Add disable-model-invocation: true to deploys and publishes.
Rules copied into every command. Shared rules belong in CLAUDE.md; the command keeps only its own task.

If you make short vertical videos with Claude Code, the skill below packages a complete spec-first workflow like the one behind the episode commands above.

Fields and syntax follow the official skills and commands documentation as of November 2026.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.

Isometric diagrams in plain SVG: projection, four-tone shading and painter's order

Mohd Yusuf Khan — Mon, 02 Nov 2026 17:02:03 +0000

Isometric drawings explain hardware and systems better than flat boxes and arrows: a reader sees depth, which part sits on which, and where things connect. You don't need a 3D engine for them. About 45 lines of JavaScript and plain SVG polygons are enough to start, and the three ideas below are the ones that decide whether the result looks crafted or broken.

The cover image is exactly what the script at the end draws: a base plate with a tank, a pipe, a pump and a valve.

1. The projection

In a classic isometric view the x and y axes sit 30 degrees below the horizontal and z points straight up. A world point (x, y, z) lands on screen at:

const COS30 = Math.cos(Math.PI / 6), SIN30 = 0.5;

function project([x, y, z], s = 20, ox = 280, oy = 190) {
  return [ox + (x - y) * COS30 * s, oy + (x + y) * SIN30 * s - z * s];
}

s is the pixel size of one world unit and (ox, oy) is where the world origin lands. On screen +x runs down-right, +y runs down-left and +z runs up. That means a bigger x + y is closer to the viewer, which matters in step 3.

2. A box is three faces, and each face gets its own tone

From this camera you only ever see three faces of a box: the top, the face at x + w (screen right) and the face at y + d (screen left). Draw those three as polygons and skip the rest.

Flat colour makes boxes look like stickers. The trick is four tones from one base colour: the top lightest (it faces the light), the right face at the base colour, the left face darker, and an outline darker still so edges read on any background.

function tones(hex) {
  const n = parseInt(hex.slice(1), 16), c = [n >> 16, (n >> 8) & 255, n & 255];
  const mix = k => '#' + c.map(v => Math.round(Math.min(255, v * k)).toString(16).padStart(2, '0')).join('');
  return { top: mix(1.25), right: mix(1.0), left: mix(0.75), line: mix(0.45) };
}

Keep the same four multipliers for every material and the whole drawing reads as lit from one direction.

3. Painter's order (the bug that bites first)

SVG paints in document order, so whatever comes later covers what came before. You have to emit far things first.

The obvious first try is to sort every box by its near corner, (x + w) + (y + d). It looks reasonable on paper and fails at once on this scene: the base plate is the widest part, so its near corner is the biggest, so it is drawn last and buries the pipe and the valve, the lower half of the tank and most of the pump.

For drawings built in layers (a plate, then parts standing on it) a two-key sort fixes it: the bottom z first, then the near corner inside each layer.

const order = (a, b) => (a.z - b.z) || ((a.x + a.w + a.y + a.d) - (b.x + b.w + b.y + b.d));

Know its limits. It holds for compact, similar-sized parts. A long member breaks it even when nothing touches: a long pipe running along x behind a short pump has the bigger near-corner sum, so it gets drawn after the pump and paints over it. Parts that float above another layer can fail the same way. For anything beyond simple layered scenes, use the separation test: with this camera, box A is behind box B when A.x + A.w <= B.x, or A.y + A.d <= B.y, or A.z + A.h <= B.z. Add an edge for each pair whose screen outlines overlap, then sort topologically. If the graph has a cycle (three bars in a pinwheel, each in front of the next), split one box in two to break it.

The whole script

Save it as iso.mjs and run node iso.mjs > machine.svg. Open the SVG in any browser. Node 18 or newer is enough; there are no dependencies.

// iso.mjs: isometric boxes in plain SVG, no libraries. Run: node iso.mjs > machine.svg
const COS30 = Math.cos(Math.PI / 6), SIN30 = 0.5;

// World -> screen. On screen, +x runs down-right, +y runs down-left, +z runs straight up. One unit = `s` px.
function project([x, y, z], s = 20, ox = 280, oy = 190) {
  return [ox + (x - y) * COS30 * s, oy + (x + y) * SIN30 * s - z * s];
}

// Four tones per material: top lightest, right face mid, left face darker, outline darkest.
function tones(hex) {
  const n = parseInt(hex.slice(1), 16), c = [n >> 16, (n >> 8) & 255, n & 255];
  const mix = k => '#' + c.map(v => Math.round(Math.min(255, v * k)).toString(16).padStart(2, '0')).join('');
  return { top: mix(1.25), right: mix(1.0), left: mix(0.75), line: mix(0.45) };
}

const pts = p => p.map(q => project(q).map(v => v.toFixed(1)).join(',')).join(' ');

// A box at (x, y, z) with size (w, d, h). Only the three faces the viewer sees are drawn.
function box({ x, y, z, w, d, h, color }) {
  const t = tones(color);
  const top   = [[x, y, z + h], [x + w, y, z + h], [x + w, y + d, z + h], [x, y + d, z + h]];
  const right = [[x + w, y, z], [x + w, y + d, z], [x + w, y + d, z + h], [x + w, y, z + h]];
  const left  = [[x, y + d, z], [x + w, y + d, z], [x + w, y + d, z + h], [x, y + d, z + h]];
  const face = (p, fill) => `<polygon points="${pts(p)}" fill="${fill}" stroke="${t.line}" stroke-width="1" stroke-linejoin="round"/>`;
  return face(left, t.left) + face(right, t.right) + face(top, t.top);
}

// Painter's order: draw what is farther from the viewer first. For parts that sit on layers
// (a plate, then things standing on it), sort by the bottom z first, then by the near corner
// (x + w) + (y + d) inside each layer.
const order = (a, b) => (a.z - b.z) || ((a.x + a.w + a.y + a.d) - (b.x + b.w + b.y + b.d));

const parts = [
  { x: 0, y: 0, z: 0,   w: 10, d: 6, h: 1,   color: '#5b6b82' }, // base plate
  { x: 1, y: 1, z: 1,   w: 3,  d: 3, h: 5,   color: '#2f7de1' }, // tank
  { x: 4, y: 2, z: 1,   w: 3,  d: 1, h: 1,   color: '#9aa7b8' }, // pipe
  { x: 7, y: 1, z: 1,   w: 2,  d: 3, h: 3,   color: '#e2a03f' }, // pump
  { x: 7.5, y: 4.5, z: 1, w: 1, d: 1, h: 0.6, color: '#d9534f' }  // valve
];

const body = [...parts].sort(order).map(box).join('\n  ');
process.stdout.write(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 460" width="600" height="460">
  <rect width="600" height="460" fill="#0f1420"/>
  ${body}
</svg>
`);

To add a part, add one line to parts. To change the look, change the four multipliers in tones. Pick mid-tone base colours: tones clamps at 255, so a very light base loses the contrast between its top and right faces. On Windows PowerShell 5.1, node iso.mjs | Out-File -Encoding utf8 machine.svg avoids a UTF-16 file.

Where to take it next

Real explainer figures need more than boxes: cylinders and rounded parts, labels that never collide, cutaways that open a wall to show the inside, live numbers on gauges, and motion. Each of those is its own small project.

For detailed figures without building the renderer yourself, the open-source anatomy skill (MIT) is an agent skill that has Claude Code create detailed, interactive isometric SVG illustrations of machines and systems. Its source is a good place to learn the techniques.

Disclosure: I'm the founder of Homingo; Homingo Learn is our learning brand. We built a paid Claude Code skill that includes that open-source skill with our reel and explainer kit on top. Isometric Explainers adds a 1080x1920 reel kit (camera moves, cutaways, callouts locked to parts, named cues synced to your narration), live readouts, and built-in layout, motion and geometry checks, so one figure becomes both a docs illustration and a vertical explainer reel. It's Rs 1,499 one-time: Isometric Explainers for Claude Code. Everything above works without it.

Tool calling in Python for Claude and OpenAI: the full agent loop

Mohd Yusuf Khan — Mon, 02 Nov 2026 14:01:06 +0000

Originally published on Homingo Learn.

Tool calling is how a model asks your code to do something (OpenAI calls it function calling; Anthropic calls it tool use). The model only proposes; your code checks the request, runs it and reports back.

How tool calling works

You send the model a list of tools, each with a name, a description and a JSON Schema for its arguments. When the model decides a tool would help, it replies with a tool call (a tool_use block in the Anthropic API) instead of, or alongside, text. Your code runs the tool and sends the result back in the next message (a tool_result block), and the model continues. With tools you define (client tools), the model never runs anything itself, which is why the checks belong in your code.

Define tools and validate their arguments

Keep each tool’s schema next to its function in a decorator, so the two are edited together. This minimal version makes every argument required (an optional third value lists the allowed values as an enum), and the runner turns any failure into a readable error for the model:

import json

TOOLS = {}


def tool(description, /, **params):
    """Register a function as a tool. params: name -> (JSON type, description[, allowed values]); all required."""
    def prop(json_type, desc, enum=None):
        return {"type": json_type, "description": desc, **({"enum": enum} if enum else {})}

    def wrap(fn):
        TOOLS[fn.__name__] = {
            "fn": fn,
            "spec": {
                "name": fn.__name__,
                "description": description,
                "input_schema": {
                    "type": "object",
                    "properties": {k: prop(*v) for k, v in params.items()},
                    "required": list(params),
                    "additionalProperties": False,  # the runner rejects unknown keys, so the schema says so too
                },
            },
        }
        return fn
    return wrap


@tool("Current weather for a city. Use for any question about weather now.",
      city=("string", "City name, e.g. 'Lisbon'"))
def get_weather(city: str) -> dict:
    return {"city": city, "temp_c": 19, "sky": "clear"}  # stand-in for a real API call


@tool("Convert an amount between EUR and USD (demo rates).",
      amount=("number", "Amount to convert"), source=("string", "Currency code", ["EUR", "USD"]),
      target=("string", "Currency code", ["EUR", "USD"]))
def convert(amount: float, source: str, target: str) -> dict:
    rates = {("EUR", "USD"): 1.08, ("USD", "EUR"): 0.93}
    if (source, target) not in rates:
        raise ValueError(f"no rate for {source}->{target}; supported: EUR<->USD")
    return {"amount": round(amount * rates[(source, target)], 2), "currency": target}


TYPES = {"string": str, "number": (int, float), "integer": int, "boolean": bool, "object": dict, "array": list}


def type_ok(value, json_type: str) -> bool:
    if isinstance(value, bool) and json_type != "boolean":  # True is an int in Python, not in JSON Schema
        return False
    if json_type == "integer" and isinstance(value, float):  # JSON Schema accepts 50.0 as an integer
        return value.is_integer()
    return isinstance(value, TYPES[json_type])


def run_tool(call: dict) -> dict:
    """Validate and run one tool call; argument and tool failures come back as error results."""
    entry = TOOLS.get(call["name"])
    if entry is None:
        return error(call, f"unknown tool {call['name']!r}; available: {', '.join(TOOLS)}")
    schema, args = entry["spec"]["input_schema"], call.get("input")
    if not isinstance(args, dict):
        return error(call, "arguments must be a JSON object")
    missing = [k for k in schema["required"] if k not in args]
    props = schema["properties"]
    wrong = [k for k, v in args.items() if k in props
             and (not type_ok(v, props[k]["type"]) or v not in props[k].get("enum", [v]))]
    unknown = [k for k in args if k not in schema["properties"]]
    if missing or wrong or unknown:
        return error(call, f"bad arguments: missing={missing} invalid={wrong} unknown={unknown}")
    try:
        content = json.dumps(entry["fn"](**args), default=str)  # dates, decimals etc. become strings
    except Exception as e:  # the model gets a readable error and can try again
        return error(call, f"{type(e).__name__}: {e}")
    return {"type": "tool_result", "tool_use_id": call["id"], "content": content}


def error(call, message):
    return {"type": "tool_result", "tool_use_id": call["id"], "content": message, "is_error": True}


print([t["spec"]["name"] for t in TOOLS.values()])
print(run_tool({"id": "t1", "name": "convert", "input": {"amount": 50, "source": "EUR", "target": "USD"}}))
print(run_tool({"id": "t2", "name": "convert", "input": {"amount": "50", "source": "EUR"}}))
print(run_tool({"id": "t3", "name": "convert", "input": {"amount": 5, "source": "EUR", "target": "EUR"}}))
# ['get_weather', 'convert']
# {'type': 'tool_result', 'tool_use_id': 't1', 'content': '{"amount": 54.0, "currency": "USD"}'}
# ... 'content': "bad arguments: missing=['target'] invalid=['amount'] unknown=[]", 'is_error': True}
# ... 'content': 'ValueError: no rate for EUR->EUR; supported: EUR<->USD', 'is_error': True}

Two details do most of the work. Errors go back as a tool_result with is_error: true instead of crashing the loop, and they say what to do differently (“supported: EUR<->USD”), so the model can correct itself on the next step. And the description is a routing rule: say when to use the tool, not just what it does. The check covers top-level names and types; for nested schemas use jsonschema.validate(args, schema) (catch jsonschema.ValidationError and return its message as an is_error result) or your provider’s strict schema mode.

The agent loop and parallel tool calls with Claude (Anthropic API)

from concurrent.futures import ThreadPoolExecutor


def chat_with_tools(call_model, user_text, max_steps=6):
    """The tool loop: call the model, run every tool it asks for, send the results back, repeat."""
    messages = [{"role": "user", "content": user_text}]
    specs = [t["spec"] for t in TOOLS.values()]
    for _ in range(max_steps):
        reply = call_model(messages, specs)
        if reply.get("stop_reason") == "max_tokens":  # cut off: a tool call or the answer may be incomplete
            return "Stopped: reply cut off (max_tokens)."
        messages.append({"role": "assistant", "content": reply["content"]})
        calls = [b for b in reply["content"] if b["type"] == "tool_use"]
        if not calls:  # no tool requested: this is the answer
            return "".join(b["text"] for b in reply["content"] if b["type"] == "text")
        with ThreadPoolExecutor() as pool:  # read-only calls run at the same time; map keeps their order
            results = list(pool.map(run_tool, calls))
        # Anthropic API: all results for one assistant turn go back together, in one user message.
        messages.append({"role": "user", "content": results})
    return "Stopped: too many tool steps."


# Stand-in model so the example runs offline. With the Anthropic SDK this is:
#   client.messages.create(model=..., max_tokens=1024, tools=specs, messages=messages).model_dump(exclude_none=True)
def fake_model(messages, specs):
    last = messages[-1]["content"]
    if isinstance(last, str):  # first turn: ask for two tools at once
        return {"stop_reason": "tool_use", "content": [
            {"type": "tool_use", "id": "a1", "name": "get_weather", "input": {"city": "Lisbon"}},
            {"type": "tool_use", "id": "a2", "name": "convert", "input": {"amount": 50, "source": "EUR", "target": "USD"}},
        ]}
    results = {r["tool_use_id"]: json.loads(r["content"]) for r in last}  # the demo assumes both succeed
    w, c = results["a1"], results["a2"]
    return {"stop_reason": "end_turn", "content": [{"type": "text", "text": f"{w['city']}: {w['temp_c']}°C and {w['sky']}. 50 EUR is {c['amount']} USD."}]}


print(chat_with_tools(fake_model, "Weather in Lisbon, and what is 50 EUR in dollars?"))
# Lisbon: 19°C and clear. 50 EUR is 54.0 USD.

The model asked for both tools in one turn. The loop runs them at the same time and returns all the results together in a single user message, each matched to its call by tool_use_id. Run read-only tools in parallel like this; run tools that change state one at a time, in order. The thread pool helps with I/O-bound tools such as API calls. The loop also checks stop_reason: a reply cut off at max_tokens can hold an incomplete tool call, so it is never run or returned as the answer. At the step cap this snippet returns a stop message; to get an answer instead, make one last call with tool_choice={"type": "none"} so the model must reply from what it has. The max_steps cap is the simplest guard against a model that keeps calling tools; see how to stop an AI agent infinite loop for repeat detection and finish checks.

OpenAI function calling in Python (Chat Completions and Responses)

Chat Completions: tools are {"type": "function", "function": {"name": ..., "description": ..., "parameters": {...}}}; parameters is the same JSON Schema as input_schema above.
Calls arrive in message.tool_calls, with the arguments as a JSON string to parse (json.loads, and treat a parse failure as a tool error).
Append the assistant message that carries tool_calls first, then each result as its own message with role: "tool" and the matching tool_call_id. Skipping the assistant message is the most common Chat Completions error.
Responses API: tools are flat ({"type": "function", "name": ..., "parameters": {...}}), calls arrive as function_call items and results go back as function_call_output items with the same call_id.

The Chat Completions loop (openai SDK), reusing the tools and run_tool from above.

def chat_with_tools_openai(client, model, user_text, max_steps=6):
    """The same loop on OpenAI Chat Completions, reusing TOOLS and run_tool from above."""
    tools = [{"type": "function", "function": {"name": s["name"], "description": s["description"],
                                               "parameters": s["input_schema"]}}
             for s in (t["spec"] for t in TOOLS.values())]
    messages = [{"role": "user", "content": user_text}]
    for _ in range(max_steps):
        choice = client.chat.completions.create(model=model, messages=messages, tools=tools).choices[0]
        if choice.finish_reason == "length":
            return "Stopped: reply cut off (max_tokens)."
        msg = choice.message
        messages.append(msg)  # the assistant message carrying tool_calls goes in BEFORE the tool messages
        if not msg.tool_calls:
            return msg.content
        for tc in msg.tool_calls:  # one role "tool" message per call, matched by tool_call_id
            try:
                args = json.loads(tc.function.arguments)  # arguments arrive as a JSON string
            except json.JSONDecodeError:
                args = None  # run_tool answers "arguments must be a JSON object"
            result = run_tool({"id": tc.id, "name": tc.function.name, "input": args})
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result["content"]})
    return "Stopped: too many tool steps."

Forcing or disabling tool calls. Both APIs let you steer the choice. Anthropic: tool_choice is {"type": "auto"} (the default), {"type": "any"} (must use some tool), {"type": "tool", "name": "convert"} (must use that one) or {"type": "none"}; add "disable_parallel_tool_use": true to get at most one call per turn. OpenAI: tool_choice is "auto", "required", "none" or a named function, and parallel_tool_calls=False turns parallel calls off.

Writing tools the model uses well

Few, distinct tools. Two tools that overlap (“search” and “lookup”) make the model guess. Merge them or make the descriptions say when each applies.
Small, typed arguments. An enum or a number is easier to get right than a paragraph of open-ended text the tool must parse.
Compact results. Return the fields the model needs, not the whole API response; every result is read back into the context.
Read-only by default. Tools that change things (send, delete, pay) should ask a person first or run only in a sandbox.
Retries live in the tool layer. A rate limit or a timeout should be retried by your code before the model sees an error. Retry only idempotent calls, or pass an idempotency key, so a send or a payment never runs twice; see retries and rate limits in Python.

Common mistakes

Trusting the arguments. The model can send a wrong type, a missing field or a made-up tool name. Validate before running.
Raising inside the loop. One exception ends the whole run. Catch it in the runner and return it as a tool error.
Losing a result. Every call needs its result: with the Anthropic API all results for one turn go back together in the next user message; with OpenAI, one tool message per call. A missing one is an API error.
No step cap. A loop without one can run until the budget is gone.

Tools are one layer of an agent, alongside the loop, memory and checks. See AI agent memory in Python and the tool layer of a multi-agent research system.

Multi-agent systems: build an AI research team: Six modules, each with a short video lesson, a quiz check and a hands-on coding round that adds a tested piece of the team to your own repo. Together they cover the planner contract, handoffs, the tool layer, shared memory, the source checker, budgets, traces and an eval gate. The capstone is your team running live on a topic of your choice, with its reports, eval scores and code in a public GitHub repo. For builders who know Python and have called a model API. Certificate on completion. See the course

Disclosure: this guide is by Homingo, the team behind the course linked above. Everything in it works without it.

Claude Code hooks: PreToolUse, PostToolUse and Stop examples

Mohd Yusuf Khan — Mon, 02 Nov 2026 13:49:02 +0000

Originally published on Homingo Learn.

CLAUDE.md asks; a hook makes sure. How hooks work, the JSON they read and return, and five examples to adapt today.

What are Claude Code hooks?

A hook is a command that Claude Code runs at a fixed point in its lifecycle: before a tool call (PreToolUse), after one succeeds (PostToolUse), when Claude finishes its reply (Stop), when a session starts, and many more. Instructions in CLAUDE.md are context that Claude tries to follow; a hook runs every time, whatever the model decides. Use CLAUDE.md for judgement and hooks for anything that must always happen or must never happen.

The events you will use most:

PreToolUse: before a tool call; can allow, deny or ask, or rewrite the input.
PostToolUse: after a tool call succeeds (PostToolUseFailure when it fails); can add context for Claude.
UserPromptSubmit: when you send a prompt, before Claude sees it.
Stop and SubagentStop: when Claude or a subagent finishes its reply; can send it back to work.
SessionStart and SessionEnd: at the start (including after /compact) and end of a session.
Notification and PermissionRequest: when Claude needs your attention or is about to ask for permission.
PreCompact: before the conversation is compacted.

Where hooks live: settings.json and frontmatter

Hooks go in a settings file: ~/.claude/settings.json for all your projects, .claude/settings.json for one project (commit it to share with the team) or .claude/settings.local.json for yourself only. Subagents and skills can also carry hooks in their frontmatter, active only while they run. The structure has three levels: the event, a matcher group, and the commands to run.

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write", "timeout": 30 }
        ]
      }
    ]
  }
}

That one is the official auto-format example: after every Edit or Write, Prettier formats the file Claude touched. The matcher is a tool name, a list like Edit|Write, or a regular expression (mcp__github__.* matches every tool of an MCP server called github); * or an empty matcher means every tool. Type /hooks in a session to see what is configured and where each hook comes from. This one needs jq and breaks on paths with spaces; the Python hooks below avoid both.

Hook input JSON, exit codes and JSON output

Claude Code sends the event as JSON on the hook’s standard input. For tool events it includes session_id, cwd, hook_event_name, tool_name and tool_input (for Edit and Write, tool_input.file_path is always absolute); PostToolUse adds tool_response. The hook answers in one of two ways:

Exit codes. 0 = carry on. 2 = block: in PreToolUse the tool call does not run and your stderr text goes to Claude as the reason; in PostToolUse the tool already ran, so stderr reaches Claude as a warning. Any other code is a non-blocking error: the action proceeds. A policy hook that exits 1 blocks nothing.
JSON on stdout (with exit 0) for finer control. PreToolUse returns hookSpecificOutput.permissionDecision (allow, deny or ask) plus a reason; PostToolUse and Stop use a top-level "decision": "block" with a reason; hookSpecificOutput.additionalContext (with hookEventName) adds a note for Claude.

Hooks change quickly between Claude Code versions. Everything here follows the official hooks reference as of November 2026; check it before relying on a rarer event or field. We write the scripts below in Python so they run the same on macOS, Linux and Windows, with no jq needed.

Example 1: block edits to protected files (PreToolUse)

.claude/hooks/protect_files.py

import json
import sys
from pathlib import PurePosixPath

data = json.load(sys.stdin)
path = PurePosixPath(data.get("tool_input", {}).get("file_path", "").replace("\\", "/"))
name, parts = path.name, set(path.parts)
blocked = (
    (name == ".env" or (name.startswith(".env.") and name != ".env.example"))
    or name == "package-lock.json"
    or ".git" in parts
    or "secrets" in parts
)
if blocked:
    print(f"Blocked: {path} is protected. Ask the user to change it.", file=sys.stderr)
    sys.exit(2)  # exit 2 = block the call; stderr goes to Claude as the reason
sys.exit(0)

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect_files.py\"" }]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR is the project root, so the hook works whatever folder Claude is in. Use python3 on macOS or Linux if that is your interpreter’s name, or py on Windows. If your settings file already has a "hooks" object, add the event inside it rather than a second "hooks" key. Test it by asking Claude to add a comment to .env: the edit is refused and Claude sees the Blocked: line. A hook only guards the tools it matches, and this one stops edits only. Add Read(./.env) and Edit(./.env) (and the same for ./secrets/**) to permissions.deny in your settings, so Claude can neither read the secrets into its context nor change them with its file tools. Bash remains the gap: narrow it with Bash deny rules and Claude Code’s Bash sandboxing (/sandbox).

Example 2: restrict a subagent's Bash commands (PreToolUse allow-list)

In our subagents guide a file-qa agent measures a rendered vertical video with ffprobe. Its prompt says “run only ffprobe”, but a prompt is a request. A hook in the agent’s own frontmatter turns it into a rule, active only while that agent runs:

.claude/agents/file-qa.md, frontmatter

---
name: file-qa
description: "Technical QA of a rendered vertical video file. Use after every render, before posting."
tools: Bash
model: haiku
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: 'python "$CLAUDE_PROJECT_DIR/.claude/hooks/only_ffprobe.py"'
---

.claude/hooks/only_ffprobe.py

import json
import shlex
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")


def decide(decision, reason):
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": decision,
        "permissionDecisionReason": reason,
    }}))
    sys.exit(0)


if any(ch in command for ch in ";&|<>`$\n\r{}*?[]~#()"):
    decide("deny", "One plain ffprobe command only: no pipes, redirects, chaining, substitutions, globs or braces.")
try:
    args = shlex.split(command)
except ValueError:
    decide("deny", "Could not parse the command.")
if not args or args[0] != "ffprobe":
    decide("deny", "This agent may run ffprobe only.")
if any(a in ("-o", "-report") for a in args[1:]):
    decide("deny", "ffprobe may not write files here (-o and -report are blocked).")
decide("allow", "Plain ffprobe probe.")

Rejecting shell metacharacters first matters: ffprobe x.mp4; rm -rf renders starts with ffprobe too. So does ffprobe -o, which writes its output to a file, hence the last check. Braces matter too: ffprobe x.mp4 {-o,out.txt} expands to -o out.txt before ffprobe runs, so they are refused with the other shell characters. A deny from a hook holds in every permission mode, even bypassPermissions. An allow skips the permission prompt but never overrides a deny rule in your settings.

Example 3: send failing tests back to Claude before it stops (Stop)

.claude/hooks/tests_before_stop.py

import json
import os
import subprocess
import sys
import tempfile
from pathlib import Path

MAX_TRIES = 3
data = json.load(sys.stdin)
counter = Path(tempfile.gettempdir()) / f"claude-stop-{data.get('session_id', 'default')}.txt"
tries = int(counter.read_text()) if counter.exists() else 0

project = os.environ.get("CLAUDE_PROJECT_DIR") or data.get("cwd")
result = subprocess.run(
    "npm test --silent", shell=True, capture_output=True, text=True,
    cwd=project, env={**os.environ, "CI": "true"},  # CI=true keeps test runners out of watch mode
)
if result.returncode == 0 or tries >= MAX_TRIES:
    counter.unlink(missing_ok=True)  # tests pass, or out of tries: let Claude stop
    sys.exit(0)
counter.write_text(str(tries + 1))
tail = (result.stdout + result.stderr)[-1500:]
reason = f"Tests fail (try {tries + 1} of {MAX_TRIES}). Fix them before finishing:\n{tail}"
print(json.dumps({"decision": "block", "reason": reason}))

When the suite fails, Claude gets the failing output as its next instruction instead of ending the turn, up to three times in a row; after that Claude may stop, the counter resets and you decide. The official docs suggest checking the stop_hook_active input field to avoid endless loops, but that allows only one retry; a small counter allows a few. Claude Code also overrides a Stop hook that blocks eight times in a row with no tool call in between. Stop fires whenever Claude finishes a reply, so keep the suite fast or run only the tests for what changed. Register it with a timeout longer than your suite takes (in seconds; Stop needs no matcher):

.claude/settings.json

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/tests_before_stop.py\"", "timeout": 300 }] }
    ]
  }
}

Example 4: add context after a tool runs (PostToolUse)

A PostToolUse hook cannot undo anything, but it can tell Claude something. This one, registered for Edit|Write, warns Claude when it edits a generated file so the next change goes to the spec instead:

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/generated_note.py\"" }]
      }
    ]
  }
}

.claude/hooks/generated_note.py

import json
import sys

data = json.load(sys.stdin)
path = data.get("tool_input", {}).get("file_path", "").replace("\\", "/")
if "/src/generated/" in path:
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": "This file is generated from the episode spec and is overwritten on the next render. "
                             "Make the change in episodes/<id>/spec.json instead.",
    }}))

To re-inject key rules after the conversation is compacted, a SessionStart hook with the matcher compact can print them; plain stdout from SessionStart goes straight into Claude’s context.

Example 5: a desktop alert when Claude needs you (Notification)

~/.claude/settings.json (Linux)

{
  "hooks": {
    "Notification": [
      { "hooks": [{ "type": "command", "command": "notify-send 'Claude Code' 'Claude Code needs your attention'" }] }
    ]
  }
}

Put it in your user settings so it works in every project. On macOS, use osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"' as the command; the official hooks guide also has a PowerShell version for Windows.

Debugging hooks and common mistakes

Exit 1 for a policy. It only logs an error. Block with exit 2 or a deny decision.
JSON that never parses. Stdout must be a single JSON object. A shell profile that echoes text on startup breaks it; so does building JSON by string concatenation. Use a JSON encoder.
Fields at the wrong level. permissionDecision sits inside hookSpecificOutput; decision for Stop and PostToolUse is top level.
Scripts that are not executable. On macOS and Linux a script called directly needs chmod +x; calling it as python script.py avoids that. On Windows, Claude Code runs command hooks through Git Bash; if it cannot find Git Bash, the hook fails.
Slow hooks on hot events. PostToolUse runs after every matching call, in parallel when Claude makes parallel calls. Keep it to milliseconds or narrow the matcher.
Treating hooks as a sandbox. A hook sees only the tools it matches, and string checks on commands can be bypassed. For hard limits, use permission rules and the Bash sandbox as well.

Hooks complete the set: CLAUDE.md holds the project rules, a skill says how to do a job, subagents check it with a fresh context, and hooks enforce the lines nobody may cross. If you make short vertical videos with Claude Code, the skill below packages the spec-first workflow that Examples 2 and 4 come from.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.

Claude Code subagents: how to create and use them (with examples)

Mohd Yusuf Khan — Mon, 02 Nov 2026 13:04:48 +0000

Originally published on Homingo Learn.

A Claude Code subagent is a second Claude with its own context, tools and instructions. Used well, it keeps your main session clean and gives you a reviewer that did not write the work.

What is a Claude Code subagent?

A Claude Code subagent is a separate Claude instance that your main session passes a task to. It starts with a fresh context window, its own system prompt and, if you say so, a restricted set of tools. It works on the task, and only its final summary comes back into your conversation. That one property explains when subagents help: anything that reads a lot (logs, test output, a folder of frames) and anything that should be judged by someone who did not do the work.

How to create a Claude Code subagent

The usual way is one Markdown file with YAML frontmatter. Put it in .claude/agents/ to share it with everyone working in the repository, or in ~/.claude/agents/ to have it in all your projects; if both define the same name, the project one wins. (Subagents can also be passed as JSON with the --agents flag, or come with a plugin.) Write the file yourself, or describe the agent you want and ask Claude to write it; depending on your version, /agents also opens a menu for this. Claude Code picks up edits to existing agent files within seconds; a newly created agents folder needs a restart of the session.

.claude/agents/stills-reviewer.md

---
name: stills-reviewer
description: "Reviews storyboard stills of a vertical video against its episode spec. Use proactively after stills are rendered and before the full render."
tools: Read, Glob, Grep
model: sonnet
---

You review storyboard stills for a 1080x1920 short video. You did not write the
spec or make the stills.

Inputs: the episode spec (spec.json) and a folder of stills, one per shot.
Safe area: everything except the top 15% and the bottom 35% of the height and
6% at each side, where platform buttons and captions sit.

For every shot:
1. Look at the still first and write one sentence: what a first-time viewer
   would understand from it alone.
2. Then read the shot's line in the spec.
3. FAIL the shot if your sentence does not match the spec's intent, if the
   subject or any caption is outside the safe area, or if a caption is unreadable.

Return a table (shot id, PASS or FAIL, one-line reason) followed by one line
with the PASS and FAIL totals, and nothing else. Never edit files.

Only name and description are required. The fields you will use most:

name: the unique identifier you call the agent by. Lowercase words joined by hyphens are the safe convention.
description: when Claude should pass work to this agent. It is the routing rule, so write it like the request it should catch.
tools: an allowlist, comma-separated or as a YAML list. Leave it out and the agent inherits every tool available to subagents. A reviewer that only has Read, Glob, Grep cannot change anything by accident. disallowedTools is the opposite: a denylist.
model: sonnet, opus, haiku, a full model ID, or inherit (the main session’s model). Routine checks run well on a smaller, cheaper model.
maxTurns, permissionMode, hooks, skills (skills preloaded into the agent) and isolation: worktree (work in a temporary git worktree) cover the rarer cases.

Claude Code changes quickly. The fields and flags in this guide follow the official subagents documentation as of November 2026; check there before relying on a rarer one.

How to use a subagent: automatic and explicit delegation

Claude delegates on its own when a task matches an agent’s description; phrases like “use proactively” make that more likely. You can also be explicit: ask in plain words (“Use the stills-reviewer subagent on renders/ep04/stills against episodes/ep04/spec.json”), or type @ and pick the agent from the list, which guarantees that agent runs. To make one agent the whole session, start Claude Code with claude --agent stills-reviewer.

Fresh context: what the subagent does not know

A subagent does not see your conversation or the files your main session already read. It gets its own system prompt, the delegation message Claude writes for it, your CLAUDE.md files and the environment basics. Two consequences:

Put the method in the agent file, not in the chat. Anything the agent needs every time (what to check, what a FAIL is, what to return) belongs in its prompt.
Ask for a short, fixed return format. The summary is all that comes back. A table of PASS and FAIL lines costs your main session a few hundred tokens; a raw dump of everything the agent read costs thousands and defeats the point.

Example: three reviewer subagents that check a reel

Short-form video is a good fit, because each check is independent and each one reads a lot. Three subagents, each with the fewest tools it needs, each used at its own stage: story-reader judges the spec before any pictures exist, stills-reviewer (above) judges the storyboard stills, file-qa measures the rendered file.

.claude/agents/story-reader.md

---
name: story-reader
description: Reads an episode spec as a first-time viewer and checks the story. Use before stills are made.
tools: Read
model: sonnet
---

Read spec.json once, as a stranger who sees only what is on screen and in the captions.
Answer each with PASS or FAIL and one line of reason:
1. Hook: does the first shot show a situation that raises a question?
2. Beats: does every shot add information or raise a new question?
3. Payoff: does the ending answer the question the hook raised?
4. Clarity: can every shot be described as one readable action?
Then one line with the totals, and nothing else. Never edit files.

.claude/agents/file-qa.md

---
name: file-qa
description: Technical QA of a rendered vertical video file. Use after every render, before posting.
tools: Bash
model: haiku
---

Run only ffprobe. For the file you are given (replace FILE with its path):
  ffprobe -v error -show_entries stream=codec_type,width,height,r_frame_rate:format=duration -of json "FILE"
Report the measured values, then PASS only if: a video stream is 1080x1920,
its r_frame_rate is 30/1, the duration is between 15 and 90 seconds, and an
audio stream exists. One line per check, then PASS or FAIL overall.

Set the frame rate and duration in file-qa to your own targets. Note that a prompt saying “run only ffprobe” is a request, not a limit: an agent with Bash can run anything Bash can. Keep permission prompts on for it (no bypassPermissions), or add a PreToolUse hook to the agent that rejects every Bash command that is not ffprobe. The other two agents have no Bash at all, so they cannot change a file whatever their prompt says.

Each reviewer then runs at its stage: story-reader once the spec is written, stills-reviewer once the stills exist. After the render, one instruction runs the final pass: “Run stills-reviewer and file-qa on episode 4 in parallel and give me every FAIL.” Independent agents can run at the same time, and you read short reports instead of folders of output. Fix the FAILs in the main session, where the context about the episode lives, then run the reviewers again.

Subagents or skills?

A skill is a method the working session loads when it is relevant (only its description is always in context): steps, reference files and scripts. Use it for how to do a job. See how to write a SKILL.md.
A subagent is a separate worker with its own context. Use it to keep heavy reading out of your session, to run independent checks in parallel, or to get a review from someone who did not write the work.
Together: a production skill does the work in the main session; reviewer subagents check it. If a reviewer needs shared rules, preload only the checking part (a QA skill) through the skills field, not the production method, so it still judges as an outsider.

Common mistakes

Every tool for every agent. A reviewer with write access will eventually “fix” what it was asked to judge. Restrict it.
A subagent for a two-line job. Each one starts cold and has to gather its own context; small, quick edits are faster in the main session.
Expecting it to remember the chat. If the agent needs a decision you made earlier, it goes in the delegation message or in the agent file.
Long descriptions. Every agent’s description sits in the main session’s context. Keep it to the trigger; move the method into the body.

For the production side of the same workflow, see how to make AI horror Shorts with Claude Code and Claude Code skills for video.

Animated horror reels skill: Our whole playbook as a Claude Code agent skill: the hook-first story method, the episode spec template, the camera, light and grade system with a palette builder, a render-ready Remotion starter and the QA checks before you post. Make reels like ours. See the skill

Disclosure: this guide is by Homingo, the team behind the skill linked above. Everything in it works without it.

How to stop an AI agent infinite loop in Python (step caps, repeat checks)

Mohd Yusuf Khan — Mon, 02 Nov 2026 12:15:07 +0000

Originally published on Homingo Learn.

An agent stuck in an infinite loop, calling the same tool again and again, is a common way agent runs fail. A few small guards turn it into a clean stop with a reason.

Agent loops look alike: a search returns nothing useful, so the agent searches again with the same words; a test fails, the agent makes the same edit and runs it again; two steps undo each other. The model is not broken. It has no signal that it is repeating itself and no clear definition of finished. This guide adds both, in plain Python 3.10 or newer, around any agent loop that asks a model for the next action. Put the code blocks in one file, in order.

Frameworks have a step cap built in: LangChain’s legacy AgentExecutor has max_iterations (“Agent stopped due to iteration limit or time limit.”), LangGraph has recursion_limit (“Recursion limit of 25 reached without hitting a stop condition”), and the OpenAI Agents SDK has max_turns. A cap stops the bleeding, but it does not notice repeats or stalls, and by default it ends the run with an error or a fixed message instead of a usable result. The guards below add those.

Why LLM agents get stuck in loops

No memory of failure: the error is in the context, but nothing says “you already tried exactly this”.
No definition of done: “research this topic” never ends; “return three findings, each with a URL and a quote” does.
Errors that read like instructions: a tool that returns “try again later” gets tried again, immediately.
Nothing outside the model decides to stop. Stopping has to be enforced in code, not requested in the prompt.

1. Add a step cap, repeat detection and a no-progress check

One object, created fresh for every run and consulted on every turn, enforces a hard step cap, counts repeated tool calls and spots runs that stopped making progress:

import hashlib
import json
from collections import Counter, deque

class LoopStop(Exception):
    pass

TEXT_KEYS = {"query", "q", "question"}  # arguments where case and spacing do not matter

def normalize(args: dict) -> dict:
    """Treat "Python loops " and "python loops" as the same search; leave paths and code alone."""
    return {k: " ".join(v.lower().split()) if k in TEXT_KEYS and isinstance(v, str) else v
            for k, v in args.items()}

def call_key(name: str, args: dict, state: str = "") -> str:
    """state: a version of the world for tools whose answer depends on it (e.g. the git tree hash)."""
    return hashlib.sha256(json.dumps([name, normalize(args), state], sort_keys=True, default=str).encode()).hexdigest()

class LoopGuard:
    def __init__(self, max_steps: int = 25, max_repeats: int = 1, stall_steps: int = 5):
        self.max_steps, self.max_repeats, self.stall_steps = max_steps, max_repeats, stall_steps
        self.steps = 0
        self.calls: Counter[str] = Counter()
        self.recent: deque[str] = deque(maxlen=stall_steps + 1)

    def tick(self, fingerprint: str) -> None:
        """Call at the start of every model turn with a fingerprint of the useful state."""
        self.steps += 1
        if self.steps > self.max_steps:
            raise LoopStop(f"step cap of {self.max_steps} reached")
        self.recent.append(fingerprint)
        if len(self.recent) == self.recent.maxlen and len(set(self.recent)) == 1:
            raise LoopStop(f"no new useful result in the last {self.stall_steps} steps")

    def record_call(self, key: str) -> bool:
        """Records a tool call. Returns True if it repeats an earlier one; raises LoopStop
        when a call has been repeated more than max_repeats times."""
        self.calls[key] += 1
        if self.calls[key] > self.max_repeats + 1:
            raise LoopStop(f"the same call was made {self.calls[key]} times")
        return self.calls[key] > 1

The fingerprint is whatever represents real progress for your agent: the set of findings collected so far, the hash of the working tree for a coding agent, the list of files written. Errors and empty results do not count. If it has not changed in five steps, more steps rarely change it; tune stall_steps from your traces. Normalizing the search text catches near-identical searches, and passing a state (such as the working-tree hash) lets a coding agent rerun the tests after a real edit without it counting as a repeat.

2. Tell the agent it is repeating a tool call

The first repeat should not be fatal; it should be visible. Instead of running the tool again, return the earlier result with a note (the repeat branch of the full loop in step 4). That often breaks the loop, because the model finally sees that the same action gives the same answer. With max_repeats=1, the first repeat gets the note and a third identical call stops the run. Retry transient errors (“try again later”) with backoff inside each tool function (not shown), so the agent only ever sees a final result, never a decision about retrying.

3. Validate the finish step in code

Give the agent an explicit finish action with required fields, state that contract in its system prompt, and validate it in code. A finish that does not meet the contract is sent back with the exact reason, and that turn still counts against the step cap:

def check_finish(args: dict) -> str | None:
    """None if the result meets the contract, else the reason it does not."""
    findings = args.get("findings")
    if not isinstance(findings, list) or len(findings) < 3:
        return "finish needs at least 3 findings"
    for i, f in enumerate(findings, 1):
        if not (isinstance(f, dict) and str(f.get("url", "")).startswith(("http://", "https://"))
                and f.get("quote")):
            return f"finding {i} needs a url and a quote"
    return None

This checks the shape, not the truth: whether a quote really appears on its page needs a separate checker that fetches the source; see the source checker in how to build a multi-agent research system in Python.

4. The full agent loop, with partial results

def useful(entry: dict) -> bool:
    obs = entry["observation"]
    return bool(obs) and not (isinstance(obs, dict) and "error" in obs)

def fingerprint(results: dict) -> str:
    return hashlib.sha256(json.dumps(sorted(k for k, e in results.items() if useful(e))).encode()).hexdigest()

def run_agent(task: str, call_model, tools: dict, guard: LoopGuard | None = None) -> dict:
    """call_model(messages) returns {"tool": name, "args": {...}}; "finish" ends the run."""
    guard = guard or LoopGuard()  # one guard per run: it holds the run's counts
    messages = [{"role": "user", "content": task}]
    results: dict[str, dict] = {}  # per distinct call: tool, args, observation
    try:
        while True:
            guard.tick(fingerprint(results))
            action = call_model(messages)
            if not isinstance(action, dict):
                messages.append({"role": "user", "content": 'Reply with JSON: {"tool": ..., "args": {...}}'})
                continue
            name, args = action.get("tool"), action.get("args") or {}
            messages.append({"role": "assistant", "content": json.dumps(action)})
            if name == "finish":
                problem = check_finish(args)
                if problem is None:
                    return {"status": "done", "result": args, "steps": guard.steps}
                messages.append({"role": "user", "content": f"Not finished: {problem}"})
                continue
            if name not in tools:
                options = sorted([*tools, "finish"])
                messages.append({"role": "user", "content": f"Unknown tool {name}. Use one of {options}."})
                continue
            key = call_key(name, args)
            if guard.record_call(key):
                observation = {"note": "You already made this call. Same result as before; "
                                       "try a different approach or finish.",
                               "result": results[key]["observation"]}
            else:
                try:
                    observation = tools<a href="**args">name</a>
                except Exception as e:  # errors become observations, not crashes
                    observation = {"error": f"{name} failed: {e}"}
                results[key] = {"tool": name, "args": args, "observation": observation}
            messages.append({"role": "user", "content": json.dumps(observation, default=str)})
    except LoopStop as e:
        return {"status": "stopped", "reason": str(e), "steps": guard.steps,
                "partial": [x for x in results.values() if useful(x)]}

Three details matter. Every model turn counts, including malformed replies, rejected finishes and unknown tools, so the step cap is a true upper bound, and the progress check sees those empty turns too. A repeated call is not executed again, so a loop costs no extra tool calls. And a stop returns what was gathered (which tool, which arguments, what came back) plus the reason, which the caller can log, show or pass to a person, instead of an exception that loses the work. With a native tool-use API, the action is a tool-use block and the observation a tool result; the guards do not change.

A quick check with a fake model that keeps repeating the same search:

def search(query: str) -> list:
    return []  # nothing found, every time

def stuck_model(messages):
    return {"tool": "search", "args": {"query": "agent loops"}}

print(run_agent("Find three sources on agent loops", stuck_model, {"search": search}))
# {'status': 'stopped', 'reason': 'the same call was made 3 times', 'steps': 3, 'partial': []}

Tune the numbers from your traces, not by feel: look at how many steps successful runs take and set the cap a comfortable margin above that. Step caps do not bound a tool that hangs, so also give each tool call a timeout and the whole run a wall-clock deadline. A token budget checked before each call is the next line of defence; see the budgets section of our guide to agent traces, budgets and evals.

Prompt changes that help (but never replace the guards)

State the finish contract in the system prompt, in the same words the checker uses.
Make tool errors specific and actionable: “no results for this query; try fewer or different words”, not “failed”.
Ask for a one-line plan field in each action ({"plan": "...", "tool": ..., "args": ...}); the loop ignores it, but repeats become obvious to the model as well as to you.

For the bigger picture, with several agents sharing a planner, a tool layer and a checker, see how to build a multi-agent research system in Python.

Multi-agent systems: build an AI research team: Six modules, each with a short video lesson, a quiz check and a hands-on coding round that adds a tested piece of the team to your own repo. Together they cover the planner contract, handoffs, the tool layer, shared memory, the source checker, budgets, traces and an eval gate. The capstone is your team running live on a topic of your choice, with its reports, eval scores and code in a public GitHub repo. For builders who know Python and have called a model API. Certificate on completion. See the course

Disclosure: this guide is by Homingo, the team behind the course linked above. Everything in it works without it.

How to test an LLM agent: traces, budgets and an eval gate in CI (Python)

Mohd Yusuf Khan — Mon, 02 Nov 2026 12:02:52 +0000

Originally published on Homingo Learn.

An agent you cannot measure is an agent you cannot change safely. Three pieces make it measurable: traces, budgets and an eval gate.

Unit tests cover the deterministic parts of an agent: parsers, validators, tool wrappers. They say nothing about whether the agent still does its job after you change a prompt. For that you need three things working together: traces that record what each step did, budgets that stop a run before it burns tokens in a loop, and an eval gate that scores the agent on fixed tasks and fails the build when the score drops. This guide builds all three in plain Python.

1. Trace every step as one JSON line

Write one line per model call or tool call: which agent, which task, what it did, how many tokens, how long, and how it ended. JSON Lines files are easy to grep, diff and load into a notebook.

import json
import time
from contextlib import contextmanager

class Tracer:
    def __init__(self, path: str, run_id: str):
        self.path, self.run_id = path, run_id

    @contextmanager
    def step(self, agent: str, task: str, kind: str):
        rec = {"run": self.run_id, "ts": time.time(), "agent": agent, "task": task, "kind": kind, "tokens": 0}
        start = time.perf_counter()
        try:
            yield rec  # the caller fills rec["tokens"], rec["attempt"], rec["input_chars"], ...
            rec.setdefault("status", "ok")
        except Exception as e:
            rec["status"], rec["error"] = "error", str(e)
            raise
        finally:
            rec["ms"] = round((time.perf_counter() - start) * 1000)
            with open(self.path, "a", encoding="utf-8") as f:
                f.write(json.dumps(rec, default=str) + "\n")

When a report comes out wrong, the trace tells you which agent produced the bad step, how many tokens and how long it took, and (if you fill those fields) its input size and attempt number, instead of a guess.

2. Budgets: check before every call

Agents loop. A tool returns an error, the agent tries again, and again. A budget object checked before each model call turns that into a clean stop with a clear reason:

class BudgetExceeded(RuntimeError):
    pass

class Budget:
    def __init__(self, total_tokens: int, per_agent_tokens: int, max_calls: int):
        self.total, self.per_agent, self.max_calls = total_tokens, per_agent_tokens, max_calls
        self.used, self.by_agent, self.calls = 0, {}, 0

    def check(self, agent: str, estimate: int) -> None:
        """Call before every model call; counts the attempt even if the call then fails."""
        if self.calls + 1 > self.max_calls:
            raise BudgetExceeded(f"call cap {self.max_calls} reached")
        if self.used + estimate > self.total:
            raise BudgetExceeded(f"run budget {self.total} tokens would be exceeded")
        if self.by_agent.get(agent, 0) + estimate > self.per_agent:
            raise BudgetExceeded(f"{agent} would exceed {self.per_agent} tokens")
        self.calls += 1

    def charge(self, agent: str, tokens: int) -> None:
        """Call after a model call with the real token count from the API response."""
        self.used += tokens
        self.by_agent[agent] = self.by_agent.get(agent, 0) + tokens

Charge the real token count from the API response after each call, not the estimate. The estimate (for example, prompt characters divided by four plus the maximum output tokens) only decides whether to make the call at all.

def call_model(agent, task, prompt, budget, tracer, client, max_out=800):
    budget.check(agent, estimate=len(prompt) // 4 + max_out)
    with tracer.step(agent, task, "model") as rec:
        rec["input_chars"] = len(prompt)
        reply = client.complete(prompt, max_tokens=max_out)  # your model client
        rec["tokens"] = reply.input_tokens + reply.output_tokens
    budget.charge(agent, rec["tokens"])
    return reply.text

One model call with both pieces wired in.

3. An eval set: fixed tasks, a score, a threshold

Pick a small, fixed set of tasks that represent the job: ten to twenty is enough to start. For each run, compute a score you can defend. For a research agent that writes cited reports, a good one is the share of report sentences that a separate checker marks as supported by their cited sources; add the run’s token count and failure count next to it.

import json
import statistics
import sys
import traceback

from agents.team import run_agent  # returns an object with .sentences, .supported, .tokens

def load_tasks(path: str) -> list[dict]:
    with open(path, encoding="utf-8") as f:
        return json.load(f)  # e.g. [{"topic": "..."}, ...]

def run_evals(tasks, min_score: float = 0.85) -> int:
    if not tasks:
        print("eval: no tasks")
        return 1
    scores, failures, tokens = [], 0, 0
    for task in tasks:
        try:
            result = run_agent(task)
            scores.append(result.supported / max(1, result.sentences))
            tokens += result.tokens
        except Exception:
            failures += 1
            scores.append(0.0)
            traceback.print_exc()
    mean = statistics.mean(scores)
    print(f"eval: mean {mean:.3f} over {len(tasks)} tasks, {failures} failed, {tokens} tokens, threshold {min_score}")
    return 0 if mean >= min_score and failures == 0 else 1

if __name__ == "__main__":
    sys.exit(run_evals(load_tasks("evals/tasks.json")))

evals/run.py (run with python -m evals.run). run_agent is your agent entry point.

4. Run the gate in CI

Run the eval script on every pull request that touches prompts, agent code or dependencies. The exit code is the gate. Keep the API key in the repository’s secrets (note that secrets are not passed to pull requests from forks, so the gate only runs on branches in your own repository):

name: agent evals
on:
  pull_request:
    paths: ["agents/**", "prompts/**", "evals/**", "requirements.txt"]
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: python -m evals.run
        env:
          MODEL_API_KEY: ${{ secrets.MODEL_API_KEY }}

.github/workflows/evals.yml

What to watch over time

Score and cost together. A prompt change that raises the score but doubles the tokens is a trade-off, not a win.
Failure rate. A run that crashes on one task in twenty will likely crash on a similar share of real tasks.
Variance. Model output varies between runs, so a single run near the threshold can flap. Run the set two or three times and gate on the mean, or keep a small margin above the threshold.

These pieces slot into a full agent team: see our multi-agent research system guide for the planner, researchers, shared memory and source checker they measure.

Multi-agent systems: build an AI research team: Six modules, each a short video lesson, a quiz check and a hands-on coding round that adds one tested piece of the team to your own repo: the planner contract, handoffs, the tool layer, shared memory, the source checker, budgets, traces and an eval gate. The capstone is your team running live on a topic of your choice, with its reports, eval scores and code in a public GitHub repo. For builders who know Python and have called a model API. Certificate on completion. See the course

Disclosure: this guide is by Homingo, the team behind the course linked above. Everything in it works without it.

How we structure an animated horror reel with Claude Code: timed spec first, then shots, then QA

Mohd Yusuf Khan — Mon, 02 Nov 2026 06:33:54 +0000

When you ask Claude Code to "make a 60-second horror reel", it will happily start writing components. Twenty minutes later you have a video that renders, moves and looks fine, and nobody watches past second three.

The problem is not the code. The problem is that the story decisions were never written down, so nothing could check them. The fix that worked for us is boring and very effective: the agent writes a timed spec first, then builds shots from it, then runs checks before anything is posted. This post walks through that structure so you can use it in your own short-form video projects, horror or not.

1. Why the spec comes before any code

Short vertical video is judged in the first few seconds. If the viewer doesn't know who, where and what is at stake almost immediately, they scroll. Those are story decisions, and they are easy to get wrong when they only live inside a component tree.

So the first thing Claude produces is a single JSON file that describes the whole episode. Code is generated from it later. Because the decisions are data, they can be linted.

A trimmed example (a new story, written for this post):

{
  "title": "Floor 13",
  "fps": 30,
  "logline": "A night-shift guard sees the lift stop at a floor the building does not have, and it is calling him.",
  "hook": { "line": "The lift just stopped at thirteen. We only have twelve floors.", "pattern": "impossible situation" },
  "newcomer": { "who": "night guard", "where": "empty office tower, 3 AM", "stakes": "he is alone and the doors are opening", "lineAt": 3.2 },
  "want": { "text": "keep the doors shut until the morning shift", "at": 6.5 },
  "cliffhanger": { "type": "reveal", "line": "The panel shows a fourteen now. And it's lit." }
}

A few rules we lint on every spec:

The hook lands in the first seconds. Frame 0 is already an event (doors opening, a light failing), never a slow establishing shot. The hook line has a named shape: impossible situation, status reversal, ticking clock, shocking reveal or payoff first.
Who, where and stakes by about 5 seconds; the want by about 8. If the line that completes them starts later, the spec fails.
A question ladder. Every open question has an opens and closes time. A new question every 10 to 15 seconds, and never more than three open at once, otherwise the viewer gets lost instead of curious.
One cliffhanger type per episode, rotated. Threat, reveal, revelation, decision, clock. Repeating the same type two episodes in a row is flagged.

None of this needs AI to check. It is a small Node script that reads the JSON and prints PASS or FAIL per rule. Claude fixes the spec until it passes, then moves on.

2. Shots: every shot carries what the viewer sees and what they should understand

Next, the spec gets a shot list. Shots are continuous (each start equals the previous end) and each one has a beat: frame0, hook, want, escalation, scare, turn, reveal, cliffhanger, endcard.

The two fields that helped us most are sees and understands:

{
  "id": "s05", "beat": "scare", "start": 14.0, "end": 18.0, "framing": "wide",
  "sees": "The corridor lights go out one by one towards the camera; the last one stays on over the lift",
  "understands": "Something is coming down the corridor, and the lift is the only lit thing left",
  "camera": { "zoom": [1.0, 1.12], "drift": 0.4, "ease": "slowIn" },
  "light": { "level": 0.8, "flicker": 0.25 },
  "scare": { "kind": "approaching darkness", "at": 15.5 }
}

Writing understands forces you (and the agent) to say what the shot is for. If you can't fill it in, the shot is decoration and should go. Camera, light and events are plain numbers, so the render code stays dumb: it reads the shot and draws it. Changing the story never means hunting through components.

Two craft rules that live in the shot data:

Silence before a scare. Set an end on the narration line before the scare so there is a real gap. The quiet does more than any sound effect.
Rotate scare mechanisms. Each scare has a kind. Two scares in one episode must use different mechanisms, and a mechanism used too often across a series gets flagged.

3. QA before anything is posted

Rendering a long vertical video takes a while, so we check cheaply first and expensively last.

Spec lint (seconds): the timing and story rules above.
Blind read (a minute): render one still per shot. Someone (or a separate model session) who has not read the spec writes one line per still describing what is happening. Compare that with the understands field. Any shot where the two don't match gets redrawn before the full render. Two rounds max; after that the shot is rethought, not polished.
Technical QA (after the render): 1080x1920, expected duration, audio present, captions in sync, no frame held static for more than about two seconds.
Uniqueness check: the posted spec is copied into a history folder, and new episodes are compared against it, so the same hook pattern or cliffhanger type doesn't sneak back three episodes later.
A separate reviewer scores hook and overall. The reviewer is never the session that wrote the script.

The point of the order is that the expensive mistakes (a story nobody follows) are caught when they cost seconds, not after a render.

4. How Claude Code fits in

We keep the method in a Claude Code skill: a SKILL.md that tells Claude the order (story, spec, lint, palette, staging, stills and blind read, voice-over, render, technical QA, uniqueness, review), plus reference files for the story rules, the spec format, camera and lighting, and QA. Claude reads the reference only when the step needs it, so the context stays small. You direct the story; Claude writes the code and runs the checks.

If you want to try the pattern without anything from us: start with one JSON spec, write five lint rules you care about, add sees/understands to every shot, and refuse to render until the spec passes. You'll feel the difference on the first episode.

Our version

We packaged the full method as the Animated Horror Reels Skill for Claude Code: SKILL.md and reference guides (story method, timed episode spec, camera, light and colour grade with a palette builder, QA and uniqueness checks) plus a render-ready TypeScript/React 1080x1920 starter project with caption timing and the check scripts. Skill Rs 1,499, one-time; the Complete Kit (Rs 4,599) adds video lessons, written guides, cheat sheets, an example project and a full demo episode project with its finished render. It needs Claude Code, Node.js and ffmpeg (Claude plan not included). Details: https://learn.homingo.co.in/skill

Disclosure: I'm with Homingo, this is our product.

A free online AI hackathon open to all of India: dates, format and scoping the build (registration closes 15 Nov)

Mohd Yusuf Khan — Mon, 12 Oct 2026 07:00:38 +0000

Homingo Hack Days is a free, online AI hackathon open to anyone in India. This post has the dates, the format and a few notes on scoping a build of about two weeks, for anyone who is deciding whether to enter.

The facts

Format: online, open to all of India, free to enter
Tracks: Agents, Automation, LLM apps
Team size: solo, or a team of 2 to 4
AI tools: allowed
Registration closes: 15 Nov 2026, 11:59 PM IST
Build phase: 21 Nov to 6 Dec 2026
What you submit: a public GitHub repository and a short demo video
Prizes and certificates: Rs 5,000 to the winner, recommendation certificates for the top 3, and a certificate for everyone who submits
Organiser: Homingo

Registration: https://hackathon.homingo.co.in/?utm_source=devto&utm_medium=community&utm_campaign=hackdays

Scoping a build of about two weeks

About two weeks is short. These notes are general advice for any hackathon of this length, not judging criteria.

Pick one user and one job. "An agent that helps students" is a theme. "An agent that reads a course PDF and makes a revision plan with page references" is a project. The second one can be shown working quickly.

Get the unglamorous path working first. For an agent, that is one complete run from input to a useful result, with the tool calls logged. For an automation, it is one real input going through every step without manual help. For an LLM app, it is one question answered from your own data with the source shown.

Decide early how you will know it works. Write down ten realistic inputs before you write much code. Run them every day. A short table in the README of what passed and what failed says more than a long feature list.

Keep the repository readable. Since the submission is a public repository, a README with setup steps, a sample input and the expected output matters. Someone should be able to clone it and run it.

Record the demo from a clean start. Show the project working from a fresh run, including one case where it handles a bad input. Keep it short.

Using AI tools

AI tools are allowed here, so the useful question is how to use them well. Let the assistant write the boilerplate, and spend your own time on the parts that decide whether the project works: the data, the prompts, the checks, and what happens when a step fails.