▶ YouTube Summaries

• YT :: https://www.youtube.com/watch?v=e1snsuY4lTI
• Original title :: I made Claude smarter by writing it a letter

Theo spent roughly six hours rewriting his global AGENTS.md / CLAUDE.md files and another six to ten testing the result, and reports an outsized improvement in day-to-day agent work. The core insight is that most of the value is not in making the model technically better at code but in making it communicate the way he wants — PR titles and descriptions a human can read, plans delivered as HTML documents, screenshots and videos uploaded and embedded. He also walks through how he audited his own agent history with agents to find real failure modes, how skill descriptions should be written as trigger keywords rather than explanations, and why he deliberately refuses to publish the files themselves.

Why the rewrite happened

He had been shipping dozens of PRs in a few days, largely because T3 Code makes it easy to run work across several machines in parallel. He runs four or five boxes, and managing which skills live on which machine got messy enough that he started building a custom system for it, then abandoned it. What replaced it is a "fleet" repo: a pile of markdown files (core AGENTS.md/CLAUDE.md, plus skills split into Claude-only, command-center-only, and universal folders), a fork of a CLI proxy, and per-skill metadata saying which machines should get which skill. Syncing is just an agent with SSH access over Tailscale pushing the files out.

The old global file had sat untouched for close to two years: a precedence note (repo instructions override globals, user instructions override both), one TypeScript rule about avoiding any, instructions to not spin up dev servers, package manager and tech preferences, and a machine inventory an agent had added. He describes it as not great and something he simply lived with.

The new global file is written as a letter

The new file opens by introducing himself — who he is, what he builds, and that he favours building complex things as simply as possible and reducing complexity. That two-sentence preference statement alone measurably curbed overeager models that rush to write more code than needed. He writes the whole file in his own conversational voice deliberately, because models tone-match: talk to the model a certain way and it answers that way.

The rest is bulleted preferences where bullets make sense:

• Keep things simple; type safety is useful; propose bold ideas that meaningfully help.
• Be careful with destructive actions not explicitly requested.
• Tests are good, but endless smoke and regression tests are slop — keep them focused.
• Comments should concisely describe how functions and classes are used, not annotate every line, and must be kept in sync when code changes.
• TypeScript that reads like a Python developer wrote it is bad TypeScript; avoid one-liner casting wrappers. Default stack picks (Zustand, React Query, TanStack Chart, Clerk or Better Auth, Drizzle or Zod) apply only when the repo has no existing choice.
• "Questions are read only" — asking about the project must not trigger edits.
• "Match ceremony to the task" — no subagents or multi-agent panels for work a single agent finishes in one pass; delegation is for breadth or adversarial review. When agents do run in parallel, state file ownership upfront so they do not collide.
• Visual work: do not edit real components first; prefer dark mode with white text for contrast.
• A blast-radius section to keep production environments safe, plus pull request rules.

He refuses to publish the file. The point, he argues, is not the exact wording but the reasoning and the path that produced it; copying someone else's globals is like adopting a stranger's generic code template for everything you will ever touch. These files influence every agent run you do, so you should own and continuously edit them.

Skill descriptions are trigger keywords, not descriptions

The description field of a skill is always loaded into context whether or not the skill is used, so its job is solely to tell the model when to pull the skill in. He has seen skills whose description contains so much detail that the skill body becomes redundant. His babysit-PR skill could drop its explanatory sentence entirely and be just "use when the user asks to monitor, watch, or babysit a PR". File-PR follows the same shape: "use when the user asks to file, open, or create a PR". Once the keywords were right, triggering worked well enough that he could split what had been one combined skill into two — which he wanted anyway, since he often needs one without the other. Late in the video he adds "or if they mention HTML with no additional context" to his HTML skill so a bare "HTML" at the end of a prompt is enough to trigger it.

The PR skills

The babysit skill exists because his repos carry three or four AI review bots. It tells the agent to use PR-monitoring tools if the harness has them, otherwise poll; act only on comments and checks newer than the last push; verify every bot finding against the source before changing code; distinguish real CI failures from infrastructure flakes; reply with a written reason when dismissing a false positive; watch main and rebase; stop and report if another PR makes this one obsolete, asking before closing; and loop until green and approved. Comments posted on his behalf must be formatted with the model slug and a note that the agent is responding for Theo. The line he calls most important: do not let review feedback expand the PR beyond the user's original goal.

The file-PR skill targets a specific pain — PR titles and bodies that no human can parse. It instructs: check whether a PR for the branch already exists; review the diff against origin/main; follow the repo's title conventions since titles become commit messages; and open with a plain explanation of the problem taken from the user's original prompt, then the solution, never an implementation inventory. He includes concrete bad/good pairs, e.g. a title about negotiating per-message deflate on the websocket versus one saying the change cut websocket frame size by 70% with gzip. Models respond very well to explicit bad/good examples — when you catch an agent doing something you have to fix by hand, put that instance in a skill and you have seeded its weights with what you actually care about. He also bans draft PRs (Codex opens them constantly and review bots then never run) and asks for a trailer noting which model and harness made the change — Claude and most harnesses know their own slug; Codex does not put it in the system prompt, so it sometimes guesses wrong.

Auditing your own history to find failure modes

Rather than guessing what to fix, he asked agents to read his Claude Code and Codex history on a machine and break down the most common failure modes by model and harness, with frequencies. The results were concrete: Opus 5 was aggressively killing the wrong processes — often the very T3 Code instance it was running inside — with far more kill attempts in two days than another model accumulated over much longer; one model filed drafts about 40% of the time; there were repo-wide check runs burning build time unnecessarily; and bash error rates differed per agent. One audit measured corrections per 100 user messages per model, though he cautions the numbers are confounded by how he uses each model (hardest tasks and least context go to one, no UI work goes to another). Other categories: tool misuse, overbuilding, stopping early, skipping verification, rare but expensive regressions, and unasked edits.

The general technique he recommends: when a thread goes badly, ask the agent why it made that decision and what indicated that direction — the cause is often a stale line in your AGENTS.md or something misread early and then carried through context. When a supposedly simple change takes half an hour, ask the agent what it spent the time on and to categorize its tool calls into helpful and unhelpful groups.

Project-level AGENTS.md is not a README

A README gives humans and agents context to decide whether they want the code. An AGENTS.md tells an agent how to change the codebase and what it must know before doing so. There is overlap, but the file should be written for agents so they can work with the developer better, not for developers.

His T3 Code file opens with a compressed identity — a minimal GUI for coding agents, a Node websocket server wrapping provider CLIs, serving web, desktop and mobile clients, positioned as an open-source bring-your-own-subscription alternative to comparable desktop agent apps. That saves the agent several tool calls of orientation. Then "what makes T3 Code special", which functions as a list of things a change must never compromise: open at the core (users run forks, roadmap and code are public), performance without compromise (regressions typically come from too much data over websockets, GPU-pegging CSS animations, expensive list rendering), remote-ready (the websocket layer, local network, Tailscale, and their own tunnel solution), and multi-surface support across the hosted web app, the locally hosted web app, the Electron desktop app that can itself act as host server, and the React Native mobile app.

A "note from Theo" section carries the taste: ambitious ideas, simple systems, software that feels obvious; do not preserve complexity because it already exists; do not introduce machinery because it looks architecturally impressive; understand the real constraint, then fight for the smallest model that makes correct behaviour unsurprising; measure twice cut once, and YAGNI. Crucially he adds that these are good defaults rather than hard rules and that developer preferences override anything in the file — otherwise contributors get stuck fighting instructions he wrote. He also warns that most contributions come from T3 Code itself, often controlled remotely, so the agent must be careful about killing dev servers or touching user data — a rule that came directly from Opus repeatedly killing his running instance.

The glossary

The first defined term is "you", meaning the agent reading the file. Then "we/us/maintainers", "user" (the person driving coding agents through the product), "agent" (the coding agent a user runs, which may include the reader), "provider" (the agent runtime or harness being wrapped), "client" (web, desktop, mobile UIs), "environment" (one running server plus the filesystem, credentials and state it owns), and "project" (an environment-local workspace record rooted at a directory). The terms are deliberately simple and mostly ones the model already knows. The value is not comprehension — models infer intent fine — it is that the glossary makes the agent describe things back to you in your team's vocabulary.

Hit every surface

He calls the most common defect in the repo a change that works on the path you tested and is missing everywhere else. So the file has a checklist the agent must walk and report on before calling frontend work done: entry points (settings page, command palette, key bindings), all clients, shared logic in the shared package, each provider adapter (a provider-shaped feature needs an explicit per-adapter decision, even if that decision is "not supported"), and the contracts package describing everything crossing the wire. That last line alone fixed changes that were not reflected in contracts. "Reverse states" was another big one — features like settle and snooze shipped without their un-settle and un-snooze counterparts. Connection modes and docs round it out; the docs callout led him to split user-facing and maintainer docs into separate entry points, because models kept leaking internal implementation detail into user docs.

Other project specifics that came from real annoyances: telling the agent the repo uses a specific package manager and the exact invocation form (a run subcommand rather than the bare one, which behaves differently in that tool); instructions to use a custom home directory for dev servers so they do not clobber the running instance; how to share a dev server over the tunnel including the pairing token; saving the PID at spin-up so the right process gets killed later; explicit test-data instructions; one integrated pass in a real client for user-visible frontend changes, on request, using dedicated test skills rather than firing up computer use unprompted; PR guidance for outside contributors; a taste section (complexity at the adapter boundary, orchestration pure, UI dumb, inferred types over annotations, any is the enemy, no continuously repainted animations); and a note that security matters but should not be over-indexed on for dev-mode and maintainer-only features.

The payoff is much shorter prompts. Real examples he shows: picking mock options by letter and saying "do C plus D plus A, file and babysit"; describing a bug in two sentences and appending "diagnose and fix, file and babysit" and expecting a mergeable PR in fifteen minutes. He notes he never notices unnecessary complexity until it crosses a threshold — collecting the causes into the file keeps it below that line.

Machine and file-handling skills

A command-center-only "provision a box" skill came from configuring a laptop the way he wanted, having an agent read his config and shell history and write it all down, then having it set up another machine and correcting what it missed or overdid. It also maintains an HTML page describing every machine, its specs, role, connection methods, and baseline setup, colour-coded to match his terminal sessions.

A universal file-upload skill lets agents upload any local file — screenshot, screen recording, log, config, build artifact — to his own public file host and get back a URL. It has a "requires" metadata field so the skill is only installed on machines that hold the host token, and it is told to tell the user rather than guess if the token is unset. The skill body is a single curl-style command, a note that only the file's basename is needed because the service slugifies and adds a random suffix, instructions for embedding the URL in GitHub, and an ffmpeg command for encoding a GIF preview. The point is remote workflow: from the mobile app you can ask the agent to record what it built, upload it, and hand you a link — or embed the video directly in the PR.

The HTML communication skill

The skill he relies on most started as "HTML plans" and became "HTML communication": when the user wants a plan, spec, write-up, findings, summary, report, comparison, or set of UI mocks as a readable artifact, produce one self-contained HTML file capped at 512K, written like a spec rather than a landing page, and upload it to his single-command hosting service. UI mocks get labelled A, B, C for direct comparison and easy selection. The same file path is reused across iterations so the URL stays stable. It is told never to open a browser, never to claim the document is hosted before the upload succeeds, and not to verify in a browser unless asked.

On camera he splits it in two, mirroring the file-PR / babysit-PR split: an HTML-communication skill for producing documents, and a separate read skill whose only job is to fetch a hosted URL with the shell instead of reaching for web search or a browser. He also demonstrates his prompting habits while doing it — telling the agent to re-familiarize itself because he has edited files since the last prompt, and explicitly saying make the changes but do not commit or push yet. Giving the model a stop point, he says, makes life much better.

Takeaways

• The goal of globals and skills is not primarily to make the model write better code; it is to make the model communicate with you better. Outputs you actually want to read are the win.
• Write skill descriptions as trigger conditions with the keywords a user would say, not as explanations of the skill's contents.
• Feed the agent bad/good example pairs drawn from its own real mistakes.
• Use agents to audit your own history for failure modes and frequencies, then encode the fixes; interrogate bad threads and slow tasks for the cause.
• Keep AGENTS.md aimed at how to change the code, distinct from the README, and include a glossary so the agent talks back in your vocabulary.
• Add an explicit escape hatch saying user instructions override the file, so contributors are not fighting your defaults.
• Do not copy anyone else's globals or skill collection wholesale, including his — the value is in building them from your own observed failures.