---
title: "Claim Ledger: Claude Code Skills: How They Work, How to Write One, and How to Check Claude Uses It"
description: "Claude picks a skill from its name and description. How to write the two lines it reads, and check it chose yours."
author: "Harry Floyd"
publication: "The Durability Curve"
canonical: "https://durabilitycurve.com/claims/claude-code-skills/"
essay: "https://durabilitycurve.com/blog/claude-code-skills/"
published: "2026-10-26"
ledger_date: "2026-10-26"
claims: 83
removed_before_publication: 0
---

# Claim Ledger: Claude Code Skills: How They Work, How to Write One, and How to Check Claude Uses It

*Claude picks a skill from its name and description. How to write the two lines it reads, and check it chose yours.*

Essay: https://durabilitycurve.com/blog/claude-code-skills/  
Ledger (canonical, cite this): https://durabilitycurve.com/claims/claude-code-skills/  
Published 2026-10-26 · last verified 2026-10-26

## What the essay claims

Before: "I wrote a skill and it works, so Claude will use it", or "the description is just a summary". After: Claude sees each skill's name and description in a short listing and loads the body only after it has chosen. So the body can be perfect and never run. A skill fires when its name or its description tells Claude what it is for, and a good description rescues a weak name. Calling it by name tests the body, and only reading the choice tests whether Claude will reach for it.

## The claim ladder

What the ladder does not reach: - No row measures a lone skill against the model's own ability across many tasks or models; row 6 is one skill, one model, one prompt set. - Most of row 6's commit requests say "commit", as does the telling name; three requests without the word gave the same result (9 of 9 for every version but the vague one), but that is still one setup. - Nothing here measures how routing degrades as a catalogue grows; the docs describe the mechanism (row 2), and the essay owns that diagnosis.

| # | Claim | Whose behaviour it measures | Status / scope |
|---|---|---|---|
| 1 | A skill is a folder with a SKILL.md; name and description load at startup, the body when chosen | Anthropic's engineering post and docs | Vendor documentation |
| 2 | Claude Code's listing has a budget (by default 1% of the context window); over it, descriptions are dropped starting with the least-used skills | Claude Code docs | Vendor documentation |
| 3 | The description should say what the skill does and when to use it ("Use when"), in the third person | Claude Code docs; Anthropic best practices | Vendor documentation |
| 4 | disable-model-invocation: true keeps Claude from choosing a skill; use it for side effects | Claude Code docs | Vendor documentation |
| 5 | Malformed frontmatter: the skill still runs by name with no metadata, so Claude can't match it; claude plugin validate reports it | Claude Code docs; our run of the validator | Docs + one first-party check |
| 6 | Five versions of one commit skill: the vague one was chosen on 0 of 21 commit requests; a telling name, Anthropic's description, the two together and the recommended version on 21 of 21 each; none took a near-miss review request (0/9 each) or an unrelated one (0/4); typed /helper, the vague one ran 2/2 with no Skill call | Our three pre-registered runs, Claude Code 2.1.292, Opus 5.5, one repository, 41 skills loaded | First-party; twelve phrasings, two or three runs each; every phrasing gave the same result on every repeat |
| 7 | Routing works when the name or the description sets a skill apart and fails only when neither does; a good description rescues a weak name, and a good name a vague description | My earlier two-skill eval (The Skill That Never Fired), Opus 5, Aug 2026, replicated | First-party, one model, single runs per cell |
| 8 | Reading the Skill call shows the choice; activation is keyword-dependent | Scott Spence's sandboxed evals, Sonnet 4.5, four Svelte skills | Third-party, one setup |
| 9 | ChatGPT: skills for Business, Enterprise, Healthcare and Edu; @ to select; Codex reads .agents/skills, $ to mention | OpenAI help (updated ~20 Oct 2026) and build guide | Vendor documentation; plans change |
| 10 | Claude app: skills on Free, Pro, Max, Team and Enterprise, need code execution; Customize > Skills; ZIP upload | Claude Help Center | Vendor; the developer overview still lists paid plans only and an older settings path |
| 11 | Snyk confirmed 76 skills with malicious payloads in their markdown instructions, of 3,984 scanned from two public registries | Snyk (vendor research, Feb 2026) | One vendor |

The guide explains, demonstrates once, and gives a check. It does not survey.

## What would make it wrong

The guide is wrong if Claude chooses skills on something other than the name and description it lists, for instance by reading skill bodies before choosing, so that a vague name and description cost nothing. Two things would show it: a vague skill like the one in row 6 being chosen as often as the sharp ones on a fresh run, or Claude Code's docs changing how the listing works. Either would move the writing advice from "required" to "helpful" and the check would need re-running.

## The evidence, row by row

Labels: VERIFIED = checked against the primary source itself by a checker who did not draft the piece, usually with the exact words, where they sit and the date read · EXECUTED = a run or observation done for the piece (code, a query, a count, or a check made live in an app); the claim is what it returned; run records are not published · CHECKED = checked against its source by a separate checker in the older ledger format, which recorded no quote, locator or date · REPORTED = not verified word for word against a primary source (secondary, not openable in full, or supported only in part); the essay words it accordingly · STRUCK = drafted, checked and removed before publication · EXCLUDED = considered and deliberately left out.

### 1. A skill is a folder with a SKILL.md of instructions, scripts and resources

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-1
- Quote: "A skill is a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), figure caption directly above "The anatomy of a skill"
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 2. Claude uses a skill when relevant, or you call it with /skill-name

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-2
- Quote: "Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), intro, para 1
- URL: https://code.claude.com/docs/en/skills

### 3. When to make a skill

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-3
- Quote: "Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), intro, para 2
- URL: https://code.claude.com/docs/en/skills

### 4. The body loads only when used, unlike CLAUDE.md

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-4
- Quote: "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), intro, para 2
- URL: https://code.claude.com/docs/en/skills

### 5. Custom commands merged into skills

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-5
- Quote: "Custom commands have been merged into skills."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), intro, note
- URL: https://code.claude.com/docs/en/skills

### 6. Claude Code skills follow an open standard used by other tools

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-6
- Quote: "Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), intro, para 3
- URL: https://code.claude.com/docs/en/skills

### 7. OpenAI's skills follow the same standard and load the same way

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-7
- Quote: "Skills build on the open agent skills standard" / "ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill."
- Source: OpenAI, Build skills, ChatGPT and Codex docs (read 23 Oct 2026), intro; progressive disclosure
- URL: https://learn.chatgpt.com/docs/build-skills

### 8. Name and description of every skill go into the system prompt at startup

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-8
- Quote: "At startup, the agent pre-loads the name and description of every installed skill into its system prompt."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), The anatomy of a skill
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 9. The body is read only once Claude judges the skill relevant

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-9
- Quote: "If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), The anatomy of a skill
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 10. Name and description are what Claude uses to decide

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-10
- Quote: "Pay special attention to the name and description of your skill. Claude will use these when deciding whether to trigger the skill in response to its current task."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), Developing and evaluating skills, 'Think from Claude's perspective'
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 11. Default skill: description always in context, full skill loads when invoked

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-11
- Quote: "Description always in context, full skill loads when invoked"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Control who invokes a skill, table, (default) row
- URL: https://code.claude.com/docs/en/skills

### 12. The description is what Claude chooses on, from potentially 100+ skills

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-12
- Quote: "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
- Source: Anthropic, Skill authoring best practices (read 23 Oct 2026), Writing effective descriptions
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

### 13. The listing keeps every name but drops descriptions over budget, least-used first; budget is 1% of context

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-13
- Quote: "The listing always contains every skill name, but if you have many skills, Claude Code drops some descriptions to fit the listing's character budget, which removes the keywords Claude needs to match your request. The budget scales at 1% of the model's context window." / "When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Troubleshooting, Skill descriptions are cut short
- URL: https://code.claude.com/docs/en/skills

### 16. name defaults to the directory name

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-16
- Quote: "Command name shown in the / menu. Defaults to the directory name."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Frontmatter reference, name
- URL: https://code.claude.com/docs/en/skills

### 17. description: what and when; falls back to first line; key use case first; 1,536-character cap in the listing

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-17
- Quote: "What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first non-empty line of the markdown content. Put the key use case first: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Frontmatter reference, description
- URL: https://code.claude.com/docs/en/skills

### 18. Spec limits: name ≤64, lowercase/digits/hyphens, matches folder; description ≤1024, what and when

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-18
- Quote: "Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen." / "Max 1024 characters. Non-empty. Describes what the skill does and when to use it." / "Must match the parent directory name"
- Source: Agent Skills specification (read 23 Oct 2026), Frontmatter table; name field
- URL: https://agentskills.io/specification

### 19. Anthropic: write the description in third person

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-19
- Quote: "Always write in third person. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems."
- Source: Anthropic, Skill authoring best practices (read 23 Oct 2026), Writing effective descriptions, warning
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

### 20. Anthropic's good example: the Git Commit Helper description

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-20
- Quote: "Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."
- Source: Anthropic, Skill authoring best practices (read 23 Oct 2026), Writing effective descriptions, Git Commit Helper skill
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

### 21. Anthropic's vague-description examples

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-21
- Quote: "description: Helps with documents" / "description: Processes data" / "description: Does stuff with files"
- Source: Anthropic, Skill authoring best practices (read 23 Oct 2026), Writing effective descriptions, 'Avoid vague descriptions'
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

### 22. Anthropic's names to avoid, and the gerund convention

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-22
- Quote: "Vague names: helper, utils, tools" / "Consider using gerund form (verb + -ing) for Skill names"
- Source: Anthropic, Skill authoring best practices (read 23 Oct 2026), Naming conventions
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

### 25. Keep the body short: it stays in context once loaded

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-25
- Quote: "Once a skill loads, its content stays in context across turns, so every line is a recurring token cost."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Types of skill content, last para
- URL: https://code.claude.com/docs/en/skills

### 26. Fields outside the spec fail on claude.ai upload and the API

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-26
- Quote: "If you include any field the spec doesn't allow, packaging or upload fails with a hard error instead of ignoring the field"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Using skill frontmatter outside Claude Code
- URL: https://code.claude.com/docs/en/skills

### 27. Personal and project locations

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-27
- Quote: "~/.claude/skills/<skill-name>/SKILL.md" / "All your projects on this machine" / ".claude/skills/<skill-name>/SKILL.md" / "Commit it so your team gets it too"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Choose where skills load, table
- URL: https://code.claude.com/docs/en/skills

### 28. Same name: enterprise over personal over project

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-28
- Quote: "Enterprise over personal, and personal over project."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Resolve skills that share a name, table
- URL: https://code.claude.com/docs/en/skills

### 29. Claude app: plans and code execution

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-29
- Quote: "Skills are available for users on Free, Pro, Max, Team, and Enterprise plans. This feature requires code execution to be enabled"
- Source: Claude Help Center, Use skills in Claude (read 23 Oct 2026), header
- URL: https://support.claude.com/en/articles/12512180-use-skills-in-claude

### 30. Claude app: Customize > Skills, upload a ZIP

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-30
- Quote: "Customize > Skills" / "Package your skill folder as a ZIP file."
- Source: Claude Help Center, Use skills in Claude (read 23 Oct 2026), Use skills; Add custom skills
- URL: https://support.claude.com/en/articles/12512180-use-skills-in-claude

### 31. Developer overview still says paid plans and Settings > Features

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-31
- Quote: "Upload your own Skills as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans"
- Source: Anthropic, Agent Skills overview, developer docs (read 23 Oct 2026), Where Skills work, Claude.ai
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

### 32. Claude app help page gives a 200-character description limit

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-32
- Quote: "This is critical—Claude uses this to determine when to invoke your skill (200 characters maximum)."
- Source: Claude Help Center, How to create custom skills (read 23 Oct 2026), Required metadata fields, description
- URL: https://support.claude.com/en/articles/12512198-how-to-create-custom-skills

### 33. Claude app check: review Claude's thinking

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-33
- Quote: "Review Claude's thinking to confirm it's loading the skill."
- Source: Claude Help Center, How to create custom skills (read 23 Oct 2026), Test your skill, After uploading
- URL: https://support.claude.com/en/articles/12512198-how-to-create-custom-skills

### 34. ChatGPT eligibility

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-34
- Quote: "Skills are available to eligible ChatGPT Business, Enterprise, Healthcare, and Edu users, subject to workspace settings and product availability."
- Source: OpenAI Help Center, Skills in ChatGPT (updated ~20 Oct 2026; browser read 23 Oct 2026), Overview
- URL: https://help.openai.com/en/articles/20001066-skills-in-chatgpt

### 35. ChatGPT: find skills under Plugins

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-35
- Quote: "In the sidebar, select Plugins." / "In the Plugin Directory, select the Skills tab."
- Source: OpenAI Help Center, Skills in ChatGPT (updated ~20 Oct 2026; browser read 23 Oct 2026), Access and create skills
- URL: https://help.openai.com/en/articles/20001066-skills-in-chatgpt

### 36. How to call a skill in ChatGPT and Codex

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-36
- Quote: "In ChatGPT, type @ to select a skill. In Codex CLI or the IDE extension, run /skills or type $ to mention a skill."
- Source: OpenAI, Build skills, ChatGPT and Codex docs (read 23 Oct 2026), How ChatGPT and Codex use skills
- URL: https://learn.chatgpt.com/docs/build-skills

### 37. Codex reads .agents/skills, repo and user

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-37
- Quote: "$REPO_ROOT/.agents/skills" / "$HOME/.agents/skills"
- Source: OpenAI, Build skills, ChatGPT and Codex docs (read 23 Oct 2026), Where Codex loads local skills, table
- URL: https://learn.chatgpt.com/docs/build-skills

### 38. Codex's equivalent of manual-only: allow_implicit_invocation false

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-38
- Quote: "When false, Codex won't implicitly invoke the skill based on user prompt; explicit $skill invocation still works."
- Source: OpenAI, Build skills, ChatGPT and Codex docs (read 23 Oct 2026), Optional metadata
- URL: https://learn.chatgpt.com/docs/build-skills

### 39. disable-model-invocation: for side effects; Claude can't choose it

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-39
- Quote: "Use this for workflows with side effects or that you want to control timing, like /commit, /deploy, or /send-slack-message. You don't want Claude deciding to deploy because your code looks ready."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Control who invokes a skill
- URL: https://code.claude.com/docs/en/skills

### 40. With it set, the description leaves the listing

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-40
- Quote: "Description not in context, full skill loads when invoked"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Control who invokes a skill, table, disable-model-invocation row
- URL: https://code.claude.com/docs/en/skills

### 41. Malformed frontmatter: runs by name, can't be matched

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-41
- Quote: "If the frontmatter YAML is malformed, Claude Code loads the skill body with empty metadata, so /skill-name still works but Claude can't match against your description."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Troubleshooting, Skill not triggering
- URL: https://code.claude.com/docs/en/skills

### 42. claude plugin validate checks skills' frontmatter (v2.1.233+)

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-42
- Quote: "claude plugin validate .claude/skills" / "Requires Claude Code v2.1.233 or later."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Troubleshooting, Skill not triggering
- URL: https://code.claude.com/docs/en/skills

### 43. Seeing it trigger is not the same as it working; measure both

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-43
- Quote: "Seeing a skill trigger tells you Claude found it, not that it did what you intended. To know a skill is working, measure separately whether Claude invokes it on the prompts it should, and whether the output matches what you expect when it does."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Evaluate and iterate on a skill
- URL: https://code.claude.com/docs/en/skills

### 44. Fresh session matters

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-44
- Quote: "A fresh session matters because leftover context from authoring the skill will mask gaps in the written instructions."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Evaluate and iterate on a skill
- URL: https://code.claude.com/docs/en/skills

### 45. Troubleshooting: keywords users would naturally say

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-45
- Quote: "Check the description includes keywords users would naturally say"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Troubleshooting, Skill not triggering, step 1
- URL: https://code.claude.com/docs/en/skills

### 46. skill-creator tunes descriptions with should/shouldn't-trigger prompts

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-46
- Quote: "generates should-trigger and should-not-trigger prompts, measures the hit rate, and proposes description edits when the skill activates on the wrong requests"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Run evals with skill-creator
- URL: https://code.claude.com/docs/en/skills

### 48. Spence detected activation from the Skill call in claude -p stream-json; one question per run

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-48
- Quote: "Runs each of the 22 test prompts through claude -p with --output-format stream-json" / "Parses the JSONL stream for Skill() tool_use events" / "I just need to know, did it call Skill() or not?" (no-hook baselines: 55% (12/22) in run 1, 50% (11/22) in run 2, Sonnet 4.5)
- Source: Scott Spence, Measuring Claude Code Skill Activation With Sandboxed Evals (8 Feb 2026), method list; 'Run 2: confirmation' table
- URL: https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals

### 49. My earlier two-skill result (The Skill That Never Fired): either field carries the choice; it fails only when neither does; a good description rescues a weak name

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-49
- Quote: "When the names were the vague part but the descriptions were sharp, routing was clean." / "It broke in one condition only: format-only names, long-date and slash-date, plus a shared vague description, where neither field told Claude what set the two skills apart." / "A good description rescued names that carried no signal."
- Source: The Durability Curve, The Skill That Never Fired (31 Aug 2026)
- URL: https://harryfloyd.substack.com/p/skill-that-never-fired

### 50. Anthropic: install from trusted sources; audit others; read bundled files

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-50
- Quote: "We recommend installing skills only from trusted sources. When installing a skill from a less-trusted source, thoroughly audit it before use." / "Start by reading the contents of the files bundled in the skill to understand what it does, paying particular attention to code dependencies and bundled resources like images or scripts."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), Security considerations when using Skills
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 51. Anthropic: watch for instructions to connect to untrusted network sources

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-51
- Quote: "pay attention to instructions or code within the skill that instruct Claude to connect to potentially untrusted external network sources."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), Security considerations
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 52. Snyk: 76 malicious payloads in skills' markdown instructions, of 3,984 scanned

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-52
- Quote: "scanning 3,984 skills from ClawHub and skills.sh as of February 5th, 2026" / "76 of Agent Skills contained malicious payloads in their markdown instructions to AI agents"
- Source: Snyk, ToxicSkills (vendor research, 5 Feb 2026), intro; findings
- URL: https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/

### 55. A subagent works in its own context window

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-55
- Quote: "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions."
- Source: Claude Code docs, Create custom subagents (read 23 Oct 2026), intro, para 2
- URL: https://code.claude.com/docs/en/sub-agents

### 56. An invoked skill's content enters the conversation and stays

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-56
- Quote: "When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there across later turns."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Skill content lifecycle
- URL: https://code.claude.com/docs/en/skills

### 59. Commands and skills both create /name

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-59
- Quote: "A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), intro, note
- URL: https://code.claude.com/docs/en/skills

### 61. A frontmatter that doesn't parse: the validator names it and says the skill loads with empty metadata

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-61
- Quote: "frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected token. At runtime this skill loads with empty metadata (all frontmatter fields silently dropped)."
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 62. Vague version (helper / Does stuff with files): chosen on 0 of 12 commit prompts

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-62
- Quote: routing-run-results.tsv: vague, kind P: 12 rows, skill_calls none
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 63. Telling name (writing-commit-messages / Does stuff with files): chosen 12 of 12; prompts echo 'commit'

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-63
- Quote: routing-run-results.tsv: name, kind P: 12 rows, {"skill":"writing-commit-messages"}
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 64. Anthropic's description on the weak name helper: chosen 12 of 12

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-64
- Quote: routing-run-results.tsv: description, kind P: 12 rows, {"skill":"helper"}
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 65. No version was chosen on the two unrelated prompts (0 of 4 each)

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-65
- Quote: routing-run-results.tsv: kind N, 12 rows, skill_calls none
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 66. Typed as /helper, the vague skill ran the house format 2 of 2, with no Skill call in the stream

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-66
- Quote: r1-D1-vague, r2-D1-vague: reply ends 'Refs: PAY-142'; no tool_use named Skill
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 67. Vague replies: 11 of 12 drafted messages carried PAY-142 (one run left it out); none opened type(scope):; two ended 'Refs PAY-142' without the colon

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-67
- Quote: raw/r-P-vague.jsonl result text: PAY-142 in the drafted message 11/12; type(scope): 0/12; 'Refs: PAY-142' 0/12
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 68. The session's skill listing held 41 skills (the test skill and 40 others)

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-68
- Quote: init event: skills array length 41
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 70. Pre-registered before the run; all four rules passed

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-70
- Quote: Pre-registered and hash-locked before the run (042a720e3247); all four of its rules passed
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 71. MCP connects AI applications to external systems

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-71
- Quote: "MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems."
- Source: Model Context Protocol, What is MCP? (read 23 Oct 2026), intro, para 1
- URL: https://modelcontextprotocol.io/docs/getting-started/intro

### 72. Extra files in the folder load only as needed

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-72
- Quote: "skills can bundle additional files within the skill directory and reference them by name from SKILL.md" / "which Claude can choose to navigate and discover only as needed"
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), The anatomy of a skill
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 73. Skills can carry code Claude runs

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-73
- Quote: "Skills can also include code for Claude to execute as tools at its discretion"
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), Skills and code execution
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 74. Anthropic published Agent Skills as an open standard (18 Dec 2025 update)

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-74
- Quote: "Dec 18, 2025" / "We've published Agent Skills as an open standard for cross-platform portability."
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), page header, Update
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 75. Spence's one question per run

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-75
- Quote: "did it call Skill() or not?"
- Source: Scott Spence, Measuring Claude Code Skill Activation With Sandboxed Evals (8 Feb 2026), method
- URL: https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals

### 77. Spence: activation is keyword-dependent; ~100% with the keyword, ~20-40% generic, ~0% indirect (no hook)

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-77
- Quote: "It's keyword-dependent." / "Prompts with explicit skill keywords activate reliably even without a hook." / "But rephrase the same concept without the keyword and it falls over." / "~100%" / "~20-40%" / "~0%"
- Source: Scott Spence, Measuring Claude Code Skill Activation With Sandboxed Evals (8 Feb 2026), What the failures tell me (table: Has keyword / Generic phrasing / Indirect)
- URL: https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals

### 78. Claude Code has a when_to_use field appended to the description in the listing

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-78
- Quote: "Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to description in the skill listing and counts toward the 1,536-character cap."
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Frontmatter reference, when_to_use
- URL: https://code.claude.com/docs/en/skills

### 80. claude.ai uploads accept six frontmatter fields

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-80
- Quote: "name, description, license, compatibility, metadata, allowed-tools"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Using skill frontmatter outside Claude Code, table
- URL: https://code.claude.com/docs/en/skills

### 81. In the Claude app, Claude reviews available skills and loads relevant ones

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-81
- Quote: "When you ask Claude to complete a task, it reviews available skills, loads relevant ones, and applies their instructions."
- Source: Claude Help Center, What are skills? (read 23 Oct 2026), How skills work
- URL: https://support.claude.com/en/articles/12512176-what-are-skills

### 82. Anthropic created the format

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-82
- Quote: "This led us to create Agent Skills"
- Source: Anthropic, Equipping agents for the real world with Agent Skills (16 Oct 2025, updated 18 Dec 2025), intro, para 2
- URL: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

### 83. Anthropic's description examples follow "what, then Use when"

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-83
- Quote: "Use when working with PDF files" / "Use when analyzing Excel files" / "Use when the user asks for help writing commit messages"
- Source: Anthropic, Skill authoring best practices (read 23 Oct 2026), Writing effective descriptions, three examples
- URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

### 84. The essay's other half: a good name rescued vague descriptions

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-84
- Quote: "A good name had already done the same for descriptions that carried none."
- Source: The Durability Curve, The Skill That Never Fired (31 Aug 2026)
- URL: https://harryfloyd.substack.com/p/skill-that-never-fired

### 85. Every prompt × version cell gave the same result on all repeats (effective sample: four phrasings)

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-85
- Quote: routing-run-results.tsv: 18 cells, identical across repeats
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md)

### 87. On three phrasings without "commit", "staged" or "git": name 9/9, description 9/9, both 9/9, vague 0/9

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-87
- Quote: routing-run-2-results.tsv, kind K: 9 rows per version; score2-output.json
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, second pre-registered run)

### 88. The recommended pair (writing-commit-messages + the third-person description): 12/12 on the commit requests, 0/4 unrelated

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-88
- Quote: routing-run-2-results.tsv, version both, kinds P and N
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, second pre-registered run)

### 90. On "the team's usual format" (and once on K1), Claude opened helper's SKILL.md with Read and copied the format, 4 of 9 vague K runs, no Skill call; 0 of 12 first-run vague runs and 0 of 27 other-version K runs opened it

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-90
- Quote: raw2/r1-K1-vague, r1-K3-vague, r2-K3-vague, r3-K3-vague: Read .claude/skills/helper/SKILL.md; reply has type(scope): and Refs: PAY-142
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, second pre-registered run)

### 91. An empty result from the jq line can mean the run failed

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-91
- Quote: One failed run (its result event reports is_error true): the guide's jq reader printed nothing and exited 0
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, second pre-registered run)

### 93. With disable-model-invocation set, a Claude attempt is blocked and told not to reproduce the steps another way

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-93
- Quote: "If Claude tries anyway, Claude Code blocks the call and instructs it not to reproduce the deploy steps another way"
- Source: Claude Code docs, Extend Claude with skills (read 23 Oct 2026), Control who invokes a skill
- URL: https://code.claude.com/docs/en/skills

### 94. No version took a review request (0/9 each); "Review my staged changes for bugs…" went to the bundled code-review skill in all 15 runs; the other two review requests called no skill

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-94
- Quote: routing-run-3-results.tsv, kind NM: 45 rows; code-review in 15 (all NM1)
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, third pre-registered run)

### 95. The recommended (hardened) version: 12/12 commit requests, 9/9 without "commit", 0/9 review, 0/4 unrelated

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-95
- Quote: routing-run-3-results.tsv, version hardened; score3-output.json
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, third pre-registered run)

### 96. No-ticket branch: hardened chosen 6/6, Refs: left out and no ticket invented 6/6; Anthropic-description version chosen 6/6 with a placeholder Refs: line 6/6 (<TICKET-ID> ×5, ??? ×1), no invented ticket

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-96
- Quote: raw3/r-T-hardened-noticket, r-T-both-noticket result text; comply-output.json
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, third pre-registered run)

### 97. Full format check (pre-registered F1–F4) on every chosen ticket-branch run: 84/84; message only 70/84 (14 added a note)

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-97
- Quote: comply-output.json: run1 name 12/12 (10), description 12/12 (12); run2 name 9/9 (7), description 9/9 (6), both 21/21 (17); run3 hardened 21/21 (18)
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, third pre-registered run)

### 98. The recommended description is under the Claude app's 200-character limit

- Status: EXECUTED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-98
- Quote: 179 characters (setup.sh hardened)
- Source: Our run, Claude Code 2.1.292, claude-opus-5-5 (RUN.md, third pre-registered run)

### 99. In the Claude app you can ask for a skill by name in the request

- Status: VERIFIED
- Row link: https://durabilitycurve.com/claims/claude-code-skills/#c-99
- Quote: "Try being more explicit in your request (e.g., \"Use my brand guidelines skill to create a presentation\")."
- Source: Claude Help Center, Use skills in Claude (read 23 Oct 2026), Troubleshooting
- URL: https://support.claude.com/en/articles/12512180-use-skills-in-claude

## Cite

- A claim: name the original source (and its locator) first, then the row it was checked in, e.g. "<source>, <locator>. Checked in: Claim Ledger, "Claude Code Skills: How They Work, How to Write One, and How to Check Claude Uses It", The Durability Curve, row <id>, https://durabilitycurve.com/claims/claude-code-skills/#c-<id>."
- The essay: Floyd, Harry (2026). Claude Code Skills: How They Work, How to Write One, and How to Check Claude Uses It. The Durability Curve. https://durabilitycurve.com/blog/claude-code-skills/
- This ledger: Floyd, Harry (2026). Claim Ledger: Claude Code Skills: How They Work, How to Write One, and How to Check Claude Uses It. The Durability Curve. https://durabilitycurve.com/claims/claude-code-skills/
- Downloads: https://durabilitycurve.com/claims/claude-code-skills.csv · https://durabilitycurve.com/claims/claude-code-skills.json

Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Reuse it, quote it or train on it, with credit to The Durability Curve and a link. Open to AI (robots.txt: search=yes, ai-input=yes, ai-train=yes).