My AGENTS.md & SKILLS.md Breakdown - CourtneyR.dev's 2nd Brain

My AGENTS.md & SKILLS.md Breakdown ![rw-book-cover](https://d34adp677peecb.cloudfront.net/static/images/article4.6bc1851654a0.png) 🔗 **Source:** [My AGENTS.md & SKILLS.md Breakdown](https://www.youtube.com/watch?v=e1snsuY4lTI#transcript) > [!note]+ Document Notes > tags: [ai-coding-agents, agents-md, skill-design, developer-tooling, prompt-engineering, llm-workflows] > author: Theo Browne (T3.gg) > source: T3.gg (YouTube) > reference: https://www.youtube.com/watch?v=e1snsuY4lTI > date created: 2026-08-17 09:15 > > > [!info] Generated analysis — not the author's words. Sections below are machine-written > > from the captured source. Only text inside `> [!quote]` blocks is verbatim from the author. > > Do not quote or attribute any other line to the named author. > > # 🏷️ Title: My AGENTS.md & SKILLS.md Breakdown (Don't copy them) >  ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - [T3.gg — Theo Browne's site/channel](https://t3.gg) - [WorkOS](https://soydev.link/workos) — episode sponsor, spoken shortlink - [Convex](https://swade.link/convex) — episode sponsor, spoken shortlink - [UploadThing](https://uploadthing.com) — Theo's file-upload product, referenced in transcript as "Uploading Ping" (near-certain ASR mis-hearing of "UploadThing") ## 📝 Summary - **What happened.** Theo Browne (T3.gg — T3 Chat, T3 Code, UploadThing) walks through a from-scratch rewrite of his global `AGENTS.md`/`CLAUDE.md`, his skill library, and the repo-specific `AGENTS.md` for T3 Code (his open-source coding-agent GUI), after a multi-day push where he says he coded more than at any point in the past year — mostly by editing markdown that steers his agents. - **Why it matters.** The video is a worked example of "prompt-as-infrastructure": the claim is that a few hours of disciplined instruction-writing, backed by auditing real agent failure logs across models, compounds into materially fewer bad PRs, less scope creep, and shorter prompts over time. It's a concrete counter-example to the common practice of copy-pasting a generic AGENTS.md template. - **Key stakeholders.** Individual developers and small teams configuring coding agents (Claude Code, Codex, Cursor, Fable/Opus/Sonnet-class models); T3 Code contributors specifically; by extension anyone maintaining Reader/Obsidian-style "skill" systems (directly relevant to this very pipeline's own skill-authoring practice). - **Risks and tradeoffs.** The approach is bespoke and self-referential — Theo explicitly refuses to publish the actual files, arguing the value is in the *process* (auditing failures, writing good/bad examples, tuning descriptions) not the artifact. That makes the video high-value as a method but low-value as a template, and it resists naive replication. There's also a highlighted security/safety risk (an agent aggressively killing unrelated processes) that got fixed only after repeated real-world damage, not proactively. - **Bottom line.** Treat `AGENTS.md`/`SKILLS.md` as living, audited artifacts tuned from observed failure patterns — glossary first, descriptions as trigger keywords not documentation, concrete good/bad examples, explicit stop points, and a repo-specific "what we never compromise on" list — rather than a one-time template you install and forget. ## 📖 Main Content - Theo frames the whole video around a personal productivity claim: dozens of PRs landed in days, credited partly to T3 Code (his product, a GUI wrapper around coding-agent CLIs) and partly to roughly two full days spent editing and testing markdown instruction files across five machines. - **Global files vs. repo files.** He distinguishes his *global* `AGENTS.md`/`CLAUDE.md` (used everywhere, ~2 years old, barely touched) from the *repo-specific* `AGENTS.md` for T3 Code (tuned heavily, rewritten from an audit of real failure logs). He argues a `README.md` is for humans/context; an `AGENTS.md` is operational instruction for how an agent should change code — different audience, different content, and conflating them is a common mistake he says he's covered in an earlier video ("deleting your Claude MD and agents MD"). - **Why he won't publish the files.** He states directly the value isn't the literal instructions but "the way I thought of it" — the reasoning path and the failure evidence that produced each line. Copying the file without the process is likened to cargo-culting a generic code template onto every project. - **Global `AGENTS.md` structure.** Self-introduction (tells the agent who Theo is and what he builds, tuned deliberately for tone-matching), a short list of general coding preferences (simplicity bias, type safety, caution on destructive actions, tests should be focused not "slop," comments describe function usage and stay in sync), TypeScript-specific tuning (explicitly countering models — he names GPT-5.6/"Soul" and Sonnet-4.5 by nickname — that write TypeScript "like a Python dev wrote it"), a "questions are read-only" rule (stops agents from editing when only asked a question), a "match ceremony to the task" rule (no sub-agent panels for simple single-pass work; delegation only for breadth/adversarial review), a file-ownership rule for parallel agents, visual/design constraints (no editing real components first, dark-mode contrast preferences), and a pull-request section pointing at dedicated skills. - **Skills as trigger-keyword systems, not documentation.** The core technical claim of the video: a skill's `description` field is *always* loaded into context (even when unused), so its job is to contain the keywords that make the model decide to pull the skill in — not to explain what the skill does. He demonstrates this by trimming an elaborate babysit-PR description down to "Use when the user asks to monitor, watch, or babysit a PR," and separately splitting a combined file+babysit PR skill into two single-purpose skills once descriptions alone reliably triggered the right one. - **Babysit-PR and File-PR skills.** Built from observed failure patterns: agents not disclosing they were commenting as an agent, PRs ballooning 3x by treating every reviewer comment as mission-critical, and vague/uninformative titles and descriptions. Fixes: explicit instructions to verify bot findings against source before acting, only respond to comments/checks newer than the latest push, format agent-authored comments with a "responding on behalf of Theo" prefix, and — called out as maybe the single highest-impact line — never let review feedback expand the PR beyond the user's original goal. - **Good/bad example pattern for PR titles and descriptions.** Theo shows an actual bad PR (title and description so vague he says even he can't reconstruct what it fixed) next to instructions with concrete before/after examples (e.g., a vague perf title vs. "perf(server): cut websocket frame size by 70% with gzipping"), and a rule to open descriptions with the *problem* in plain language before any implementation detail, never leading with an "implementation inventory." He states plainly that agents are good at pattern-matching to explicit good/bad examples, so embedding one or two real ones is more effective than abstract rules. - **Cross-model failure audit.** Rather than guessing at instructions, Theo had agents (Fable, Opus, GPT-5.6/"Soul") mine his own multi-machine chat history to quantify failure modes per model: Opus 5 disproportionately killed the wrong (often its own host) process; GPT-5.6/"Soul" filed draft PRs ~40% of the time and ran unnecessary repo-wide checks; only "Soul" made unasked-for edits to global files. He explicitly flags the Opus sample as small (used it only ~2 days) while still drawing a comparative conclusion from it. - **T3 Code repo `AGENTS.md`.** Built the same way — audit-driven, not aspirational. Opens with a glossary (You/We-us-maintainers/User/Agent/Provider/Client/Environment/Project) so that both the agent's understanding of instructions and its communication back to Theo use consistent terms. Follows with an explicit "what T3 Code is" briefing (so the agent doesn't spend early tool calls researching), then a short list of non-negotiables — open at the core, performance without compromise, remote-ready, multi-surface (web/desktop/mobile) — framed as things no change should ever break, alongside context like "100,000+ users" to calibrate caution given alpha status. - **"Note from Theo" — simplicity mandate.** A short, quotable block invoking YAGNI and "measure twice, cut once," instructing the agent not to preserve or introduce complexity for its own sake, and explicitly stating these are defaults a developer's stated preference can override — added because Theo noticed agent/user friction when the file's defaults silently won over what a user actually wanted in the moment. - **"Hit every surface" checklist.** Addresses a named recurring defect class: a change works on the one path tested and is silently missing from other surfaces (settings page, command palette, keybindings, other clients, docs). Extends to a "contracts package" rule (anything crossing the websocket/HTTP boundary must be reflected there) and a "reverse states" rule (any new state transition like settle/snooze must ship its inverse — unsettle/unsnooze — in the same change). - **Tooling quirks encoded directly into the file.** A specific complaint that Vite Plus's CLI requires `vp run dev` rather than the more intuitive `vp dev` (unlike `bun dev`/`pnpm dev`), which agents kept getting wrong until explicitly told — framed with visible frustration at the tool's design decision. - **Operational hygiene instructions.** Custom T3 Code home directories so spun-up dev servers don't collide with the running instance; sharing dev servers over Tailscale/Tailnet with the correct pairing token; saving the dev-server PID so the agent stops the *right* process (a direct response to the Opus-killing-processes failure mode); explicit test-data instructions; a rule to use one integrated real-client pass for user-visible front-end changes rather than spinning up computer-use tooling unnecessarily; a taste section (complexity belongs at the adapter boundary, orchestration stays pure, UI stays dumb, `any` is "the enemy"); and a rule that dev-mode security should not be over-indexed relative to its actual local/tailnet-only exposure. - **Live demo of the workflow.** Theo shows one-line prompts ("Do C+D+A. File and babysit.") producing a full mocked-UI-to-merged-PR flow, and a bug report ("...settle button... wasn't working... Right click settle did. Diagnose and fix, file and babysit.") producing a near-mergeable PR in ~15 minutes — presented as proof that the accumulated instruction tuning collapses prompt length over time. - **Command-center (machine-specific) skills.** A "provision a box" skill, built by having an agent inventory an already-configured machine's dotfiles/bash history/config and generalize a setup script for new machines, iteratively corrected based on what it missed or over-did. Includes a self-updating HTML dashboard of fleet machines, specs, and roles. - **File-upload skill.** Uploads local files (screenshots, recordings, logs, build artifacts) to a personal file host (`files.tslop.org`) and returns a public URL, gated by a `requires` metadata field so the skill doesn't even appear on machines lacking the auth token ("if it is unset, tell the user instead of guessing"). Theo frames this — and the whole video's throughline — explicitly: the goal isn't making the model write better code, it's making the model *communicate* with him better (screenshots/recordings embedded directly in PRs). - **HTML-communication / post-plan skill, and a live refactor.** Originally an overloaded "HTML planning" skill, reframed as "HTML communication" (any readable HTML artifact — plan, spec, write-up, comparison, UI mocks — for a human, uploaded to `postplan.dev`) and explicitly *not* for HTML shipped as product code. Theo runs a real prompt live, splitting it into two narrowly-triggered skills (`post-plan-read` for fetching a supplied postplan URL via shell instead of a browser; `html-communication` for producing one) — each description trimmed to bare trigger phrasing, including appending "...or if they mention HTML with no additional context" so a one-word "HTML" at the end of a prompt is enough to trigger it. - **Closing framing.** Theo explicitly states he never told viewers to copy his repo, comparing blind adoption of someone else's skill library to installing every package in someone else's `package.json` — the point is to build the muscle of auditing your own agents' failures and writing instructions from that evidence. ### 🗒️ Notes #### ⏱️ [00:00](https://www.youtube.com/watch?v=e1snsuY4lTI&t=0) Intro — coding surge and roadmap - Landed "dozens of PRs" in days; credits both T3 Code and ~2 days of markdown editing/testing. - Sets up the video's arc: streamlining across machines → writing/auditing agent instructions. #### ⏱️ [01:29](https://www.youtube.com/watch?v=e1snsuY4lTI&t=89) Sponsor: WorkOS - Pitch centers on auth as increasingly agent-facing (agents acting on behalf of users), not just harder-to-DIY enterprise auth (Okta/SAML/Duo/ADFS). #### ⏱️ [02:55](https://www.youtube.com/watch?v=e1snsuY4lTI&t=175) Old global AGENTS.md walkthrough - Prior file (~2 years old): precedence rules (repo-specific overrides global, user overrides both), TypeScript "avoid any" rule, dev-server-breaking-environment fix, package manager preference (bun over pnpm), a later-added YAGNI line "another agent might have added," and a fleet/computer-inventory section credited to "Soul." #### ⏱️ [05:49](https://www.youtube.com/watch?v=e1snsuY4lTI&t=349) New global AGENTS.md — self-intro, tone, glossary-adjacent framing - Opens with self-introduction to the agent, explicitly to leverage model tone-matching. - Adds a two-sentence proactivity dampener credited with reducing overeager code-writing from "overeager" models. - Coding preferences kept as bullets; TypeScript section separately tuned against models that "write TypeScript like a Python dev." #### ⏱️ [09:00](https://www.youtube.com/watch?v=e1snsuY4lTI&t=540) Why the file isn't published - States directly: value is in the reasoning path, not the literal instructions. - Comparison: copying the file = copying someone's generic code template for every project. #### ⏱️ [10:05](https://www.youtube.com/watch?v=e1snsuY4lTI&t=605) Babysit-PR skill origin - Built after noticing mixed quality when asking agents to "babysit" or "file" PRs on repos with 3-4 AI reviewers. - Failure modes fixed: uncredited agent comments, 3x PR bloat from over-addressing minor review comments. #### ⏱️ [12:50](https://www.youtube.com/watch?v=e1snsuY4lTI&t=770) Description = trigger keywords, not documentation - Central technical claim, demonstrated by trimming a long description to a one-line trigger phrase. - Splitting babysit/file-PR into two skills once descriptions alone triggered correctly. #### ⏱️ [14:15](https://www.youtube.com/watch?v=e1snsuY4lTI&t=855) File-PR skill + good/bad title & description examples - Real bad PR shown (title/summary too vague to reconstruct intent) contrasted with concrete before/after title examples. - "Do not lead with an implementation inventory" rule; model-slug-in-description addition for tracking which model/harness filed what. #### ⏱️ [19:00](https://www.youtube.com/watch?v=e1snsuY4lTI&t=1140) T3 Code repo AGENTS.md rewrite — audit-driven process - Opens the working thread with a prompt asking the agent to review his cross-model, cross-machine history for common mistakes, categorized by model. #### ⏱️ [22:44](https://www.youtube.com/watch?v=e1snsuY4lTI&t=1364) Cross-model failure audit results - Opus 5: aggressive wrong-process killing (worse than any other model observed, small sample explicitly acknowledged). - GPT-5.6/"Soul": ~40% draft-PR rate, unnecessary repo-wide checks, only model making unasked-for global-file edits. - Metrics also tracked: user-data touches, bash error rates, "corrections per 100 messages" per model. #### ⏱️ [24:18](https://www.youtube.com/watch?v=e1snsuY4lTI&t=1458) T3 Code AGENTS.md — glossary and "never compromise" list - Glossary: You / We-us-maintainers / User / Agent / Provider / Client / Environment / Project. - Non-negotiables: open at the core, performance without compromise, remote-ready, multi-surface (web/desktop/mobile). #### ⏱️ [30:24](https://www.youtube.com/watch?v=e1snsuY4lTI&t=1824) "Note from Theo" — simplicity mandate - YAGNI/"measure twice cut once" framing; explicit statement that developer preference can override file defaults. #### ⏱️ [31:17](https://www.youtube.com/watch?v=e1snsuY4lTI&t=1877) Sponsor: Convex - Pitch: single-folder backend representation is easy for agents to write against; team pedigree (ex-Dropbox scaling engineers) cited as reliability signal. #### ⏱️ [32:37](https://www.youtube.com/watch?v=e1snsuY4lTI&t=1957) "Hit every surface" checklist, contracts package, reverse states - Named defect class: change works on tested path, missing elsewhere (settings, command palette, keybindings, other clients, docs). - Contracts package must reflect anything crossing the websocket/HTTP boundary; new states (settle/snooze) must ship their inverse in the same change. #### ⏱️ [35:01](https://www.youtube.com/watch?v=e1snsuY4lTI&t=2101) Vite Plus `vp run dev` quirk - Models kept trying `vp dev`/typing out "Vite Plus"; explicit instruction added after repeated agent mistakes matching Theo's own recurring frustration with the tool's design. #### ⏱️ [36:17](https://www.youtube.com/watch?v=e1snsuY4lTI&t=2177) Dev-server hygiene, PID tracking, test skills, taste rules - Custom home directories to avoid colliding with the running server; PID saved so the agent kills the correct process (direct response to the Opus incident); computer-use test skills (`test T3 app`, `test T3 mobile`) reserved for user-visible front-end changes; taste rules (complexity at adapter boundary, `any` is "the enemy," no continuously repainted GPU-heavy animations); dev-mode security explicitly told not to be over-indexed. #### ⏱️ [39:52](https://www.youtube.com/watch?v=e1snsuY4lTI&t=2392) Live demo — one-line prompts driving full PR workflow - "Do C+D+A. File and babysit." and a bug-report-to-fix prompt both shown producing near-complete, mergeable PRs quickly, attributed to the accumulated instruction tuning. #### ⏱️ [40:01](https://www.youtube.com/watch?v=e1snsuY4lTI&t=2401) Command-center (machine-specific) provisioning skill - Built by having an agent audit an already-configured machine and generalize setup for new ones; includes a self-updating fleet-status HTML dashboard. #### ⏱️ [42:44](https://www.youtube.com/watch?v=e1snsuY4lTI&t=2564) File-upload skill (files.tslop.org) - `requires`-gated on an auth token so the skill is invisible on machines without it; framed as primarily valuable for *communicating* with Theo (screenshots/recordings in PRs), not for the agent's own coding. #### ⏱️ [44:52](https://www.youtube.com/watch?v=e1snsuY4lTI&t=2692) HTML-communication / post-plan skill — live refactor - Splits an overloaded "HTML planning" skill into `post-plan-read` (fetch via shell, never browser) and `html-communication` (produce a readable HTML artifact, explicitly not product HTML); description trimmed to trigger phrasing including a bare "HTML" mention. #### ⏱️ [50:59](https://www.youtube.com/watch?v=e1snsuY4lTI&t=3059) Closing — don't copy the files - Explicit refusal to hand out the repo; comparison to blindly installing someone else's dependency list; call to build the same auditing habit rather than the same file. ## 📚 References - [T3.gg](https://t3.gg) — Theo Browne's site/channel; primary source for T3 Chat/T3 Code - [UploadThing](https://uploadthing.com) — Theo's file-upload product (referenced in transcript as "Uploading Ping," almost certainly an ASR mis-transcription) - [WorkOS](https://soydev.link/workos) — sponsor, spoken shortlink from the transcript - [Convex](https://swade.link/convex) — sponsor, spoken shortlink from the transcript ## 🗣️ Paraphrase - Theo says his recent coding surge is only partly about T3 Code's own features — the bigger driver was deliberately rewriting the markdown files (`AGENTS.md`, `CLAUDE.md`, skills) that steer his agents, which he'd otherwise neglected for roughly two years. - He separates global instruction files (used everywhere) from repo-specific ones (tuned to a single codebase), and argues the global `README.md` is for human/agent orientation while `AGENTS.md` is operational instruction — conflating the two is a mistake he's addressed before. - He deliberately withholds the actual files from viewers: the transferable value is the reasoning and evidence behind each line, not the line itself, and copying it wholesale is like cargo-culting a generic template onto unrelated projects. - The video's central technical argument is that a skill's `description` is always loaded into the model's context regardless of use, so it should function as trigger keywords for when to invoke the skill, not as a description of what the skill does — he demonstrates cutting verbose descriptions down to short "use when..." phrasing, and splitting an overloaded skill into two once each description reliably self-selected. - Several skills (babysit-PR, file-PR) were built directly from named failure patterns he'd observed (undisclosed agent comments, PR bloat from over-addressing minor feedback, vague titles/descriptions), fixed with explicit dos/don'ts and concrete good/bad examples, on the premise that models pattern-match well to shown examples. - For T3 Code's contributor-facing `AGENTS.md`, he didn't guess at content — he had agents mine his own multi-machine, multi-model chat history to quantify failure modes (e.g., Opus 5 killing the wrong process, a GPT model filing an outsized share of draft PRs), then wrote the file to specifically counter what the data showed. - The repo file opens with a shared-vocabulary glossary, briefs the agent on the product so it doesn't waste early tool calls researching, lists things that must never be compromised (openness, performance, remote-readiness, multi-surface support), and includes a short "Note from Theo" invoking YAGNI to keep the agent from over-engineering — with an explicit statement that developer intent overrides the file's defaults. - Operational sections address a recurring "worked on the path I tested, broke everywhere else" defect, a tooling CLI quirk that keeps tripping up agents, dev-server process hygiene tied directly back to the Opus incident, and a "don't over-secure a local-only dev feature" note. - He live-demonstrates the payoff: single-line prompts producing complete, near-mergeable PRs, and live-edits a real skill (splitting HTML-communication from a read-only "post-plan" fetch skill) to show the actual editing workflow, not just the end state. - He closes by explicitly discouraging viewers from copying his skill repo, likening it to installing someone else's entire dependency list, and instead urging them to build the habit of auditing their own agents' failures to write their own instructions. ## 📰 Newsletter - **Skills are trigger phrases, not manuals — worth stealing for The WPOCC's own agent tooling.** Theo Browne (T3.gg) just posted a genuinely useful teardown of how he tunes coding-agent instruction files, and the headline insight travels well past his stack: a skill's `description` field loads into the model's context whether or not the skill fires, so it should read like search keywords ("use when the user asks to babysit a PR"), not like a mini-README. If any of our own automation reads like documentation instead of a trigger, that's worth a pass. - **The best fix he found for bad agent output wasn't a bigger prompt — it was one good and one bad real example.** For anyone iterating on Claude/Codex instructions for WordPress tooling, contributor docs, or release automation, his pattern (show the actual awful PR title next to the one you wanted) is more concrete and reusable than most prompt-engineering advice floating around. - **He also ran an actual audit** — had agents mine his own chat history across models to find measurable, per-model failure rates (one model killing the wrong process, another over-filing draft PRs) before writing a single instruction. Worth borrowing the method even without his specific numbers. - Links: [T3.gg](https://t3.gg) · [UploadThing](https://uploadthing.com) · video: [My AGENTS.md & SKILLS.md Breakdown](https://www.youtube.com/watch?v=e1snsuY4lTI) ## ✅ Action Items #### DevRel - Developer advocacy: Adapt Theo's "audit real failure logs before writing instructions" method into a short workshop/talk format for contributor-facing agent-tooling docs. - Education: Draft a short guide translating "description = trigger keywords" into concrete do/don't examples for skill authors new to Claude Code/Codex skill systems. - Developer experience: Review our own MCP/skill descriptions for documentation-style bloat vs. trigger-keyword focus, per the pattern demonstrated at 12:50. - Developer marketing: Not applicable to this source — no marketing campaign or funnel content discussed. - Community management: Not applicable to this source — no moderation or CoC content discussed. - Internal/external/cross-project: Share the cross-model failure-audit method (mining chat history for per-model failure rates) as a reusable practice across teams running multiple coding-agent harnesses. #### OSPO - Policy & Governance: Consider a lightweight internal standard distinguishing README (human-facing) from AGENTS.md (agent-operational instruction), per the distinction Theo draws at 09:00. - License Compliance: Not applicable to this source — no licensing content discussed. - Security Management: Flag the "agent killed the wrong process" failure mode (22:44) as a concrete case study for tool-permission scoping reviews in any agent-facing sandbox policy. - Software Inventory: Not applicable to this source — no SBOM/inventory content discussed. - Developer Support: Not applicable to this source — no support-tooling content discussed. - Community Engagement: Not applicable to this source — no upstream funding/MoU content discussed. - Strategic Alignment: Not applicable to this source — no OKR/roadmap content discussed. #### Community - Maintainers: The "never compromise" list pattern (open at the core, performance, remote-ready, multi-surface at 24:18) is a reusable template for any project's own non-negotiables section in contributor docs. - Contributors: The glossary-first approach (You/We/User/Agent/Provider/Client/Environment/Project) is a low-cost addition to reduce onboarding ambiguity for both human and agent contributors. - Sponsors: Not applicable to this source — no sponsor-transparency content discussed (the video's own sponsors, WorkOS and Convex, are ad reads, not a governance topic). - Ecosystem: Not applicable to this source — no cross-project incident-drill content discussed. #### WordPress - Core: Consider whether Core's own `AGENTS.md`/contributor guidance would benefit from an audit-driven rewrite rather than an aspirational one. - Core Performance: Not directly applicable — but the "hit every surface" defect class (32:37) generalizes to performance regressions that pass on one code path and regress elsewhere. - Core AI: Directly applicable — the description-as-trigger-keyword and good/bad-example patterns are reusable guidance for any Core AI agent-tooling guidelines. - Core Program Team: Not applicable to this source — no cross-team coordination-ritual content discussed. - Mobile: Not applicable to this source. - Playground: Not applicable to this source. - Community: Not applicable to this source. - Training: The video itself is a usable case study for a "how to write agent instructions from evidence, not vibes" training module. - Marketing: Not applicable to this source. - Support: Not applicable to this source. - Design: Not applicable to this source. - Documentation: Directly applicable — the README-vs-AGENTS.md distinction (09:00) is worth codifying in any WordPress-adjacent documentation style guide covering agent-facing docs. - Photos: Not applicable to this source. - TV: Not applicable to this source. - Polyglots: Not applicable to this source. - Accessibility: Not applicable to this source. - Meta: Not applicable to this source. - CLI: The Vite Plus `vp run dev` complaint (35:01) is a small but real case study in how CLI ergonomics quietly tax every downstream agent interaction — relevant to any WP-CLI ergonomics review. - Hosting: Not applicable to this source. - Tide: Not applicable to this source. - Openverse: Not applicable to this source. - Themes: Not applicable to this source. - Plugins: Not applicable to this source. #### The WPOCC - Programs: Not applicable to this source — no fellowship/microgrant content discussed. - Projects: The audit-driven `AGENTS.md` rewrite process is a candidate pattern for any WPOCC documentation-sprint tooling. - Funding experiments: Not applicable to this source. ### FAIR - Technical independence: Not applicable to this source — no metadata/provenance/signature content discussed. - Policies and covenants: Not applicable to this source. - Productized governance artifacts: The glossary-first, non-negotiables-list pattern (24:18) is a reusable shape for FAIR's own charter/operator-agreement documents, independent of this video's AI-coding-agent framing. ## 🧪 Hypotheses - H1: Repo-scoped `AGENTS.md` files that open with an explicit shared glossary reduce agent misinterpretation of ambiguous instructions, measurable via a drop in mid-task clarifying questions or corrective follow-ups. - H2: Skill descriptions written as short trigger-keyword phrases yield a higher correct-skill-invocation rate than descriptions written as explanatory prose, holding skill body content constant. - H3: Embedding one concrete good/bad example for a previously-flagged failure pattern reduces recurrence of that pattern more than an equivalent-length abstract rule. - H4: Explicit "stop points" in a prompt (e.g., "don't commit yet, I'll tell you when") reduce agent overreach/scope creep compared to open-ended prompts on otherwise identical tasks. - H5: Cross-model failure-pattern audits (mining an agent's own session history) surface differentiated, model-specific failure profiles usable for task-to-model routing decisions. - H6: Splitting one overloaded skill into two narrowly-triggered skills improves correct-skill-selection accuracy compared to a single skill with a broad "when to use" list. ### 📊 Methodology - H1/H3/H4: Controlled prompt-variant testing — run matched task sets against the same model/harness with and without the glossary/example/stop-point addition, log clarifying-question rate, defect recurrence rate, and unrequested-action rate. - H2/H6: Skill-invocation logging across a fixed prompt corpus, A/B testing description phrasing (trigger-keyword vs. prose; single overloaded skill vs. two split skills), scored against a human-labeled "correct skill for this prompt" ground truth. - H5: Structured log mining (as Theo did manually) formalized into a repeatable script — tag each agent action by model, harness, and outcome category (process-kill, draft-PR, unasked-edit, etc.), track rates over a rolling window per model. ### ❓ Questions - Does the "description as trigger keywords" pattern hold up as a skill library grows past a few dozen entries, or does keyword collision between skills start degrading selection accuracy? - How much of the reported productivity gain is really from the instruction-file rewrite versus from T3 Code's own multi-machine parallelism improvements, which Theo also credits in the same breath? - Is the Opus-5-kills-processes finding a model-capability issue or a tool-permission/sandboxing gap that would recur with any sufficiently agentic model given the same tool access? - What's the actual maintenance cost over a year of an audit-driven `AGENTS.md` — does it need re-auditing every time a new model version ships, given the video's own within-video observation that "5.5 and 5.6" behaved differently? - Would a smaller team without Theo's five-machine, multi-model setup get proportionate value from this process, or does the ROI depend on his unusually high agent-usage volume? ### 🔮 Future Research - A standardized taxonomy of coding-agent failure modes (process misuse, scope creep, draft-PR habits, unasked edits, tool misuse) that different teams could tag against consistently, enabling cross-org comparison rather than each team inventing its own categories. - Tooling to auto-mine agent session history for failure patterns (Theo did this manually via prompting) as a reusable, model-agnostic script rather than a one-off audit. - Formal (not anecdotal) evaluation of the "description as trigger keywords" claim — currently supported only by Theo's own before/after experience, not a controlled study. - Investigation into whether "hit every surface" style checklists can be partially automated (e.g., via a lint step that flags a diff touching one client surface but not its siblings) rather than relying on the agent reading and following the checklist every time. ### 💡 Implications - **Practice.** Treat instruction files as living artifacts revised from observed failures, not one-time setup; budget real time (Theo cites ~12-16 hours) for this as legitimate engineering work, not overhead. - **Policy.** Organizations standardizing on coding agents may want an explicit README-vs-AGENTS.md content policy to prevent the conflation Theo flags, plus a documented process for auditing and updating instruction files as models change. - **Security.** The Opus-5 process-killing incident is a concrete argument for scoping agent tool permissions (especially process-management tools) rather than relying on instruction-file text alone to prevent destructive actions — instructions are a mitigation, not a guarantee. - **Education.** The good/bad example pattern and the glossary-first approach are teachable, low-cost techniques worth including in any internal "how to write good AGENTS.md" training material. - **Funding models.** Not directly addressed by this source; no funding-model content to extend meaningfully. ### 🧠 Learning Styles Assessment - **Reading level estimate.** Applying a rough Flesch-Kincaid-style estimate to the transcript's conversational, run-on style: approximately grade 8-9 reading level — informal spoken register, short clauses, frequent asides, occasional profanity (partially bleeped in the transcript), technical jargon (AGENTS.md, YAGNI, contracts package) assumed familiar without definition. #### 👀 Visual learners - Present: heavy screen-recording of actual file diffs, PR titles, and a live skill-editing session — the video is fundamentally show-don't-tell. - Improve: the transcript-only capture (this source) loses all of that; a companion set of annotated screenshots of the before/after AGENTS.md sections would meaningfully help a reader working from notes alone. #### 🔊 Aural learners - Present: the source is native audio/video; tone and emphasis (frustration, enthusiasm) carry real information (e.g., the Vite Plus complaint, the Opus complaint). - Improve: a 2-3 minute audio-only recap of just the "description = trigger keywords" and "hit every surface" sections would serve aural learners who don't need the full 51 minutes. #### 🗣️ Verbal learners - Present: the video uses a small number of recurring analogies (copying a generic code template, installing someone else's package.json) to anchor abstract points. - Improve: a short glossary of the video's own coined terms (e.g., "hit every surface," "match ceremony to the task") would help verbal learners map concept to term faster. #### 🧩 Kinesthetic learners - Present: the live-refactor segment (44:52) is effectively a mini step-by-step lab — a real prompt, a real diff, a real result. - Improve: a downloadable, redacted example AGENTS.md skeleton (not Theo's actual file, which he withholds) that a reader could edit hands-on would extend this further. #### 🧠 Logical learners - Present: the cross-model failure audit (22:44) presents genuine comparative data (rates, counts) rather than pure anecdote. - Improve: a simple table of model × failure-category × observed rate, reconstructed from the spoken numbers, would make the comparative claims much easier to scan than prose. #### 🧑‍🤝‍🧑 Social learners - Present: the video is framed as advice to a community of viewers who also run coding agents; implicit peer comparison ("agents are really good at bad and good examples"). - Improve: no discussion-prompt or Q&A structure is present; a companion discussion thread ("what failure pattern have you seen from your agent?") would suit social learners. #### 🧘‍♀️ Solitary learners - Present: the explicit closing instruction to build your own process rather than copy his is itself a solitary-learner-friendly framing. - Improve: a short self-audit worksheet ("list your last 5 agent frustrations, write one instruction line per one") would operationalize that framing. #### 🌿 Naturalistic learners - Present: minimal — no ecosystem/sustainability framing in the source. - Improve: not a natural fit for this content; no meaningful addition proposed. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: this deep-read note itself uses semantic headings; the original YouTube video's own page provides standard video-player landmarks. - Improve: the transcript captured here uses timestamp-prefixed lines without heading structure in its raw form — the H4 timestamped subheadings added in this note's 🗒️ Notes section are the accessibility improvement. #### Keyboard navigation - Present: standard YouTube player keyboard controls apply (not evaluated directly here). - Improve: not assessable from transcript alone. #### Contrast and readability - Present: not assessable from transcript alone (visual on-screen text/diffs weren't captured). - Improve: screen-recorded code/diff segments would benefit from a stated minimum on-screen font size given typical remote-coding demo tendencies toward small terminal text. #### Text resizing and reflow - Present: not applicable to video content directly. - Improve: not applicable. #### Media and captions - Present: auto-generated captions/transcript exist (the source of this analysis) — WCAG 1.2.2 baseline is met. - Improve: auto-captions contain clear ASR errors (e.g., "open sauce" for "open source," "Uploading Ping" for "UploadThing," "soul" for a model nickname likely "Sol" or similar) — human-reviewed captions would materially improve accuracy for a highly technical, jargon-dense video. #### Forms and interactions - Not applicable to this source — no forms or interactive elements in a YouTube video transcript. #### Standards reference - Primary gap maps to WCAG 2.2 AA 1.2.2 (Captions) — met at a baseline (auto-captions exist) but with accuracy issues that a human pass would address; no other criteria are meaningfully assessable from a transcript-only capture. ### 🌍 DEIB Assessment #### Cultural breadth - Present: no multi-region or multilingual framing; content is narrowly scoped to one individual's personal workflow and tooling. - Improve: not a natural fit for this content type (a personal workflow walkthrough), so no meaningful expansion proposed. #### Inclusive language - Present: mostly gender-neutral technical language; jargon (AGENTS.md, YAGNI, "harness," "provider") used without definition, assuming an already-technical audience. - Improve: a brief jargon glossary at video start would lower the barrier for newer developers. #### Neurodiversity support - Present: content is chunked by feature/skill in the video's own structure, which aids predictability. - Improve: the spoken delivery includes frequent tangents and self-interruptions (e.g., mid-sentence corrections, "I don't have it here, but I have it in my global... I do"); a written companion outline would help viewers who find that delivery style hard to track. #### Representation - Present: single narrator; other people are referenced by name (Julius, Igor) as collaborators without elaboration. - Improve: not assessable further from a solo-narrator transcript. #### Psychological safety - Present: casual, unfiltered tone including profanity (partially self-censored/bleeped) and pointed criticism of specific tools and, briefly, a named open-source maintainer (Evan You, re: Vite's CLI design) — see Fallacies below for the ad hominem risk this creates. - Improve: routing the Vite CLI critique to the actual design decision (without the personal framing) would reduce psychological-safety risk for viewers who know or work with the maintainer criticized. ### ✅ Logical Validity #### Strong reasoning - **Inductive, evidence-based** (22:44): rather than asserting model quality differences from vibes, Theo has agents mine his own chat history for counted failure rates per model — a genuine (if informal) empirical method, strong because it's falsifiable against his own logs and he reports it even when unflattering to a model he favors (Fable). - **Causal, mechanism-linked** (36:17): the PID-tracking fix is explicitly tied back to the specific incident (Opus killing the wrong process) that motivated it — a clear cause-then-fix chain rather than a generic "best practice" claim. #### Fallacies - **Hasty generalization** (20:44-21:14): Theo explicitly notes he "only used [Opus] for 2 days" yet still draws a firm comparative ranking ("significantly more times to kill processes than Fable had in all the time I used it") — he flags the small sample himself, which is honest, but the conclusion is still presented with more confidence than a 2-day sample supports. **Fix:** caveat the ranking as preliminary pending a larger sample, or report absolute counts alongside the comparison so readers can judge sample adequacy themselves. - **Ad hominem (mild)** (35:01-35:38): the Vite Plus `vp run dev` critique shifts from the design decision itself ("`vp dev` does its own thing, `vp run dev` does what you want") to a personal jab at the maintainer ("our friend Evan You could not get over his [redacted]... He's wrong"). The design critique is substantive and worth keeping; the personal framing doesn't strengthen the argument and adds attack-not-argument content. **Fix:** keep the technical complaint (inconsistent CLI verb semantics), drop the personal characterization. #### Tone of voice - Casual, high-energy, self-deprecating in places ("I hope you understand writing markdowns expensive"), enthusiastic about tooling wins, visibly frustrated at specific failure incidents (Opus process-killing, Vite CLI ergonomics) — consistent with a personal-channel dev-vlog register rather than a formal technical writeup. ### 🛡️ DARVO Analysis - Not applicable to this source — DARVO (Deny, Attack, Reverse Victim/Offender) describes a response pattern to an accusation of wrongdoing. This video contains no accusation-and-response dynamic; the closest analog (the Vite Plus/Evan You critique) is a one-directional grievance about a tool design choice, not a defensive cycle, and is already captured above as a mild ad hominem fallacy rather than a DARVO pattern. ## 🎯 Conclusion - **Bottom line.** The video's real claim isn't "here's a good AGENTS.md" — it's that instruction files should be built the same way you'd build any other system with a real failure rate: observe actual failures (ideally with logs/numbers, not vibes), write instructions that specifically counter what you observed, embed concrete good/bad examples rather than abstract rules, and treat the description of any reusable skill as a trigger phrase rather than a manual. Theo's specific files are deliberately withheld because, per his own argument, the artifact isn't the point. - **Practical next steps for readers.** (1) Pull a sample of your own agent's recent sessions and categorize the failures you actually see, the way Theo's cross-model audit did, before writing new instructions. (2) Audit existing skill/tool descriptions for documentation-style bloat and rewrite the ones that should instead be short trigger phrases. (3) For any recurring bad output pattern, add one real good/bad example rather than a longer abstract rule. (4) Separate human-facing docs (README) from agent-operational docs (AGENTS.md) if they're currently combined. ## 🔄 Refactor Appendix — My AGENTS.md & SKILLS.md Breakdown (Don't copy them) > Density: 5 Literature atoms (H3), 2 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent — extended here given source density (51-minute > substantive walkthrough with many distinct, reusable claims). > > Konik claim-header rules: present tense, declarative, ≤10 words when > possible, searchable, unique, mirrors annotation focus if present. > > Atomicity: one declarative sentence per atom. "and"/"also" → split. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Atoms (H3) #### [H1] Instruction value is the reasoning, not the text > [!quote] > the value of this isn't the exact things I instructed. It is the way I thought of it. **Context & use**: - ~09:00-09:20, explaining why he won't publish his actual `AGENTS.md`. - Directly relevant to Courtney's own skill-authoring practice (`mattpocock-skills:writing-for-agents`, `superpowers:writing-skills`) — argues against template-copying in favor of documenting the *why* behind each instruction line. **Tags**: #xref #articleseed  #### [H2] Skill descriptions are always-loaded trigger keywords > [!quote] > you should treat the description less like an elaborate explanation of all the things the skill does **Context & use**: - ~12:50-13:07, core technical claim of the video. - Directly testable against Courtney's own `~/.claude/skills/*/SKILL.md` frontmatter descriptions — worth an audit pass for documentation-style bloat. **Tags**: #xref #addendum  #### [H3] Open PR descriptions with the problem, not an inventory > [!quote] > Open the description with a simple explanation of the problem based on the user's original prompt, then briefly explain the solution. **Context & use**: - ~15:54-16:07, part of the file-PR skill's instructions, paired with a concrete bad/good example. - Relevant cross-reference: `anti-slop-git-writing` skill's own guidance on commit/PR message style. **Tags**: #xref  #### [H4] A small sample still produced a firm model-safety finding > [!quote] > I noticed Opus 5 was aggressively killing the wrong process, often killing the T3 code instance that it was running in. **Context & use**: - ~22:44-22:57, part of the cross-model failure audit; Theo separately acknowledges only 2 days of Opus use. - Cross-reference for `security-review` and tool-permission-scoping practice — an instructions-only fix (PID tracking) followed a real incident rather than preventing it proactively. **Tags**: #xref  #### [H5] Named a defect class: works on the tested path, missing elsewhere > [!quote] > The most common defect in this repo is a change that works on the path you tested and is missing everywhere else. **Context & use**: - ~32:59-33:05, opens the "hit every surface" checklist section. - Generalizes past T3 Code to any multi-surface (web/mobile/CLI) project's own review checklist. **Tags**: #xref #addendum  ### 🧠 Permanent Candidates (H4) #### [P1] A skill description functions as a search trigger, not a manual **Claim** (one sentence, Courtney's voice): A skill's description field should read as searchable trigger phrases that tell the model when to invoke the skill, because that field loads into context whether or not the skill fires, so any explanatory content in it is wasted tokens on every unrelated turn. **Evidence pointer**: [[#H2]] **Scope & conditions**: Holds for any agent harness where skill/tool descriptions are always-injected (Claude Code, similar MCP/skill systems); breaks down if a harness only loads descriptions on-demand after some other selection step. **Links** (≥1 with annotation): - [[Konik claim-header rules]] — because applies-in the same "short, searchable, present-tense" discipline this pipeline already uses for Literature atom headers.  #### [P2] Instruction files should be revised from counted failures, not intuition **Claim** (one sentence, Courtney's voice): Agent instruction files improve fastest when each new line is added in direct response to a categorized, counted failure observed in real session logs rather than a generic best practice. **Evidence pointer**: [[#H4]] **Scope & conditions**: Holds when session logs/history are available to mine; requires enough usage volume to distinguish a real pattern from a one-off (see the small-sample fallacy noted in Logical Validity). **Links** (≥1 with annotation): - [[H1 — instruction value is the reasoning]] — because extends the same "process over artifact" argument to the source of the instructions, not just their preservation.  ### ✏️ Fleeting Queue - [F1] The transcript's "Uploading Ping" is almost certainly an ASR mis-hearing of "UploadThing," Theo's actual product — worth confirming before citing this note elsewhere. #xref - [F2] Cross-reference candidate: does Claude Code's own skill `description:` frontmatter field get the same "always loaded" treatment described here? If so, this video is direct external validation for `superpowers:writing-skills` and `mattpocock-skills:writing-for-agents` guidance. #addendum ### → Things 3 (max 2 actions) - [ ] Audit `~/.claude/skills/*/SKILL.md` descriptions against the "trigger keywords, not documentation" test from this video — flag any that read like a manual — context #things  📄 **Full text:** [[Full Document Contents/Articles/My AGENTS.md & SKILLS.md Breakdown.md|My AGENTS.md & SKILLS.md Breakdown by Theo Browne (T3.gg)]] ## Highlights - Where can I find the agents MD file? I want to copy some of the instructions. You can't. I very intentionally did not publish this file. Not because I'm evil and I want you to have to carefully watch the video and copy every single word by hand. The real reason is the value of this isn't the exact things I instructed. It is the way I thought of it. It is the reasons I added the things I added and the path I took there. I will describe how I came to these conclusions and why I added these things right after. I really want you guys to take the opportunity to learn from my process here, not to copy paste the specific things in my global files. ([View Highlight](https://read.readwise.io/read/01m080wbrdfpqzxj0rxggrhtxv)) - Note: Instruction-file value is the reasoning process, not the literal text — argument against template-copying. - Tags: articleseed, xref, atom/literature/h1 - This is a thing that most people get wrong and agents get even more wrong. Your description should not describe necessarily what the skill does because the description is always inserted even if the skill is not being used. The point of the description is to let the model know when it should pull in the skill. So, you should treat the description less like an elaborate explanation of all the things the skill does. Hell, I've seen skills where the description gives you everything that you need, and you don't even need to use the skill because the description has all the details. The description should have the magic keywords to tell the model when to pull the thing in. So here I could probably delete this monitor a pull request through review in CI entirely and have it just be used when the user asks to monitor, watch, or babysit a PR. The point of this skill is to be pulled in and give the model the context when it needs these things. I know it's unintuitive because it's called a description, but you really should think of the description of a skill as the trigger keywords rather than as an actual description. As such, you can guess how my file PR skill is formatted. File a concise pull request. ([View Highlight](https://read.readwise.io/read/01m080wf0wdmgjavq4fzyscgrc)) - Note: Core technical claim: a skill's description field is always loaded into context, so it should read as trigger keywords, not documentation. - Tags: addendum, xref, atom/literature/h2 - Another important chunk that I have here, this is probably the one that's changed my life the most, as silly as it is. Open the description with a simple explanation of the problem based on the user's original prompt. Then briefly explain the solution. Do not lead with an implementation inventory. So I gave a bad example here. Removed implicit workspace carryover from every new thread entry point. New threads inherit only the project from context branch, work, yada yada. Just nonsense. No one's going to read this. Good example. My new work tree default was ignored when starting new threads on existing work trees. Super unintuitive. Now your preferences always apply. So much better. I also specifically told it to stop opening draft PRs because Codex loves opening draft PRs that don't get reviews. I told it to open a real PR rather than a draft. So review bots run. ([View Highlight](https://read.readwise.io/read/01m080whrbsmryrxg52r65ebcj)) - Note: PR descriptions should open with the problem in plain language, not an implementation inventory — paired with a concrete bad/good example. - Tags: xref, atom/literature/h3 - This was fun because not only did it catch specific failures that I cared about, it also categorized them by how often they happened with each model and harness. I noticed Opus 5 was aggressively killing the wrong process. ([View Highlight](https://read.readwise.io/read/01m080wm9m9ay6wtpvq4ab8ks4)) - Note: Cross-model failure audit finding; Theo separately acknowledges only 2 days of Opus use behind this comparative claim. - Tags: fallacy/hasty-generalization, xref, atom/literature/h4 - Sorry about that. I hope you understand. Writing markdown is expensive and writing it all by hand is time-consuming. A bit of this was whisper flow, but the majority of this was handcoded and written. So yeah, this next piece is another one of those huge lifesaver ones because I was running into a lot of problems where I would make a change in T3 code and it would only apply to one of the surfaces. For example, it would only be changed on the desktop app and not the website or mobile. I wanted to stop doing that and also to make sure the docs kept up to date as well. So I said as much, hit every surface. The most common defect in this repo is a change that works on the path you tested and is missing everywhere else. Before calling frontend work done, walk this list and say which entries apply. Make sure all the entry points are addressed. Things like settings page, command palette, and key bindings. So if you add a feature in the chat view, it should be accessible in those places. You have clients, because we need to make sure things work in all the different clients. The web version, the desktop version, as well as the mobile apps. Shared logic lives in the shared package client runtime section. And then the providers, each of our providers have their own adapters. ([View Highlight](https://read.readwise.io/read/01m080wq424w3t5tv0m27w3bc4)) - Note: Named defect class: a change tested on one surface silently missing from others — generalizes past T3 Code to any multi-surface project. - Tags: atom/literature/h5, addendum, xref