[{"data":1,"prerenderedAt":1075},["ShallowReactive",2],{"blog-claude-skills-guide-en":3},{"slug":4,"published":5,"minutes":6,"category":7,"tags":8,"tagPages":14,"keywords":16,"about":28,"sources":35,"cover":57,"og":58,"expertise":59,"locales":60,"lang":61,"title":64,"description":65,"coverAlt":66,"metaTitle":67,"takeaways":68,"faq":74,"toc":90,"blocks":121,"others":793},"claude-skills-guide","2026-10-20",12,"agents",[9,10,11,12,13],"Claude skills","SKILL.md","Claude Code","Agent Skills","Progressive disclosure",[15],"claude-code",[17,18,19,20,21,22,23,24,25,26,27],"claude skills","claude code skills","how to create a claude skill","skill.md format","agent skills specification","claude skill frontmatter","skill description triggering","progressive disclosure skills","claude skills vs mcp","skills api","custom slash commands skills",[29,32],{"name":30,"url":31},"Claude (AI)","https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FClaude_(AI)",{"name":33,"url":34},"Anthropic","https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FAnthropic",[36,39,42,45,48,51,54],{"title":37,"url":38},"Claude Code documentation: skills","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fskills",{"title":40,"url":41},"Agent Skills overview, Claude API documentation","https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fagents-and-tools\u002Fagent-skills\u002Foverview",{"title":43,"url":44},"Skill authoring best practices, Claude API documentation","https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fagents-and-tools\u002Fagent-skills\u002Fbest-practices",{"title":46,"url":47},"Agent Skills specification","https:\u002F\u002Fagentskills.io\u002Fspecification",{"title":49,"url":50},"Evaluating skill output quality, Agent Skills documentation","https:\u002F\u002Fagentskills.io\u002Fskill-creation\u002Fevaluating-skills",{"title":52,"url":53},"Equipping agents for the real world with Agent Skills, Anthropic engineering blog","https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fequipping-agents-for-the-real-world-with-agent-skills",{"title":55,"url":56},"The state of Claude skills in 2026, SkillGild analysis of Ahrefs data","https:\u002F\u002Fdev.to\u002Fskillgild\u002Fthe-state-of-claude-skills-in-2026-what-38000-searches-say-248n","\u002Fimages\u002Fblog\u002Fclaude-skills-guide\u002Fcover.webp","\u002Fimages\u002Fblog\u002Fclaude-skills-guide\u002Fog.jpg","ai-engineer",[61,62,63],"en","de","hu","Claude skills: how to write a SKILL.md that loads at the right moment","How to write a Claude skill: directory layout, frontmatter fields and limits, progressive disclosure, descriptions that trigger, scripts and testing.","Claude skills and SKILL.md: an open toolbox holds upright folders, and one folder is pulled out with a single sheet.","How to write a Claude skill · Balázs Csorba",[69,70,71,72,73],"A skill is a folder whose SKILL.md frontmatter tells Claude when to use it; the instructions and bundled files load later, only when a task needs them.","The name is 1 to 64 characters of lowercase letters, numbers and hyphens; the description may run to 1,024 characters and should say what the skill does and when to use it.","Claude Code silently ignores unknown frontmatter fields, while claude.ai uploads and the Skills API reject them, so validate the file on the surface where you ship it.","Write the description in the third person with the words users actually type; the skill listing cuts long text at 1,536 characters, so put the use case first.","Test each skill in fresh sessions with and without it, starting from at least three evaluations for the gaps you found.",[75,78,81,84,87],{"q":76,"a":77},"What is the difference between a Claude skill and a prompt?","A prompt is guidance for one conversation or task. A skill is a folder that Claude loads on demand: the name and description are always available, the SKILL.md body loads when the skill is triggered, and bundled files load only when a task reads them.",{"q":79,"a":80},"Which fields does a SKILL.md file need?","The open Agent Skills standard requires name and description. The name is 1 to 64 characters of lowercase letters, numbers and hyphens. The description is 1 to 1,024 characters and says what the skill does and when to use it. Claude Code makes every field optional and adds fields for invocation, arguments and subagents.",{"q":82,"a":83},"Where should a skill file be saved?","Save a personal skill at ~\u002F.claude\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md to use it in every project on that machine, and a project skill under .claude\u002Fskills\u002F to share it through the repository. Plugin skills load wherever the plugin is enabled. On claude.ai you upload a zip file through Settings > Features, and the API uses the \u002Fv1\u002Fskills endpoints.",{"q":85,"a":86},"Why does my skill not trigger?","Check that the description contains the words users actually type, ask Claude which skills are available, rephrase the request, and invoke the skill with \u002Fskill-name. Malformed frontmatter leaves the skill without its description, so run claude plugin validate on the skills folder.",{"q":88,"a":89},"Should a skill call a script or contain the logic itself?","Put deterministic steps in a bundled script that Claude runs, and keep judgment calls in the instructions. Claude runs the script through bash and sees only its output, which saves context and gives repeatable results. Allow the script in allowed-tools so the run does not stop at a permission prompt.",[91,94,97,100,103,106,109,112,115,118],{"id":92,"title":93},"what-is-a-skill","What is a skill, and how does it differ from a prompt?",{"id":95,"title":96},"skill-directory-layout","What does a skill directory contain?",{"id":98,"title":99},"frontmatter-fields-and-limits","Which frontmatter fields exist, and what are their limits?",{"id":101,"title":102},"progressive-disclosure","How does progressive disclosure keep skills cheap?",{"id":104,"title":105},"writing-the-description","How should the description be written so the skill triggers?",{"id":107,"title":108},"where-skills-live","Where do skills live, and which sessions load them?",{"id":110,"title":111},"invocation-arguments-and-permissions","How do invocation, arguments and tool permissions work?",{"id":113,"title":114},"bundling-scripts-and-references","How should scripts and reference files be bundled?",{"id":116,"title":117},"testing-and-iterating","How do you test and iterate on a skill?",{"id":119,"title":120},"sources","Sources",[122,130,139,142,155,170,171,192,198,215,216,230,355,373,387,414,415,423,427,434,439,445,446,451,454,465,466,477,541,550,564,573,574,599,601,629,637,644,656,671,672,677,683,696,698,701,704,705,710,713,744,758,768,769],{"type":123,"content":124},"paragraph",[125,126,129],"A Claude skill is a folder with a ",{"tag":127,"children":128},"code",[10]," file at its root. The file opens with YAML frontmatter that says what the skill does and when to use it, followed by Markdown instructions. Claude reads the frontmatter at startup, loads the instructions when a request matches the skill, and opens bundled files only when a step needs them. Claude Code, the Claude API and claude.ai all support skills built on this format; Claude Code adds fields beyond the open Agent Skills standard.",{"type":123,"content":131},[132,133,138],"Demand for the topic is large. In the Ahrefs data that SkillGild analyzed, “claude skills” and “claude code skills” each draw about 10,000 US searches a month, as of the 6 October 2026 export. The site already explains why skills are worth using, in the ",{"tag":134,"to":135,"children":136},"link","\u002Fblog\u002Fcoding-agent-skills-workflow",[137],"coding-agent skills workflow"," post. This guide covers authoring: the directory layout, every frontmatter field and its limits, how the description decides when a skill loads, where skills live, how arguments and tool permissions work, and how to test a skill. Each limit is taken from the Claude documentation or the open standard it cites.",{"type":140,"level":141,"id":92,"text":93},"heading",2,{"type":123,"content":143},[144,145,149,150,154],"A skill is a reusable, filesystem-based resource that gives Claude domain-specific expertise. A prompt is conversation-level guidance for one task. A skill loads on demand, so you do not repeat the same guidance in every conversation (",{"tag":146,"href":41,"children":147},"a",[148],"Agent Skills overview","). To choose between skills, project rules and MCP tools, read the ",{"tag":134,"to":151,"children":152},"\u002Fblog\u002Fagents-md-skills-mcp-cli-decision-matrix",[153],"decision matrix post",".",{"type":123,"content":156},[157,158,161,162,165,166,169],"Interest has moved from explanation to practice. SkillGild reports that volume for “claude skills” rose after Anthropic launched Agent Skills in October 2025, peaked in January 2026 and has since fallen about 62 percent. The practical queries kept growing: “how to create a claude skill” and its variants add up to about 10,200 searches a month (",{"tag":146,"href":56,"children":159},[160],"SkillGild analysis","). For my own setup, I keep about 20 agent skills in ",{"tag":127,"children":163},[164],"~\u002F.agents\u002Fskills",", and ",{"tag":127,"children":167},[168],"jev-decide"," is one of them.",{"type":140,"level":141,"id":95,"text":96},{"type":123,"content":172},[173,174,176,177,180,181,184,185,188,189,191],"Only ",{"tag":127,"children":175},[10]," is required. The open standard defines three optional directories: ",{"tag":127,"children":178},[179],"scripts\u002F"," for executable code, ",{"tag":127,"children":182},[183],"references\u002F"," for documentation that Claude reads on demand, and ",{"tag":127,"children":186},[187],"assets\u002F"," for templates, images and data files. A skill can add other files and directories (",{"tag":146,"href":47,"children":190},[46],").",{"type":193,"src":194,"alt":195,"wide":196,"caption":197},"image","\u002Fimages\u002Fblog\u002Fclaude-skills-guide\u002Fcalc-7-en.webp","Folder layout of a Claude skill named pdf-processing, with SKILL.md, FORMS.md, REFERENCE.md and a script",true,"A skill folder named pdf-processing. SKILL.md is required and holds the frontmatter and overview. FORMS.md is read only when a form task needs it, REFERENCE.md only when an API detail is needed. scripts\u002Ffill_form.py runs through bash, and its code never enters the context.",{"type":123,"content":199},[200,201,203,204,207,208,211,212,191],"Three rules from the docs shape the layout. Keep each reference file focused, because agents load them on demand and smaller files use less context. Keep file references one level deep from ",{"tag":127,"children":202},[10],", since Claude may only preview a file that another referenced file points to, which can leave information out. Use forward slashes in paths, even on Windows, and name files for their content, such as ",{"tag":127,"children":205},[206],"form_validation_rules.md"," rather than ",{"tag":127,"children":209},[210],"doc2.md"," (",{"tag":146,"href":44,"children":213},[214],"best practices",{"type":140,"level":141,"id":98,"text":99},{"type":123,"content":217},[218,219,222,223,226,227,229],"The open standard requires two fields, ",{"tag":127,"children":220},[221],"name"," and ",{"tag":127,"children":224},[225],"description",", and makes the rest optional. Claude Code treats every field as optional, recommends ",{"tag":127,"children":228},[225],", and adds fields for invocation, arguments and subagents. The table lists the fields you will use most, with the limits from the spec and the docs.",{"type":231,"head":232,"rows":241},"table",[233,235,237,239],[234],"Field",[236],"Required?",[238],"What it does",[240],"Limits",[242,252,262,273,283,293,303,313,329,342],[243,246,248,250],[244],{"tag":127,"children":245},[221],[247],"Yes in the standard; optional in Claude Code",[249],"Identifier; in Claude Code, the command name, defaulting to the directory name",[251],"1–64 characters: lowercase letters, numbers, hyphens; no leading, trailing or doubled hyphen; no reserved words such as “anthropic” or “claude”",[253,256,258,260],[254],{"tag":127,"children":255},[225],[257],"Yes in the standard; recommended in Claude Code",[259],"What the skill does and when Claude should use it",[261],"1–1,024 characters; no XML tags",[263,267,269,271],[264],{"tag":127,"children":265},[266],"when_to_use",[268],"No",[270],"Extra trigger phrases or example requests, appended to the description",[272],"Counts toward the 1,536-character listing cap (Claude Code)",[274,278,279,281],[275],{"tag":127,"children":276},[277],"license",[268],[280],"License name or a bundled license file",[282],"Keep it short (spec)",[284,288,289,291],[285],{"tag":127,"children":286},[287],"compatibility",[268],[290],"Environment needs: products, system packages, network access",[292],"Up to 500 characters (spec)",[294,298,299,301],[295],{"tag":127,"children":296},[297],"metadata",[268],[300],"Key-value map for your own tooling",[302],"String keys and string values (spec)",[304,308,309,311],[305],{"tag":127,"children":306},[307],"allowed-tools",[268],[310],"Tools the skill may use without a permission prompt",[312],"Experimental in the standard; space-separated",[314,318,319,324],[315],{"tag":127,"children":316},[317],"disable-model-invocation",[268],[320,323],{"tag":127,"children":321},[322],"true"," means only you can invoke the skill",[325,326],"Claude Code only; default ",{"tag":127,"children":327},[328],"false",[330,334,335,339],[331],{"tag":127,"children":332},[333],"user-invocable",[268],[336,338],{"tag":127,"children":337},[328]," hides the skill from the \u002F menu, so only Claude invokes it",[325,340],{"tag":127,"children":341},[322],[343,347,348,353],[344],{"tag":127,"children":345},[346],"argument-hint",[268],[349,350],"Autocomplete hint, such as ",{"tag":127,"children":351},[352],"[issue-number]",[354],"Claude Code only",{"type":123,"content":356},[357,358,361,362,365,366,369,370,191],"The name rules are strict: 1 to 64 characters of lowercase letters, numbers and hyphens, with no leading, trailing or doubled hyphen. The spec also requires the name to match the parent directory. Claude Code is looser. A directory called ",{"tag":127,"children":359},[360],"deploy-staging"," with ",{"tag":127,"children":363},[364],"name: deploy"," is invoked as ",{"tag":127,"children":367},[368],"\u002Fdeploy",", so the field sets the command name (",{"tag":146,"href":38,"children":371},[372],"Claude Code docs",{"type":123,"content":374},[375,376,378,379,382,383,386],"Two details cause most silent failures. Claude Code ignores an unrecognized field without an error, so a misspelled ",{"tag":127,"children":377},[307]," does nothing. It reads frontmatter only when the opening ",{"tag":127,"children":380},[381],"---"," is the first line, and if the YAML does not parse, the skill loads with empty metadata and cannot be matched by its description. The spec’s reference library, run as ",{"tag":127,"children":384},[385],"skills-ref validate .\u002Fmy-skill",", checks the frontmatter and naming rules.",{"type":388,"variant":389,"title":390,"body":391},"callout","warn","One file, two outcomes",[392],[393,394,396,397,396,399,396,401,396,403,222,405,407,408,411,412,191],"The same frontmatter can pass in one place and fail in another. claude.ai uploads, the Skills API and the packaging script accept only ",{"tag":127,"children":395},[221],", ",{"tag":127,"children":398},[225],{"tag":127,"children":400},[277],{"tag":127,"children":402},[287],{"tag":127,"children":404},[297],{"tag":127,"children":406},[307],", and any other key fails with an error such as ",{"tag":127,"children":409},[410],"Unexpected key(s) in SKILL.md frontmatter: argument-hint",". Claude Code accepts its own extra fields, so the same file works locally and fails on upload (",{"tag":146,"href":38,"children":413},[372],{"type":140,"level":141,"id":101,"text":102},{"type":123,"content":416},[417,418,420,421,191],"Claude loads a skill in three stages, and each stage costs context only when it is needed. The metadata, about 100 tokens per skill, loads at startup. The ",{"tag":127,"children":419},[10]," body, recommended under 5,000 tokens, loads when the skill is triggered. Bundled files cost nothing until a task reads or runs them (",{"tag":146,"href":41,"children":422},[148],{"type":193,"src":424,"alt":425,"wide":196,"caption":426},"\u002Fimages\u002Fblog\u002Fclaude-skills-guide\u002Fdiagram-17.webp","Three loading levels of a Claude skill: metadata at startup, instructions when triggered, resources when used","Only the name and description occupy context until a skill is triggered; each later stage adds context only when a task needs it.",{"type":123,"content":428},[429,430,433],"So installed skills are cheap, and long skills are not. Keep the body under 500 lines and move detail into reference files, as the spec and the best-practices guide both advise. Anthropic’s ",{"tag":146,"href":53,"children":431},[432],"engineering post on Agent Skills"," covers the architecture and real-world uses in more depth.",{"type":123,"content":435},[436,437,191],"Two behaviors matter in long sessions. Claude Code does not re-read the file on later turns, so a rule that must hold for the whole task belongs in standing instructions. After a conversation is compacted, Claude Code re-attaches the latest invocation of each skill, keeping the first 5,000 tokens of each within a combined budget of 25,000 tokens. Put the critical instructions near the top (",{"tag":146,"href":38,"children":438},[372],{"type":123,"content":440},[441,442,444],"The skill listing has a budget of its own, scaled at 1 percent of the model’s context window. When many skills overflow it, Claude Code drops the descriptions of the skills you invoke least first, and it cuts the combined description and ",{"tag":127,"children":443},[266]," text at 1,536 characters in any case.",{"type":140,"level":141,"id":104,"text":105},{"type":123,"content":447},[448,449,191],"The description is the one part of a skill that Claude reads before deciding to load the rest, so it must say what the skill does and when to use it. Write it in the third person, and include the words a user would type. Claude chooses among potentially 100 or more skills using these descriptions, so each one needs enough detail to make that choice (",{"tag":146,"href":44,"children":450},[214],{"type":123,"content":452},[453],"The third-person rule exists because the description is injected into the system prompt, and an inconsistent point of view can hurt discovery. The guide’s examples show the contrast. “Processes Excel files and generates reports” works; “I can help you process Excel files” and “You can use this to process Excel files” do not. Vague lines such as “Helps with documents”, “Processes data” and “Does stuff with files” give Claude nothing to match. Its PDF example names both the actions and the triggers: “Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.”",{"type":123,"content":455},[456,457,460,461,154],"When a skill does not trigger, check that the description contains the words users say, confirm the skill appears when you ask what skills are available, rephrase the request, and invoke it as ",{"tag":127,"children":458},[459],"\u002Fskill-name"," to rule out a naming problem. Put the key use case first, because the listing cuts long text. The same rule applies to agent tools; see ",{"tag":134,"to":462,"children":463},"\u002Fblog\u002Fagent-tool-design-descriptions-errors",[464],"designing tools for AI agents",{"type":140,"level":141,"id":107,"text":108},{"type":123,"content":467},[468,469,472,473,476],"Where a skill is saved decides which sessions load it. A personal skill in ",{"tag":127,"children":470},[471],"~\u002F.claude\u002Fskills\u002F"," loads in every project on that machine. A project skill in ",{"tag":127,"children":474},[475],".claude\u002Fskills\u002F"," loads in its repository, so commit it to share it. A plugin skill loads wherever the plugin is enabled. Claude Code reads project skills from the directory where you start and from each parent up to the repository root.",{"type":231,"head":478,"rows":485},[479,481,483],[480],"Location",[482],"Path",[484],"Loads in",[486,496,505,513,522,534],[487,489,494],[488],"Enterprise",[490,493],{"tag":127,"children":491},[492],".claude\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md"," in the managed settings directory",[495],"All users on machines where the organization deploys it",[497,499,503],[498],"Personal",[500],{"tag":127,"children":501},[502],"~\u002F.claude\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md",[504],"All your projects on this machine, but not Cowork or cloud sessions",[506,508,511],[507],"Project",[509],{"tag":127,"children":510},[492],[512],"Sessions in this repository; commit it so the team gets it too",[514,516,520],[515],"Nested",[517],{"tag":127,"children":518},[519],"\u003Csubdir>\u002F.claude\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md",[521],"Sessions started in or below that subdirectory",[523,525,529],[524],"Plugin",[526],{"tag":127,"children":527},[528],"\u003Cplugin>\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md",[530,531],"Wherever the plugin is enabled, as ",{"tag":127,"children":532},[533],"\u002Fplugin-name:skill-name",[535,537,539],[536],"claude.ai account",[538],"Skills enabled for the account",[540],"Cowork, cloud and terminal sessions signed in with that account",{"type":123,"content":542},[543,544,222,547,154],"Nested skills load the first time Claude reads or edits a file in their subdirectory, and edits made during a session take effect without a restart. Two folder names are reserved: ",{"tag":127,"children":545},[546],"synced",{"tag":127,"children":548},[549],"anthropic-skills",{"type":388,"variant":551,"title":552,"body":553},"note","Personal skills are invisible to cloud sessions",[554],[555,556,558,559,561,562,191],"Cowork and cloud sessions do not read ",{"tag":127,"children":557},[471]," on your machine, so a scheduled cloud task that invokes a skill stored only there reports that the skill was not found. Enable the skill for your claude.ai account, or commit it to the repository’s ",{"tag":127,"children":560},[475]," for cloud sessions outside project threads (",{"tag":146,"href":38,"children":563},[372],{"type":123,"content":565},[566,567,570,571,191],"The other surfaces have their own rules. On claude.ai you upload a zip file through Settings > Features. This needs a Pro, Max, Team or Enterprise plan with code execution enabled, and the skills belong to each user, not the organization. The Claude API takes skills through the ",{"tag":127,"children":568},[569],"\u002Fv1\u002Fskills"," endpoints and shares them across the workspace. Skills do not sync between surfaces, so upload each one where you want it (",{"tag":146,"href":41,"children":572},[148],{"type":140,"level":141,"id":110,"text":111},{"type":123,"content":575},[576,577,580,581,584,585,587,588,591,592,594,595,598],"By default, you and Claude can both invoke a skill. ",{"tag":127,"children":578},[579],"disable-model-invocation: true"," makes a skill manual-only, ",{"tag":127,"children":582},[583],"user-invocable: false"," makes it Claude-only, ",{"tag":127,"children":586},[307]," pre-approves tools for the turn that invokes it, and ",{"tag":127,"children":589},[590],"context: fork"," runs it in a subagent. The example below uses three features: an ",{"tag":127,"children":593},[346],", pre-approved git commands and a ",{"tag":127,"children":596},[597],"$ARGUMENTS"," placeholder.",{"type":127,"code":600},"---\nname: summarize-changes\ndescription: Summarizes uncommitted changes and flags risks. Use when the user asks what changed, wants a commit message, or asks to review their diff.\nargument-hint: [focus-area]\nallowed-tools: Bash(git diff *) Bash(git status *)\n---\n\n## Current changes\n\n!`git diff HEAD`\n\n## Instructions\n\nSummarize the changes above in two or three bullet points. Focus area, if one was given: $ARGUMENTS\n\nList the risks you notice, such as missing error handling, hardcoded values, or tests that need updating.\n\nIf the diff is empty, say there are no uncommitted changes.",{"type":123,"content":602},[603,604,606,607,396,610,613,614,617,618,620,621,624,625,628],"Arguments arrive through ",{"tag":127,"children":605},[597],", or through ",{"tag":127,"children":608},[609],"$0",{"tag":127,"children":611},[612],"$1"," and so on for single positions. Quote a multi-word value to keep it as one argument, so ",{"tag":127,"children":615},[616],"\u002Fmy-skill \"hello world\" second"," sets ",{"tag":127,"children":619},[609]," to ",{"tag":127,"children":622},[623],"hello world",". If the skill has no placeholder for the input, Claude Code appends it as ",{"tag":127,"children":626},[627],"ARGUMENTS: \u003Cvalue>",", so Claude still sees it.",{"type":123,"content":630},[631,633,634,636],{"tag":127,"children":632},[307]," grants permission only for the turn that invokes the skill, and the grant clears when you send your next message. It does not restrict tools; your permission settings still govern everything the list does not name. Workspace trust does not gate the field, so a project skill’s ",{"tag":127,"children":635},[307]," applies even in a folder you have never trusted. Review that field in any skill you take from a repository.",{"type":123,"content":638},[639,640,643],"The shell-injection line in the example runs ",{"tag":127,"children":641},[642],"git diff HEAD"," before Claude sees the skill, and the output replaces the placeholder. Injected commands skip the prompt but still pass your permission rules. Outside auto mode, a command whose check does not come back as allowed aborts the invocation, and one failed command aborts the whole skill, not just its own line. That is why the example pre-approves the git commands.",{"type":123,"content":645},[646,648,649,652,653,154],{"tag":127,"children":647},[590]," starts a subagent of the type named in ",{"tag":127,"children":650},[651],"agent"," and passes it the skill as its prompt. The subagent does not see your conversation, so the skill has to stand on its own. The docs note that the setting suits skills with explicit instructions; a skill that holds only guidelines returns nothing useful. Forked skills run in the background unless you set ",{"tag":127,"children":654},[655],"background: false",{"type":123,"content":657},[658,659,662,663,666,667,670],"To control which skills Claude may call, use rules such as ",{"tag":127,"children":660},[661],"Skill(commit)"," for one exact name or ",{"tag":127,"children":664},[665],"Skill(deploy *)"," for a name with any arguments. Denying the Skill tool in ",{"tag":127,"children":668},[669],"\u002Fpermissions"," disables every skill.",{"type":140,"level":141,"id":113,"text":114},{"type":123,"content":673},[674,675,191],"Bundle a script when the result must be identical every time, and let Claude run it rather than read it. Claude executes bundled scripts through bash and sees only their output (",{"tag":146,"href":41,"children":676},[148],{"type":123,"content":678},[679,680,191],"The best-practices guide sets the bar. Handle the error case rather than failing and leaving Claude to guess, and justify every constant: a 30-second timeout with a comment explaining it is documented, while an unexplained number is a “voodoo constant”. The spec adds that scripts should be self-contained or document their dependencies, print useful error messages and handle edge cases (",{"tag":146,"href":47,"children":681},[682],"spec",{"type":123,"content":684},[685,686,689,690,692,693,695],"Refer to the script with ",{"tag":127,"children":687},[688],"${CLAUDE_SKILL_DIR}",", which expands to the directory holding the skill’s ",{"tag":127,"children":691},[10],". Using the same variable in the instructions and in ",{"tag":127,"children":694},[307]," lets the script run without a permission prompt. The docs use this pattern:",{"type":127,"code":697},"---\nname: render-chart\ndescription: Render a chart from a CSV file\nallowed-tools: Bash(${CLAUDE_SKILL_DIR}\u002Fscripts\u002Frender.sh *)\n---\n\nRun `${CLAUDE_SKILL_DIR}\u002Fscripts\u002Frender.sh \u003Ccsv-file>` to render the chart.",{"type":123,"content":699},[700],"Where a skill runs decides what it can reach. On the Claude API, skills have no network access and cannot install packages at runtime, so every dependency must already be present. On claude.ai, network access depends on user and admin settings. In Claude Code, a skill has the same network access as any other program on the machine, though global package installs are discouraged.",{"type":123,"content":702},[703],"Treat a skill like installed software. Use only skills you wrote or got from Anthropic, read every bundled file, and take extra care with skills that fetch external content, because fetched text can carry instructions. The overview also warns that a trustworthy skill can be compromised when its external dependencies change.",{"type":140,"level":141,"id":116,"text":117},{"type":123,"content":706},[707,708,191],"Test two things separately: whether Claude loads the skill for the prompts it should, and whether the output is right when it does. Seeing a skill trigger shows only the first. Run a few realistic prompts in fresh sessions, with the skill and without it, because leftover context from writing the skill hides gaps (",{"tag":146,"href":38,"children":709},[372],{"type":123,"content":711},[712],"The best-practices guide asks for evaluations before documentation. Find where Claude fails without the skill, write at least three evaluations for those gaps, record a baseline, then add the smallest instructions that pass. Test with every model you plan to use. The guide’s checklist names Haiku, Sonnet and Opus, and notes that what works for Opus may need more detail for Haiku.",{"type":123,"content":714},[715,716,719,720,723,724,727,728,731,732,735,736,739,740,743],"For a personal or project skill, set it to ",{"tag":127,"children":717},[718],"\"off\""," in ",{"tag":127,"children":721},[722],"skillOverrides"," to get the baseline run. The skill-creator plugin automates the loop: it stores cases in ",{"tag":127,"children":725},[726],"evals\u002Fevals.json",", runs each in its own subagent, grades assertions into ",{"tag":127,"children":729},[730],"grading.json",", rolls pass rate and tokens into ",{"tag":127,"children":733},[734],"benchmark.json",", and can tune the description with should-trigger and should-not-trigger prompts. Its format differs from the one ",{"tag":127,"children":737},[738],"claude plugin eval"," uses for plugins. The ",{"tag":146,"href":50,"children":741},[742],"evaluation guide on agentskills.io"," explains the iteration workflow.",{"type":123,"content":745},[746,747,750,751,753,754,757],"Two commands catch problems that are otherwise hard to see. ",{"tag":127,"children":748},[749],"claude plugin validate"," reports ",{"tag":127,"children":752},[10]," files whose frontmatter does not parse (Claude Code v2.1.233 or later). ",{"tag":127,"children":755},[756],"\u002Fskill-doctor"," shows what each skill costs in the listing and flags skills that are never invoked (v2.1.252 or later).",{"type":123,"content":759},[760,761,763,764,154],"Finally, watch how Claude navigates the skill. The best-practices guide lists four signals: unexpected reading orders, links Claude never follows, a reference file it reads on every task, and bundled files it never opens. Each points to a structural fix, such as a more explicit link or a file moved into ",{"tag":127,"children":762},[10],". If you are building skills or agent workflows for a team, see my ",{"tag":134,"to":765,"children":766},"\u002Fexpertise\u002Fai-engineer",[767],"AI engineering work",{"type":140,"level":141,"id":119,"text":120},{"type":770,"ordered":196,"items":771},"list",[772,775,778,781,784,787,790],[773],{"tag":146,"href":38,"children":774},[37],[776],{"tag":146,"href":41,"children":777},[40],[779],{"tag":146,"href":44,"children":780},[43],[782],{"tag":146,"href":47,"children":783},[46],[785],{"tag":146,"href":50,"children":786},[49],[788],{"tag":146,"href":53,"children":789},[52],[791],{"tag":146,"href":56,"children":792},[55],[794,863,914,1015],{"slug":795,"published":796,"minutes":6,"category":7,"tags":797,"tagPages":802,"keywords":804,"about":815,"sources":820,"cover":857,"og":858,"expertise":59,"locales":859,"lang":61,"title":860,"description":861,"coverAlt":862},"claude-in-opencode","2026-10-30",[798,11,799,800,801],"OpenCode","Claude Agent SDK","Coding agents","LLM pricing",[15,803],"coding-agents",[805,806,807,808,809,810,811,812,813,814],"claude in opencode","opencode claude","opencode claude agent","opencode claude subscription","opencode claude max","opencode anthropic api key","claude agent sdk opencode","opencode claude code login","opencode github copilot claude","opencode zen claude pricing",[816,817,818],{"name":30,"url":31},{"name":33,"url":34},{"name":798,"url":819},"https:\u002F\u002Fopencode.ai",[821,824,827,830,833,836,839,842,845,848,851,854],{"title":822,"url":823},"OpenCode v2.2.3 release notes (October 30, 2026)","https:\u002F\u002Fgithub.com\u002Fanomalyco\u002Fopencode\u002Freleases\u002Ftag\u002Fv2.2.3",{"title":825,"url":826},"OpenCode pull request #58782: add Claude Agent provider","https:\u002F\u002Fgithub.com\u002Fanomalyco\u002Fopencode\u002Fpull\u002F58782",{"title":828,"url":829},"Claude Agent provider design spec","https:\u002F\u002Fgithub.com\u002FTarquinen\u002Fopencode\u002Fblob\u002Fclaude-agent-provider\u002Fspecs\u002Fv2\u002Fclaude-agent-provider.md",{"title":831,"url":832},"OpenCode docs: Providers","https:\u002F\u002Fopencode.ai\u002Fv2\u002Fdocs\u002Fproviders\u002F",{"title":834,"url":835},"OpenCode docs: Models","https:\u002F\u002Fopencode.ai\u002Fv2\u002Fdocs\u002Fmodels\u002F",{"title":837,"url":838},"OpenCode docs (v1): Providers, note on Claude Pro\u002FMax plugins","https:\u002F\u002Fopencode.ai\u002Fdocs\u002Fproviders\u002F",{"title":840,"url":841},"OpenCode Console: models and pricing","https:\u002F\u002Fopencode.ai\u002Fv2\u002Fdocs\u002Fconsole\u002Fmodels\u002F",{"title":843,"url":844},"OpenCode Go: plans and usage limits","https:\u002F\u002Fopencode.ai\u002Fv2\u002Fdocs\u002Fconsole\u002Fgo\u002F",{"title":846,"url":847},"Claude Code docs: Legal and compliance","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Flegal-and-compliance",{"title":849,"url":850},"Claude Help Center: Use the Claude Agent SDK with your Claude plan","https:\u002F\u002Fsupport.claude.com\u002Fen\u002Farticles\u002F15036540-use-the-claude-agent-sdk-with-your-claude-plan",{"title":852,"url":853},"Claude Platform docs: Pricing","https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fabout-claude\u002Fpricing",{"title":855,"url":856},"GitHub Docs: Supported AI models in GitHub Copilot","https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Freference\u002Fai-models\u002Fsupported-models","\u002Fimages\u002Fblog\u002Fclaude-in-opencode\u002Fcover.webp","\u002Fimages\u002Fblog\u002Fclaude-in-opencode\u002Fog.jpg",[61,62,63],"Claude in OpenCode: the Claude Agent provider, API keys and the other routes","How to use Claude in OpenCode: the new Claude Agent provider on your Claude plan, API keys, Console, Copilot and OpenRouter, with costs and limits.","Claude in OpenCode: a hand plugs one of two adapters into a laptop that shows a terminal window.",{"slug":864,"published":865,"minutes":866,"category":7,"tags":867,"tagPages":872,"keywords":873,"about":884,"sources":889,"cover":908,"og":909,"expertise":59,"locales":910,"lang":61,"title":911,"description":912,"coverAlt":913},"claude-code-review","2026-10-21",11,[11,868,869,870,871],"Code review","GitHub","Pull requests","Review costs",[15],[874,875,876,877,878,879,880,881,882,883],"claude code review","claude code review github","claude code review pricing","code review generally available","ai pull request review","claude github app review","review level quick standard deep","claude code review setup","review spend limit","automated code review agents",[885,887],{"name":886,"url":31},"Claude",{"name":868,"url":888},"https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FCode_review",[890,893,896,899,902,905],{"title":891,"url":892},"Claude: Code Review is now generally available (Oct 15, 2026)","https:\u002F\u002Fclaude.com\u002Fresources\u002Farticles\u002Fcode-review-is-now-generally-available",{"title":894,"url":895},"Claude Code docs: Code Review","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fcode-review",{"title":897,"url":898},"Claude Code docs: Set up Code Review","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fcode-review-setup",{"title":900,"url":901},"Claude Code docs: Code Review costs and usage","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fcode-review-costs",{"title":903,"url":904},"Claude: Code Review research preview announcement","https:\u002F\u002Fclaude.com\u002Fresources\u002Farticles\u002Fcode-review",{"title":906,"url":907},"Claude Code docs: GitHub Actions","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fgithub-actions","\u002Fimages\u002Fblog\u002Fclaude-code-review\u002Fcover.webp","\u002Fimages\u002Fblog\u002Fclaude-code-review\u002Fog.jpg",[61,62,63],"Claude Code Review is generally available: how the multi-agent review works and costs","Claude Code Review, now GA for Team and Enterprise: how agents verify findings, set review levels, cap spend, and compare with the GitHub Action.","Claude Code Review: three magnifying glasses examine a sheet of lines, and one line is circled and checked.",{"slug":915,"published":916,"updated":917,"minutes":918,"category":7,"tags":919,"tagPages":923,"keywords":925,"about":938,"sources":948,"cover":1009,"og":1010,"expertise":59,"locales":1011,"lang":61,"title":1012,"description":1013,"coverAlt":1014},"token-saving-tools-coding-agents-top-20","2026-08-26","2026-09-23",17,[11,920,921,922],"token usage","Context engineering","developer tools",[15,924],"context-engineering",[926,927,928,929,930,931,932,933,934,935,936,937],"reduce Claude Code token usage","token saving tools for coding agents","rtk token killer","lean-ctx","context-mode MCP","Serena MCP","Repomix compress","MCP tool search","prompt caching","ccusage","coding agent cost","context engineering",[939,942,945],{"name":940,"url":941},"Large language model","https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FLarge_language_model",{"name":943,"url":944},"Claude (language model)","https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FClaude_(language_model)",{"name":946,"url":947},"Prompt engineering","https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FPrompt_engineering",[949,952,955,958,961,964,967,970,973,976,979,982,985,988,991,994,997,1000,1003,1006],{"title":950,"url":951},"rtk: a CLI proxy that filters shell output for coding agents (GitHub)","https:\u002F\u002Fgithub.com\u002Frtk-ai\u002Frtk",{"title":953,"url":954},"lean-ctx: context read modes and shell compression for coding agents (GitHub)","https:\u002F\u002Fgithub.com\u002Fyvgude\u002Flean-ctx",{"title":956,"url":957},"context-mode: sandboxed tool output with SQLite FTS5 search (GitHub)","https:\u002F\u002Fgithub.com\u002Fmksglu\u002Fcontext-mode",{"title":959,"url":960},"Serena: semantic code retrieval and editing over MCP (GitHub)","https:\u002F\u002Fgithub.com\u002Foraios\u002Fserena",{"title":962,"url":963},"token-savior: symbol index, memory and bash compaction over MCP (GitHub)","https:\u002F\u002Fgithub.com\u002FMibayy\u002Ftoken-savior",{"title":965,"url":966},"code-review-graph: a code graph for blast-radius reviews (GitHub)","https:\u002F\u002Fgithub.com\u002Ftirth8205\u002Fcode-review-graph",{"title":968,"url":969},"Aider documentation: repository map","https:\u002F\u002Faider.chat\u002Fdocs\u002Frepomap.html",{"title":971,"url":972},"Repomix: pack a repository into one AI-friendly file (GitHub)","https:\u002F\u002Fgithub.com\u002Fyamadashy\u002Frepomix",{"title":974,"url":975},"Context7: up-to-date library documentation for LLMs (GitHub)","https:\u002F\u002Fgithub.com\u002Fupstash\u002Fcontext7",{"title":977,"url":978},"claude-context: hybrid code search MCP (GitHub)","https:\u002F\u002Fgithub.com\u002Fzilliztech\u002Fclaude-context",{"title":980,"url":981},"caveman: terse output modes for coding agents (GitHub)","https:\u002F\u002Fgithub.com\u002FJuliusBrussee\u002Fcaveman",{"title":983,"url":984},"claude-token-efficient: an eight-rule CLAUDE.md (GitHub)","https:\u002F\u002Fgithub.com\u002Fdrona23\u002Fclaude-token-efficient",{"title":986,"url":987},"claude-code-router: a local model gateway for coding agents (GitHub)","https:\u002F\u002Fgithub.com\u002Fmusistudio\u002Fclaude-code-router",{"title":989,"url":990},"ccusage: token and cost reports from local agent logs (GitHub)","https:\u002F\u002Fgithub.com\u002Fryoppippi\u002Fccusage",{"title":992,"url":993},"LLMLingua: prompt compression (Microsoft, GitHub)","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FLLMLingua",{"title":995,"url":996},"ComputingForGeeks: tools that reduce Claude Code token usage, tested (April 2026)","https:\u002F\u002Fcomputingforgeeks.com\u002Freduce-claude-code-token-usage-tools\u002F",{"title":998,"url":999},"Claude Code docs: manage costs effectively","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fcosts",{"title":1001,"url":1002},"Claude Code docs: MCP, output limits and tool search","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fmcp",{"title":1004,"url":1005},"Claude API docs: tool search tool","https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fagents-and-tools\u002Ftool-use\u002Ftool-search-tool",{"title":1007,"url":1008},"Claude API docs: prompt caching","https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fbuild-with-claude\u002Fprompt-caching","\u002Fimages\u002Fblog\u002Ftoken-saving-tools-coding-agents-top-20\u002Fcover.webp","\u002Fimages\u002Fblog\u002Ftoken-saving-tools-coding-agents-top-20\u002Fog.jpg",[61,62,63],"Top 20 ways to cut coding-agent tokens: rtk, lean-ctx, Serena and more, ranked by evidence","rtk, lean-ctx, context-mode, Serena and 16 more token savers for coding agents, ranked by evidence, with my own measurements on a real Nuxt codebase.","Cutting coding-agent tokens: a press shrinks a tall coin stack into a short one, a robot with a trophy beside it.",{"slug":1016,"published":1017,"updated":1018,"minutes":1019,"category":7,"tags":1020,"tagPages":1024,"keywords":1025,"about":1037,"sources":1044,"cover":1069,"og":1070,"expertise":59,"locales":1071,"lang":61,"title":1072,"description":1073,"coverAlt":1074},"agent-loop-explained","2026-07-16","2026-09-04",10,[1021,800,1022,11,1023],"Agent loop","Tool calling","Stop conditions",[803,15],[1026,1027,1028,1029,1030,1031,1032,1033,1034,1035,1036],"agent loop","human in the loop AI agent","agentic loop","AI agent loop","tool calling loop","Ralph loop coding agent","Claude Code \u002Floop","Claude Code \u002Fgoal","how to stop an AI agent from looping","ReAct agent pattern","stop_reason tool_use",[1038,1041,1042],{"name":1039,"url":1040},"Intelligent agent","https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FIntelligent_agent",{"name":940,"url":941},{"name":11,"url":1043},"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Foverview",[1045,1048,1051,1054,1057,1060,1063,1066],{"title":1046,"url":1047},"Anthropic: Building effective agents (Dec 2024)","https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents",{"title":1049,"url":1050},"Yao et al.: ReAct: Synergizing Reasoning and Acting in Language Models (2022)","https:\u002F\u002Farxiv.org\u002Fabs\u002F2210.03629",{"title":1052,"url":1053},"Claude API docs: Handling stop reasons","https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fbuild-with-claude\u002Fhandling-stop-reasons",{"title":1055,"url":1056},"Anthropic: Effective harnesses for long-running agents (Nov 2025)","https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Feffective-harnesses-for-long-running-agents",{"title":1058,"url":1059},"Simon Willison: Red\u002Fgreen TDD (Agentic Engineering Patterns)","https:\u002F\u002Fsimonwillison.net\u002Fguides\u002Fagentic-engineering-patterns\u002Fred-green-tdd\u002F",{"title":1061,"url":1062},"Geoffrey Huntley: Ralph Wiggum as a software engineer (Jul 2025)","https:\u002F\u002Fghuntley.com\u002Fralph\u002F",{"title":1064,"url":1065},"Claude Code docs: Run prompts on a schedule (\u002Floop)","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fscheduled-tasks",{"title":1067,"url":1068},"Claude Code docs: Keep Claude working toward a goal (\u002Fgoal)","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fgoal","\u002Fimages\u002Fblog\u002Fagent-loop-explained\u002Fcover.webp","\u002Fimages\u002Fblog\u002Fagent-loop-explained\u002Fog.jpg",[61,62,63],"The agent loop, explained: how coding agents run, and how to make them stop","How the agent loop works in code, which stop conditions and budgets to enforce, and how outer loops like Ralph and Claude Code \u002Floop and \u002Fgoal behave.","The agent loop: a small robot walks a circular track that a striped barrier arm crosses next to a finish flag.",1793451241839]