{"slug": "claude-code-s-17-official-skills-the-rule-vs-the-practice", "title": "Claude Code's 17 Official Skills: the Rule vs the Practice", "summary": "Anthropic's official Claude Code skills reveal a gap between documented rules and actual practice. The developer analyzed all 17 official skills and found that the 500-line limit for SKILL.md is a guideline, not a law—the docx skill is 590 lines. Descriptions must be 'pushy' to avoid under-triggering, and most skills are a single file rather than split into subfolders.", "body_md": "Anthropic's docs are clear: a SKILL.md should be under 500 lines. Their own `docx`\n\nskill is 590. I read all 17 of Anthropic's official skills, frontmatter by frontmatter, while building my own marketplace alongside. Every time, the same gap: the docs say one thing, the corpus does another. And the corpus is the one that's right.\n\nHere's what actually comes out when you read the code instead of the docs.\n\nA skill is useless if it doesn't trigger at the right moment. And what decides triggering isn't the body of the SKILL.md, it's its `description`\n\nin the frontmatter. Claude reads the list of available skills (just name + description) and picks. So all of the \"when to use it\" must live in the description, not the body.\n\nThe counter-intuitive part, which Anthropic repeats in its own skill-creator: **Claude under-triggers skills** far more than it over-triggers them. It only consults a skill for a task it can't handle trivially. \"Read this PDF\" will never fire the PDF skill, even with a perfect description. Hence an explicit instruction: write descriptions that are a little *pushy*.\n\nYou see it in the code: the `xlsx`\n\nskill says \"Use this skill **any time** a spreadsheet file is the primary input or output\", `pptx`\n\nsays \"any time a .pptx is involved **in any way**\". No shyness. You push triggering, you don't hold it back.\n\n\"Keep the SKILL.md under 500 lines\" is one of the most quoted rules. In practice, `docx`\n\nis 590 lines, and the docs themselves add \"feel free to go longer if needed\". The others range from 32 to 404. The truth: 500 is a target, not a law.\n\nThe real principle behind it isn't length, it's the context budget. The SKILL.md body loads on every trigger. If it's big because it holds the essentials, fine, go over. If it's big because it drags along detail that could live elsewhere, that's the fault. Size alone isn't the sin.\n\nThe central skill pattern is staged loading: metadata (name + description) always in context, the body loaded on trigger, and resources (`scripts/`\n\n, `references/`\n\n) only on demand. A script can even execute without being loaded into context.\n\nExcept that in the corpus, **11 skills out of 17 are a single SKILL.md, with no subfolder at all**. Splitting isn't the norm, it's the exception you reach for when the domain warrants it. And when you do split, it's mostly `scripts/`\n\n: `pdf`\n\n, `docx`\n\n, `xlsx`\n\n, `pptx`\n\nare first and foremost script boxes for deterministic operations. The `references/`\n\n(docs loaded on demand) appear on only two skills. The lesson: pull the deterministic stuff into executable code long before you pull prose into a side file.\n\nWriting my own skills, I systematically added a \"NOT for X\" clause to the description, to avoid false triggers. Reading the official ones, surprise: they almost never do it. Their descriptions list inclusions (\"this includes…\"), not exclusions.\n\nThe reason fits in one word: their domains don't overlap. The PDF skill and the Excel skill can't be confused, so no exclusion is needed, and they'd rather maximize triggering. My case is different: my skills touch each other (reviewing a diff, shipping a feature, wrapping up a branch are adjacent). The \"NOT for\" lets me disambiguate between my own skills. So it isn't a universal rule, it's a response to overlap. If your skills don't compete, don't add it: you'd only reduce your triggering, the worst flaw of all.\n\nThe most instructive part of the official skill-creator is that they don't guess a good description, they measure it. The protocol, unrolled:\n\nIt's an eval pipeline, not a finger in the air. Most people write a description by feel and move on. Anthropic treats it as the product.\n\nThe gap, row by row, across the 17 official skills:\n\nThe common assumption\n\nWhat the official corpus does\n\nA SKILL.md is under 500 lines\n\n`docx`\n\nis 590, and the docs add \"go longer if needed\"\n\nThe description just says when to use the skill\n\nIt must be *pushy*: the real risk is under-triggering\n\nYou split into `references/`\n\nand `scripts/`\n\n(progressive disclosure)\n\n11 of 17 skills are a single file; when you split, mostly `scripts/`\n\nYou restrict the description (\"NOT for\") to avoid false triggers\n\nAlmost never written: distinct domains, they maximize triggering\n\nA good description is written by feel\n\nIt's measured: 20 queries, each run 3 times, a 5-iteration loop, scored on a held-out test set\n\nThe real lesson isn't in the list of rules, it's in the gap. The docs give clean heuristics; the corpus shows how competent people bend them when the ground demands it. Reading the 17 skills teaches more than reading the doc page, because you see the real trade-offs: going past 500 lines when the content deserves it, skipping the split two-thirds of the time, pushing triggering rather than restricting it.\n\nIf you keep one thing: the risk isn't that your skill triggers too much, it's that it doesn't trigger at all. Write the description to be found.\n\n**🧩 My skills, installable**\n\nI built a marketplace of Claude Code skills from my real workflow, applying these patterns. Browse and install them on the [Skills page](https://www.web-developpeur.com/en/skills), including a [skill-builder](https://www.web-developpeur.com/en/skills/skill-builder) skill that condenses these principles. To frame an agent, see also the [CLAUDE.md contexts](https://www.web-developpeur.com/blog/claude-md/).\n\nAim for under 500, but it's not a law: the official docx skill is 590. What matters is that the body doesn't drag detail that should live in a script or a reference file. Go over if the essential content warrants it, then add pointers to side files.\n\nAlmost always the description. Claude under-triggers by default and only consults a skill for a non-trivial task. Make the description more inclusive and \"pushy\" (\"use this skill whenever… even if the user doesn't say…\"), with real trigger phrases. And test: a one-step task will never trigger a skill, and that's normal.\n\nNot by default: 11 of the 17 official skills are a single SKILL.md. You split when the domain is heavy, and then mostly into scripts/ for deterministic work (file manipulation, validation). references/ only earns its place for large multi-variant domains.\n\nSkill = a capability triggered by its description when the situation calls for it. CLAUDE.md = context always loaded for a specific project. Hook = deterministic automation on an event, enforced by the harness, not the model. If it's \"always do X\", it's a hook or a CLAUDE.md, not a skill.", "url": "https://wpnews.pro/news/claude-code-s-17-official-skills-the-rule-vs-the-practice", "canonical_source": "https://dev.to/ohugonnot/claude-codes-17-official-skills-the-rule-vs-the-practice-4f15", "published_at": "2026-07-22 09:00:03+00:00", "updated_at": "2026-07-22 09:31:39.062615+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models"], "entities": ["Anthropic", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/claude-code-s-17-official-skills-the-rule-vs-the-practice", "markdown": "https://wpnews.pro/news/claude-code-s-17-official-skills-the-rule-vs-the-practice.md", "text": "https://wpnews.pro/news/claude-code-s-17-official-skills-the-rule-vs-the-practice.txt", "jsonld": "https://wpnews.pro/news/claude-code-s-17-official-skills-the-rule-vs-the-practice.jsonld"}}