---
url: "https://www.reddit.com/r/ClaudeAI/comments/1wyjty8/anthropics_official_agent_skills_guide_6_insights/"
title: "Anthropic's official agent skills guide. 6 insights"
source_kind: reddit
subreddit: ClaudeAI
author: BuffaloConscious7919
captured: "2026-10-08T18:11:04+00:00"
comment_tree: false
topics: [practice, skills]
summary: "Anthropic's skill authoring guide highlights 6 key practices: use gerund names, keep references shallow, add a table of contents, rely on evaluation-driven development, treat descriptions as the product, and use progressive disclosure."
status: ok
---

we know agent skills are a double edged beast, but did you know Anthropic dropped an update to their skill authoring docs?? Were we all to busy making mods ???
once again i took 10 minutes to read this and then summarise the information into 6 key points covered by the guide
- name skills with gerunds (ideally). stop calling skills "utils" or "data".. the guide recommends "-ing" verbs like processing-pdfs or analyzing-spreadsheets because it clearly describes what the skill does. noun phrases (pdf-processing) or action names (process-pdfs) are apparently ok too.. just be consistent across your library..
- keep references one level deep. link every reference file directly from SKILL.md. if SKILL.md points to a file that points to another file, claude may only preview it, checking only the first 100 chars. subfolders are fine, chains of links aren't
- use a table of contents. sometimes. agents might read the first 100 lines of a file to check if it's relevant. If the good stuff is at line 350, put a table of contents at the top so it knows to keep reading
- rely on evaluation-driven dev. don't just vibe check your skills. run claude on the task WITHOUT the skill first, note where it fails, build a few test scenarios, measure a baseline, and only then write just enough to fix the gaps. sidenote: the guide says theres no built-in way to run these evals yet so you roll your own
- treat the description as the product. its always loaded and its how Claude picks your skill out of possibly 100+ others. if its vague,it just won't get picked. sidenote: write it in the third person and say what it does AND when to use it, with the actual key terms users will say...
- the most valuable rule IMO: progressive disclosure is king. instead of wacking all your rules into the system prompt, only the name + descripition sits there at startup. SKILL.md only loads when the skill is relevant, and extra files only load when actually needed. keep SKILL.md under 500 lines and split the rest out
One other note from the document: test your skill on every model you plan to use it with. what works for Opus might need more detail for Haiku.
source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices