# My AGENTS.md & SKILLS.md Breakdown > [!question] Lingering Questions > - Does "description as trigger keywords" 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 Theo's reported productivity gain is really the instruction-file rewrite versus T3 Code's own multi-machine parallelism improvements, credited in the same breath? > - Would a smaller team without Theo's five-machine, multi-model usage volume see proportionate ROI from an audit-driven `AGENTS.md` process? > [!tip] Article Ideas > - "Your skill description is a search query, not a README" — audit piece walking `~/.claude/skills/*/SKILL.md` descriptions against the trigger-keyword test, showing before/after trims. > [!link] Cross Reference > - [[3. Resources/Permanent Notes/Context Budget Is Spent By Default Not By Exception]] — same always-loaded-cost mechanism (skill descriptions inject into context whether used or not), argued from the opposite side: that note says minimize what's always-on, this source's core claim is about what the always-on field should contain > - [[3. Resources/Permanent Notes/Write Agent-Facing Docs Assuming the Agent Wont Fetch the Reference]] — related agent-facing-docs design discipline, different mechanism (inline critical content vs. trigger-only description) > - [[3. Resources/Permanent Notes/Intent Written on the Outside Compounds While Re-Derived Intent Is Debt]] — same "process over artifact" framing Theo uses to explain why he won't publish his actual files > [!quote] Vocabulary > - **AGENTS.md** — repo-specific operational instruction file for how an agent should change code, as distinct from a human-facing README > - **hit every surface** — Theo's named defect class: a change that works on the tested path but is silently missing from other clients/entry points ## Bib capsule Theo Browne (T3.gg), "My AGENTS.md & SKILLS.md Breakdown (Don't copy them)," YouTube, https://www.youtube.com/watch?v=e1snsuY4lTI ## Author's thesis (Q1+Q2) Theo argues that agent instruction files (`AGENTS.md`, `CLAUDE.md`) and skill libraries should be built the same way any system with a measurable failure rate gets built: audit real failure logs across models, write instructions that specifically counter what was observed, embed concrete good/bad examples instead of abstract rules, and treat a skill's `description` field as a trigger phrase rather than documentation. He explicitly refuses to publish his actual files, arguing the transferable value is the reasoning process behind each line, not the line itself — copying the artifact without the process is cargo-culting a generic template onto an unrelated project. ## Key arguments (≤3) 1. A skill's `description` field is always injected into context regardless of whether the skill fires, so it should contain search-trigger keywords for when to invoke the skill, not an explanation of what it does. 2. Instruction files improve fastest when new lines are added in direct response to categorized, counted failures mined from real multi-model session logs, not from guessed best practices. 3. Concrete before/after good/bad examples (a real bad PR title next to a rewritten good one) teach an agent a pattern more reliably than an abstract rule stating the same preference. ## Claim atoms ### Instruction value is the reasoning, not the text > [!quote] ID:rw_atom1 > the value of this isn't the exact things I instructed. It is the way I thought of it. Where/why: ~09:00, explaining why he withholds his actual `AGENTS.md` — copying the artifact without the reasoning is cargo-culting. ### Skill descriptions are always-loaded trigger keywords > [!quote] ID:rw_atom2 > you should treat the description less like an elaborate explanation of all the things the skill does Where/why: ~12:50, the video's central technical claim — the field is injected on every turn whether the skill is used or not. ### Open PR descriptions with the problem, not an inventory > [!quote] ID:rw_atom3 > Open the description with a simple explanation of the problem based on the user's original prompt, then briefly explain the solution. Where/why: ~15:54, part of the file-PR skill, paired with a real bad/good title example. ### A small sample still produced a firm model-safety finding > [!quote] ID:rw_atom4 > I noticed Opus 5 was aggressively killing the wrong process, often killing the T3 code instance that it was running in. Where/why: ~22:44, cross-model failure audit; Theo separately acknowledges only 2 days of Opus use behind the comparative claim — a hasty-generalization risk he flags himself. ### Named a defect class: works on the tested path, missing elsewhere > [!quote] ID:rw_atom5 > The most common defect in this repo is a change that works on the path you tested and is missing everywhere else. Where/why: ~32:59, opens the "hit every surface" checklist — generalizes past T3 Code to any multi-surface (web/desktop/mobile) project's review checklist. ## Permanent candidates - **New**: A skill description functions as a search trigger, not a manual — promoted below as [[3. Resources/Permanent Notes/Skill Descriptions Are Trigger Keywords Not Documentation]] - Instruction files should be revised from counted failures, not intuition — not promoting a standalone note: the "externalize decisions so they compound" half is already covered by [[3. Resources/Permanent Notes/Intent Written on the Outside Compounds While Re-Derived Intent Is Debt]], and the "evidence from real logs, not vibes" specificity is thin enough on its own to live as claim atom `rw_atom4` above rather than a second permanent note. ## Processing checklist - [x] Checked for existing Literature Note — none found - [x] Checked for existing Permanent Notes covering this source's claims — found adjacent-but-distinct notes on always-loaded context cost, agent-facing doc design, and externalized intent; none capture the "description as search trigger" claim specifically, so it's promoted - [x] Connected into [[3. Resources/MOCs/AI & the Future of Knowledge Work MOC]] ## Links - [[3. Resources/MOCs/AI & the Future of Knowledge Work MOC]] — situates this alongside the vault's existing thread on how agent capability and harness design change instruction-writing practice