--- title: Agents.md vs Skills: markdown minimalism has a new fight description: A debate has broken out over whether AI coding agents need structured 'skills' folders or just a single agents.md file. Developer yacineMTB argues... canonical: https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Agents.md vs Skills: markdown minimalism has a new fight | daily.dev og:description: A debate has broken out over whether AI coding agents need structured 'skills' folders or just a single agents.md file. Developer yacineMTB argues... og:url: https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd og:image: https://api.daily.dev/og/posts/s0hWifpfd.png og:image:alt: Agents.md vs Skills: markdown minimalism has a new fight 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. # Agents.md vs Skills: markdown minimalism has a new fight **[Trends](https://daily.dev/sources/trends)** · 2 min read · 1 upvotes · 0 comments ## Summary A debate has broken out over whether AI coding agents need structured 'skills' folders or just a single agents.md file. Developer yacineMTB argues skills.md-style folders are unnecessary bloat and everything should live in one agents.md. Counter-arguments frame Agent Skills as a distinct artifact combining plain-English policy with executable steps, letting product and engineering collaborate on the same diff. Commentator hwchase17 suggests both sides are arguing over less difference than it appears. ## Content There's a standards war happening in agent config files, and it's really just about who gets to own the markdown. The flashpoint: Shopify's Tobi Lütke says he's considering banning Claude Code at the company until Anthropic starts respecting AGENTS.md and the emerging `.agents/skills` convention instead of forcing everyone onto CLAUDE.md. His complaint is specific: "Insisting on only reading CLAUDE.md sometimes leads to split brain problems when different team members use different tools. Just unnecessary." That's a company threatening to pull a tool over a file naming convention, which tells you how seriously the AGENTS.md camp is taking this. yacineMTB piled on from another angle, dismissing Anthropic's Skills format outright: "don't use skills.md or SKILLS or whatever by the way. it's bloat, just put everything in an agents.md." Meanwhile Harrison Chase (of LangChain) is nodding along, pointing out that the whole fight is almost absurd on its face because "agents.md and skills are just markdown files/directories." Low stakes, high drama. The workaround culture is already here. Ian Nuttall published a full shell script and launchd daemon that watches your filesystem and auto-symlinks CLAUDE.md to AGENTS.md the moment a new AGENTS.md appears, so you never have to maintain two files by hand. That's a genuinely elaborate hack for what amounts to Anthropic not reading a competitor's spec. Underneath the naming fight, there's real substance about what should actually go in these files. Real Python's tutorial shows the stakes concretely: run a coding agent on a FastAPI project with no AGENTS.md and you get a sloppy ID scheme, no validation, inconsistent errors. Add a tight AGENTS.md covering conventions, tooling, and quality gates, and the same prompt produces clean, tested code. The lesson from most practitioners, including one developer's personal agent.md writeup, is that concise beats comprehensive. That concision point has teeth. A research thread being passed around (via omarsar0) found that Claude Code's context compaction shreds safety rules buried in long CLAUDE.md files: 53% survive one compaction round, only 10% survive five. If your giant CLAUDE.md references five other standards docs, like the bloated setup one developer described inheriting from a new team, you're not being thorough, you're setting an expiration timer on your own rules. ## Questions this post answers ### What is the difference between agents.md and Agent Skills for AI coding agents? Agents.md is a single markdown file acting as one source of truth for agent instructions, while Agent Skills use a folder structure mixing plain-English policy with executable steps that call real APIs. Skills proponents argue this lets product and engineering collaborate on the same artifact, while critics like yacineMTB call skills folders unnecessary bloat compared to a single agents.md file. _Developers weighing agent configuration approaches can follow this ongoing debate on daily.dev._ --- Tags: [#ai-agents](https://daily.dev/tags/ai-agents), [#prompt-engineering](https://daily.dev/tags/prompt-engineering) [View this post on daily.dev](https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd) ```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":"Agents.md vs Skills: markdown minimalism has a new fight","url":"https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd"},"datePublished":"2026-08-19T17:22:35.923Z","dateModified":"2026-08-26T01:44:28.824Z","description":"A debate has broken out over whether AI coding agents need structured 'skills' folders or just a single agents.md file. Developer yacineMTB argues...","isAccessibleForFree":true,"articleSection":"Trends","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":"Trends","logo":"https://media.daily.dev/image/upload/s--ZfSp3asX--/f_auto,q_auto/v1780996004/logos/trends?_a=BAMAMiWQ0","url":"https://daily.dev/sources/trends"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"ai-agents,prompt-engineering","timeRequired":"PT2M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Trends","item":"https://daily.dev/sources/trends"},{"@type":"ListItem","position":3,"name":"Agents.md vs Skills: markdown minimalism has a new fight"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/agents-md-vs-skills-markdown-minimalism-has-a-new-fight-s0hwifpfd#faq","mainEntity":[{"@type":"Question","name":"What is the difference between agents.md and Agent Skills for AI coding agents?","acceptedAnswer":{"@type":"Answer","text":"Agents.md is a single markdown file acting as one source of truth for agent instructions, while Agent Skills use a folder structure mixing plain-English policy with executable steps that call real APIs. Skills proponents argue this lets product and engineering collaborate on the same artifact, while critics like yacineMTB call skills folders unnecessary bloat compared to a single agents.md file. Developers weighing agent configuration approaches can follow this ongoing debate on daily.dev."}}]} ```