--- title: I made Claude smarter by writing it a letter | daily.dev description: A developer shares how spending 12+ hours rewriting their global AGENTS.md and CLAUDE.md files dramatically improved their AI coding agent workflows. Key... canonical: https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0 twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: I made Claude smarter by writing it a letter | daily.dev og:description: A developer shares how spending 12+ hours rewriting their global AGENTS.md and CLAUDE.md files dramatically improved their AI coding agent workflows. Key... og:url: https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0 og:image: https://api.daily.dev/og/posts/i1EDEOqE0.png og:image:alt: I made Claude smarter by writing it a letter og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # I made Claude smarter by writing it a letter **[Theo - t3․gg](https://daily.dev/sources/t3dotgg)** · 51 min read · 2 upvotes · 0 comments ## Summary A developer shares how spending 12+ hours rewriting their global AGENTS.md and CLAUDE.md files dramatically improved their AI coding agent workflows. Key insights include: writing agent instructions in a conversational, first-person tone for better tone-matching; using skill descriptions as trigger keywords rather than explanations; auditing agent conversation histories to identify failure patterns by model (Opus 5 was worst for tool misuse, Soul filed draft PRs 40% of the time); separating skills like 'file PR' and 'babysit PR' for precision; adding a glossary so agents communicate using project-specific terminology; and building custom skills for file uploads and HTML planning artifacts. The core thesis is that these files should optimize agent communication with humans, not just technical code quality. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How should I write the description field in a Claude Code skill so it triggers correctly? Write the description as trigger keywords rather than an explanation of what the skill does, since the description is always inserted into context even when the skill isn't used. Phrase it like 'use when the user asks to monitor, watch, or babysit a PR' so the model knows exactly when to pull the skill in, instead of describing its internal logic. _Developers tuning agent skills compare notes on prompt patterns like this through daily.dev._ ### What is the difference between an agents.md file and a README for AI coding agents? A README gives context about a project for humans and agents deciding whether to use the code, while agents.md and CLAUDE.md files instruct the agent on how to make changes and what to know before doing so. Agents.md should be written for the agent's interaction with the developer, not as project documentation, and should include a glossary of team-specific terms. _Teams refining how they instruct coding agents track approaches like this on daily.dev._ ### Why does Opus 5 sometimes kill the wrong process when working as a coding agent? Opus 5 was found to be aggressively and mistakenly killing running processes, including the coding tool instance it was operating in itself, more often than other models like GPT-5.6-Sonnet or Codex during real usage audits. This tool-misuse behavior was significant enough to prompt an explicit instruction added to agent configuration files warning against killing dev servers or damaging the running instance. _Anyone weighing model reliability for agentic coding tasks follows real-world reports like this on daily.dev._ ## Similar posts on daily.dev - [How to Make Claude Code Improve from its Own Mistakes](https://daily.dev/posts/how-to-make-claude-code-improve-from-its-own-mistakes-0k82t0t43) · Towards Data Science · 3 upvotes · 0 comments - [10 tips to improve your coding agent game](https://daily.dev/posts/10-tips-to-improve-your-coding-agent-game-r2zthx2x0) · Pulumi · 3 upvotes · 0 comments - [How I use AI agents to write code](https://daily.dev/posts/how-i-use-ai-agents-to-write-code-onvlmqy00) · Read the Tea Leaves · 99 upvotes · 3 comments --- Tags: [#ai-coding](https://daily.dev/tags/ai-coding), [#claude](https://daily.dev/tags/claude), [#prompt-engineering](https://daily.dev/tags/prompt-engineering) [View this post on daily.dev](https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"I made Claude smarter by writing it a letter","url":"https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0"},"datePublished":"2026-08-11T07:02:21.125Z","dateModified":"2026-09-13T20:33:42.475Z","description":"A developer shares how spending 12+ hours rewriting their global AGENTS.md and CLAUDE.md files dramatically improved their AI coding agent workflows. Key...","image":"https://i.ytimg.com/vi/e1snsuY4lTI/sddefault.jpg","thumbnailUrl":"https://i.ytimg.com/vi/e1snsuY4lTI/sddefault.jpg","isAccessibleForFree":true,"articleSection":"Theo - t3․gg","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Theo - t3․gg","logo":"https://media.daily.dev/image/upload/s--UmX7IyU3--/f_auto/v1704628081/logos/t3dotgg.jpg","url":"https://daily.dev/sources/t3dotgg"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":2},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"ai-coding,claude,prompt-engineering","timeRequired":"PT51M","video":{"@type":"VideoObject","name":"I made Claude smarter by writing it a letter","description":"A developer shares how spending 12+ hours rewriting their global AGENTS.md and CLAUDE.md files dramatically improved their AI coding agent workflows. Key...","thumbnailUrl":"https://i.ytimg.com/vi/e1snsuY4lTI/sddefault.jpg","uploadDate":"2026-08-11T07:02:21.125Z","duration":"PT51M","url":"https://api.daily.dev/r/i1EDEOqE0","embedUrl":"https://www.youtube.com/embed/e1snsuY4lTI"}} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Theo - t3․gg","item":"https://daily.dev/sources/t3dotgg"},{"@type":"ListItem","position":3,"name":"I made Claude smarter by writing it a letter"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/i-made-claude-smarter-by-writing-it-a-letter-i1edeoqe0#faq","mainEntity":[{"@type":"Question","name":"How should I write the description field in a Claude Code skill so it triggers correctly?","acceptedAnswer":{"@type":"Answer","text":"Write the description as trigger keywords rather than an explanation of what the skill does, since the description is always inserted into context even when the skill isn't used. Phrase it like 'use when the user asks to monitor, watch, or babysit a PR' so the model knows exactly when to pull the skill in, instead of describing its internal logic. Developers tuning agent skills compare notes on prompt patterns like this through daily.dev."}},{"@type":"Question","name":"What is the difference between an agents.md file and a README for AI coding agents?","acceptedAnswer":{"@type":"Answer","text":"A README gives context about a project for humans and agents deciding whether to use the code, while agents.md and CLAUDE.md files instruct the agent on how to make changes and what to know before doing so. Agents.md should be written for the agent's interaction with the developer, not as project documentation, and should include a glossary of team-specific terms. Teams refining how they instruct coding agents track approaches like this on daily.dev."}},{"@type":"Question","name":"Why does Opus 5 sometimes kill the wrong process when working as a coding agent?","acceptedAnswer":{"@type":"Answer","text":"Opus 5 was found to be aggressively and mistakenly killing running processes, including the coding tool instance it was operating in itself, more often than other models like GPT-5.6-Sonnet or Codex during real usage audits. This tool-misuse behavior was significant enough to prompt an explicit instruction added to agent configuration files warning against killing dev servers or damaging the running instance. Anyone weighing model reliability for agentic coding tasks follows real-world reports like this on daily.dev."}}]} ```