Claude Skills: Packaging a Repeatable Process as Knowledge

Snapshot of fast-changing documentation: 10 October 2026

A team may find itself doing the same work over and over: reviewing a pull request (PR), checking a change against the requirements in Jira, preparing a migration, or gathering evidence during an incident. If you paste a long checklist into the chat every time, some steps get lost, and each author phrases them differently. A Skill is a way to package a repeatable procedure together with the reference material, templates and, where needed, small programs it relies on.

The body of SKILL.md does not, by itself, grant access to an external system or to secrets, and it does not guarantee that every sentence will be carried out exactly. What a Skill can do depends on the host system and its settings. Claude Code has one important exception that deserves careful review: the allowed-tools field can pre-approve the listed tools for the turn in which the Skill is invoked. It does not remove other available tools, and it does not replace the global permission rules. Check it in every Skill, especially project Skills: this grant can apply even in -p mode, in a directory you have not yet trusted. You need this distinction both when building a safe workflow and when judging its quality (Claude Code documentation on Skill permissions).

In this unit, the term Claude Skills means Skills in specific Anthropic environments. Some fields and the overall structure are based on the open Agent Skills format, but loading, invocation, permissions and support for additional files depend on the product. The details of changeable behaviour below were checked on 10 October 2026; before using them in practice, compare them with the current documentation and the version of your client.

What a Skill packages

A Skill is a directory containing a SKILL.md file. That file holds short metadata used to discover the Skill, and a body with the working instructions. You can add to the directory any material that is not needed for every task:

pr-review/
├── SKILL.md                  # when to apply it and how to run the process
├── references/
│   └── review-rubric.md      # detailed severity scale
├── assets/
│   └── report-template.md    # report template
└── scripts/
    └── list_changed_files.py # optional deterministic operation

This subdirectory structure is not mandatory. The minimal Agent Skills format requires only SKILL.md; scripts/, references/ and assets/ are conventional but optional places for the corresponding material. A reference, template or program is added only when it solves a specific problem in the workflow (Agent Skills specification).

Imagine a football statistics site that imports official records of players moving between teams. A one-off request such as "check that the import preserves history" can explain that task right now. A Skill for reviewing such changes preserves the repeatable order: find the requirement, read the source format, match the event against the roster state, check idempotency, and show the evidence in the report. A dictionary of the external feed's fields can live separately and be loaded only for import changes.

A procedure is worth packaging when it recurs, has a stable order of steps, and needs criteria or resources that are easy to overlook. Not every piece of guidance needs a Skill: a one-off task is easier to describe in the request; a stable fact about the whole repository belongs in the general rules; an operation on a system is performed by a tool or an Application Programming Interface (API); a machine-checkable condition is better enforced by an automated check.

A Skill is not just another word for a prompt

A prompt is a specific message for the current task. A Skill is a reusable package that the host system can offer or load when a task resembles its purpose. Even if the body of a Skill reads like a long prompt, it is surrounded by discovery, a directory of resources and the rules of a particular environment.

Size matters too. If reference material is always loaded into the main SKILL.md, every use carries unnecessary context, and the file becomes harder to update. Anthropic advises keeping SKILL.md under 500 lines and moving detail into linked files. An extra file does not load by magic just because it sits next to SKILL.md: SKILL.md has to explain what it contains and under what condition to read it (Claude Code guidance on supporting files).

The open format and product-specific capabilities

The open Agent Skills standard describes the package structure and a small, portable subset of frontmatter in YAML (YAML Ain't Markup Language, a data serialisation format), meaning the metadata between the --- delimiters at the top of SKILL.md:

---
name: roster-import-review
description: Reviews changes to the import of football transactions. Use for changes to the parser, mapping, deduplication or historical roster state.
license: Apache-2.0
compatibility: Requires access to the Git repository and read access to test fixtures.
metadata:
  owner: data-platform
  version: "1.2"
---

In the standard, name and description are required. The name is limited to 64 characters, consists of lowercase letters, digits and hyphens, matches the name of the parent directory, does not start or end with a hyphen, and contains no double hyphens. The description must fit within 1,024 characters and say what the Skill does and when to use it. The fields license, compatibility, metadata and allowed-tools are optional; the last one is marked experimental in the specification (Agent Skills specification).

The metadata.version key in the example is the team catalogue's own field. The specification allows arbitrary key-value pairs; that does not mean every host understands a version field or uses it to choose a version. Check who reads the metadata, how versions are published, and how a consumer pins a specific copy (Agent Skills specification).

Claude Code supports this shared subset, plus its own fields and behaviour. In Claude Code, all frontmatter fields are formally optional, but a description is recommended: it helps Claude decide when the Skill is relevant. If name is missing, the directory name is normally used. The Claude Code extensions include when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths and shell. This is not a list of universal Agent Skills fields (Claude Code documentation).

For example, in Claude Code, disable-model-invocation: true prevents the model from invoking the Skill automatically, while still letting you invoke it manually as /name. user-invocable: false removes the Skill from the list of commands available to the user, but the model can still invoke it. These fields answer different questions. They affect discovery or how the Skill is launched in Claude Code; they do not turn the Skill's body into access control (Claude Code documentation).

The paths field is another Claude Code extension: glob patterns restrict automatic loading of the Skill to cases where the work touches matching files. For example, the following header suits automatic selection while working on a TypeScript import parser (Claude Code documentation):

---
description: Reviews changes to the parser for official football transactions.
paths:
  - "src/imports/**/*.ts"
---

A path match is a condition for context, not a tool filter, not permission to read that directory, and not a barrier to other paths. A field with the same name in another product may be absent or mean something else (Claude Code documentation).

Claude Code can accept additional fields such as paths, hooks, context: fork, and the execution of commands from the body. Uploading a Skill on the web to claude.ai and the Skills API accept a narrower subset of the standard: name, description, license, compatibility, metadata and allowed-tools. An extra field may cause an error during packaging or upload rather than being silently ignored. In Claude Code, dynamic context injection uses a line of the form !`command` or the corresponding fenced block: the shell command runs before the instructions are passed to the model, and its output is inserted into the context. This is product-specific behaviour that does not work in the claude.ai chat or through the API. In the Cowork desktop app, every such line in a synced Skill is replaced with a disableSkillShellExecution placeholder instead of being executed (Claude Code documentation; Agent Skills overview).

On this upload path, the values of the fields are checked, not just which fields are present. Anthropic limits the name to 64 characters of lowercase letters, digits and hyphens, and forbids Extensible Markup Language (XML) tags and the reserved words anthropic and claude in it; the description cannot be empty, exceed 1,024 characters or contain XML tags. These checks on top of the standard mean that a valid Agent Skills package will not necessarily be accepted by a particular upload API (Agent Skills overview, package structure).

The Claude API requires the Code Execution tool: the Skill runs in an isolated container with no network access and no package installation at run time. Custom Skills uploaded to the API are available across the workspace; Skills uploaded to claude.ai are available to the individual user. In claude.ai, code execution has to be enabled, and an individually uploaded Skill does not automatically become a team or organisation Skill. Check the conditions against the current documentation and your account plan (Anthropic Agent Skills overview).

Codex and ChatGPT have their own discovery locations and invocation rules for Skills; according to their current documentation, the file must contain name and description, and additional interface metadata is kept in a separate agents/openai.yaml. The OpenAI API, in turn, distinguishes between uploaded Skill references and local files for different execution modes. A shared format does not guarantee the same path, file access, script execution, authorisation or automatic invocation. If a package has to work in several host systems, define the smallest common structure and document the product-specific logic separately (OpenAI documentation on Skills for ChatGPT and Codex; OpenAI API documentation on Skills).

Where a Skill lives and how it enters the context

In Claude Code, location determines where a Skill is available:

Location	Typical path	Scope
Personal	~/.claude/skills/<name>/SKILL.md	The user's projects on this machine
Project	.claude/skills/<name>/SKILL.md	The repository; can be shared through Git
Nested	<subdir>/.claude/skills/<name>/SKILL.md	Work in that subtree and the corresponding sessions
Managed	A directory set by an administrator	Devices or users covered by the policy
Plugin	<plugin>/skills/<name>/SKILL.md	Sessions where that plugin is enabled
Synced	A Skill enabled in the claude.ai account	Supported sessions of that account

These are not interchangeable ways of installing a Skill. Cowork sessions and Claude Code cloud sessions do not read the personal ~/.claude/skills/ directory on the user's computer: they use the Skills enabled in the claude.ai account. A cloud session additionally finds project Skills committed to the repository. In a monorepo, the working directory also matters: a file for a subdirectory may become available only when the session works in the corresponding part of the tree (Claude Code documentation; Anthropic Agent Skills overview).

Loading is progressive (Claude Code documentation; Anthropic Agent Skills overview):

1. By default, the host shows the model the names and descriptions of the available Skills. This is a compact index for discovery, not the full instructions. In Claude Code, a Skill with disable-model-invocation: true keeps its description out of the model's context until it is explicitly invoked by hand; settings can also hide a Skill.
2. If the request matches, the model may choose the Skill, or the user invokes it explicitly with a command such as /review-pr.
3. Once invoked, the body of SKILL.md is added to the session context.
4. If needed, the model opens the linked references or templates, or runs a permitted script within what that host allows (Claude Code documentation; Anthropic Agent Skills overview).

In Claude Code, the loaded body of a Skill may stay in the context for subsequent turns. A permission from allowed-tools, however, does not necessarily persist along with the text: the current documentation says the tools it pre-approves are allowed only for the turn in which the Skill is invoked, and the user's next message resets that grant. So keep the lifecycle of the instruction separate from the lifecycle of the permission (Claude Code documentation: permissions and skill content lifecycle).

A Skill's description is a discovery hint, not a deterministic router. Wording such as "use for any work with code" can capture an architecture explanation, a research question or release preparation, even though the workflow is meant for reviewing pull requests. A narrow description with example tasks and clear boundaries usually helps, but the decision still depends on the model and the available context. A long description can also be truncated: in Claude Code, the description and when_to_use fields together have a length limit in the Skills list (Claude Code documentation).

The workflow contract

A reliable Skill starts from a defined piece of work, not from a file name or a list of capabilities. Before writing SKILL.md, agree on its contract:

Part of the contract	What to record
Purpose	What result the workflow should produce, and for whom
Scope	Which tasks are included and which do not belong to the Skill
Inputs	Which issues, diffs, documents, environments or sources must be read
Sources of truth	What we trust, and what to do with stale or contradictory data
Steps	The order of actions and the evidence to collect
Decisions	Which conditions lead to proceeding, an alternative, a clarifying question, or stopping
Output	The format of the report or artefact, and who consumes it
Failure	How to detect missing data, access or confidence, or a contradiction
Side effects	Which changes are allowed, with whose approval and through which tools
Limits	What the workflow cannot prove or carry out

The instruction "review the PR thoroughly" is weak because it defines no source of expected behaviour, no search boundary, no severity of problems and no shape for the result. It is better to say: "read the linked acceptance criteria and the diff; for each finding, give the file, the line and the observable consequence; if the required evidence is missing, flag it as an open question and do not make anything up; do not make changes and do not merge the PR." Then a reviewer can see exactly what to check.

The procedure should also show when not to run. Provide:

• a positive example: the request "review the current PR against the Jira acceptance criteria";
• a negative example: "explain why this data schema was chosen", when the person is only asking for an explanation, not a review of a diff;
• a borderline example: "find the risks in the plan for changing the parser; there is no PR yet". Here the Skill can read the plan and state that a full diff review is not possible, but it must not invent files or conclude that the PR has already been reviewed.

Stop conditions and questions are not excess politeness. If the Jira issue contradicts a test fixture, the Skill should name the conflict and ask for the source of truth to be determined. If access to logs is missing during an incident, it can draw up a list of unknowns, but it must not present assumptions as the result of analysis. If an instruction asks for a merge or a deployment, preparing for the action must be separated from the action itself, and the required approval named explicitly.

When you need a Skill, and when a different mechanism

A Skill can tie other mechanisms together into a procedure, but it does not replace them:

Mechanism	What problem it solves	What it does not guarantee on its own
A persistent rule or CLAUDE.md	A stable fact or convention useful across many tasks	That every step of a complex process is carried out
A one-off prompt	An instruction for one specific session	Repeat discovery and a single team version
Skill	A reusable workflow, its required steps and references	Deterministic invocation, or permission for a side effect
Tool or Model Context Protocol (MCP)	A machine operation, or access to data or an external system	The right strategy for using the result
Subagent	Isolated or parallel work on a separate task	Automatic independence or a correct conclusion
Script	A repeatable deterministic transformation or check	Sound judgement beyond the coded rules
Hook, permission, continuous integration (CI)	Automated control at a configured point	Control over channels that configuration does not cover

Example: reviewing a publishing scheduler. An articles platform needs to check the newsroom's time zone and redelivery of events: if the scheduler sent a publication but received no response, a retry must not create a duplicate. A Skill can read the acceptance criteria, the diff, the changed calls and the tests, and return, for each problem, the path, the condition and the consequence. If the tests have no retry scenario, or the requirements do not define the switch to daylight saving time, it should flag the gap rather than change the scheduler on its own. Publishing to production and disabling the queue remain separate actions with their own permissions.

If agents must always know that the team does not rewrite historical migrations, that is a persistent fact for the repository rules. If they have to go through the steps of a specific PR review, a Skill is the right fit. Checking JSON (JavaScript Object Notation) format or key uniqueness is better left to a test or a program than to the model's textual promise alone. Reading Jira requires an available tool; the Skill only describes how to use it and what to do with the result. Writing "read Jira" in SKILL.md does not create an account or a network permission.

Keep short navigation and the order of work in the main SKILL.md. Hand off large team rules, an API schema, a dependency map or examples to linked files. Add a script for a step where an error from manual repetition is costly and the condition can be coded precisely. Document its input arguments, the files it reads or changes, its external calls, its exit code and its dependencies. A script with a hidden network call or that reads environment variables is part of the package's security surface.

Worked example: a Skill for PR review

Situation. A hypothetical team is changing the import of official transactions on a football statistics site. A player moves from one team to another; the current roster must be updated, and the previous association preserved in the history. Jira holds the acceptance criteria; the PR changes the parser and the handler for repeated events.

The problem. If the prompt simply says "check the code", the review may stop at style, miss a duplicated message, or report a defect that is not in the diff. The team wants to reuse its criteria, but does not want the Skill to change code, post comments or merge the request automatically.

Alternatives. A one-off prompt is simple, but the author has to recreate the checklist every time. A global rule would overload every task with PR-review detail. A GitHub tool can read the diff and the comments, but it does not decide how to match them against the acceptance criteria. So the team creates a separate Skill for the procedure, leaves tool permissions in the existing settings, and gives this workflow no right to make changes.

Action. The package contains a minimal header and explicit boundaries:

---
name: evidence-pr-review
description: Reviews an open pull request against the linked requirements and looks for defects in the changed behaviour. Use when the user asks for a PR review or an assessment of a change before merging; do not use for general architecture explanations, writing code or deployment.
disable-model-invocation: true
---

# Evidence-based change review

1. Identify the pull request and the linked task. Read the acceptance criteria, the diff and the context of the changed calls.
2. Compare the requirements with the code and the existing test fixtures. Distinguish an observed defect, a question for the author, and a risk outside the diff.
3. For each finding, give the file and line, a concrete reproduction condition, and the consequence for the user or the data. Do not claim that a test was run if it was not.
4. If a requirement, access or necessary context is missing, say so and halt any conclusion that depends on it.
5. Return findings from most to least serious; for each, give the severity, the evidence and a possible direction for the fix. If there are no findings, say exactly what was checked and what remained outside the review.
6. Do not edit files, post a comment, approve, merge or deploy changes. Any such action requires a separate explicit instruction in the session and access configured by the host system.

If the pull request or the linked requirements are not specified, ask for clarification first.
For the detailed severity scale and examples, see references/review-rubric.md.

The file references/review-rubric.md can define local severity categories, for example:

Category	Criterion in this teaching example
Blocking defect	The change loses the player's previous team or applies the same transaction twice
Significant risk	The roster state is updated without checking the source or the event identifier
Question	The acceptance criteria or the external contract needed for a conclusion are missing
Observation	A stylistic suggestion with no demonstrated effect on behaviour

The reference must not contradict the Jira requirements or the project rules. In this example, the disable-model-invocation field is a specific Claude Code extension and should not be carried over to another host without adaptation.

Result. For the request "Review the PR linked to DEMO-60", the user invokes the Skill explicitly. The agent returns verified findings, or states honestly that the criteria or the diff are unavailable. It does not claim to have merged the PR, and does not change it just because it saw a button or a tool.

Why this solution fits. The procedure recurs and needs the same evidence and report format each time. The rule "do not merge" in the text is not a technical block, so to actually prevent merging, the tool settings and GitHub permissions must also restrict the channel. Explicit invocation reduces the risk of the Skill running automatically on a request for an explanation.

Limits. The Skill does not prove that every possible defect was found. It does not confirm the CI status unless that source was actually read. If the reviewer has the authority to post comments or merge PRs, that is controlled by external permissions and a separate instruction, not by the wording in Markdown.

Short example: reviewing a publishing scheduler

A content platform team wants to review scheduler changes without copying the checklist into every request. A publication is scheduled in the newsroom's time zone; if the response from the service is lost, a repeated event must not create a duplicate. The Skill can be described like this:

---
name: content-publish-review
description: Reviews PRs about publication scheduling, time zones and repeated event handling. Use to review such changes, not for deployment or editing copy.
disable-model-invocation: true
---

# Publication change review

1. Read the linked task, the acceptance criteria, the diff and the changed calls.
2. Check the time zone and repeated-event handling against the code and the existing tests.
3. For each comment, give the file, line, condition and consequence; distinguish a defect from a question and from a risk outside the diff.
4. If a requirement, access or evidence is missing, name the gap and halt the dependent conclusion.
5. Do not edit, publish, deploy or disable the scheduler.

Explicit invocation helps keep this workflow from running on an ordinary request to explain the architecture. It is neither a permission nor a technical block: external actions remain under the control of tools and the environment's policy. In the test set, check a request with an open PR, a paraphrase of it, a description of a delay with no PR, and a case where the requirement does not specify a time zone. This complements the example above with a different kind of repeatable check and shows that triggers need to be narrow.

Worked example: a broad description causes false triggers

Situation. An invented team has a software-helper Skill with the description "helps with any software team task: code, Jira, releases, incidents and architecture". Its body mostly teaches how to read a diff and prepare a review. For requests such as "why is the queue delaying messages?" and "prepare a release plan", the model sometimes opens this Skill.

The problem. The description is far broader than the workflow. These are false triggers, not evidence that the Skill should do more kinds of work. Adding new steps to an already large body can make it confusing and increase conflicts with other Skills.

Alternatives. You could build a broader Skill that investigates queues, reviews PRs, plans releases and changes the architecture all at once. The other way is to narrow the boundary. If a question asks for an explanation, ordinary analysis without a Skill may be enough. Separate repeatable processes get separate packages: evidence-pr-review, release-readiness and incident-triage.

Action. The author rewrites the description to be specific: "Reviews the changed code of an open pull request against the linked requirements. Use for a PR review request or a pre-merge check; do not use for explaining architecture, writing a release plan or investigating a live incident." The trigger tests include a direct phrasing, a synonymous request, an incomplete task and negative examples. The release and incident workflows have their own inputs, evidence, outputs and limits on side effects.

Test request	Expected behaviour
"Review the open PR and check it against the Jira requirements"	Select the PR-review Skill
"Check this change for bugs before merging"	Probably select it, after clarifying what is to be reviewed
"Why does the parser store two identical transactions?"	Explain or investigate the data; do not pretend this is a PR review
"What is a safe order of steps for the release?"	Do not run the PR-review workflow
"Queue latency has spiked in production, help me locate the cause"	If one exists, the incident workflow; do not start changing code automatically

Result. The description now matches a single purpose, and the neighbouring processes have their own contracts. The team evaluates activation and the usefulness of the result separately: whether the Skill was invoked on the right requests, and whether the review was done well once it was.

Why this solution fits. A short catalogue description should help recognise the scope, not promise "everything for everyone". Separate Skills can be maintained and tested independently; some tasks need no Skill at all.

Limits. Precise wording in the description does not guarantee zero false triggers: the choice is automatic and depends on context. Explicit invocation also does not prove that the workflow completed correctly. If a wrong automatic decision could cause an external side effect, a narrow description alone is not enough: you need permissions and execution barriers.

Worked example: a third-party Skill asks to send the .env file

Situation. An unknown author distributes a Skill called "integration setup". Its body instructs the agent to open the .env file and upload it to an address the project does not control, in order to "check the configuration". A script in scripts/ hides a Hypertext Transfer Protocol (HTTP) request behind the innocuous name check_config.py.

The problem. .env may contain database passwords, API keys or tokens. A Skill's instructions are content, and a bundled script is executable code. A public Uniform Resource Locator (URL) or a star count proves neither the origin of each version nor the absence of a malicious step.

Alternatives. Running the Skill blindly is fastest, but risks exposing secrets. You could instead first review the whole package without running it, ask for a safe list of variable names without values, or use an approved configuration tool with test data.

Action. Before installing, check the repository owner, the change history, the licence of that specific directory, the frontmatter, every link, the scripts, external calls and dependencies. Do not run the script, and do not give it access to secrets. For the check that is actually needed, provide only the names of the required parameters, or a redacted configuration without values; ask the owner for an approved endpoint. If a real secret has already been sent, follow the credential rotation procedure rather than assuming that deleting the message undoes the leak.

Result. The check was halted before any secret was sent. The team recorded the exact version and its decision about the package, or rejected it. The instruction in the Skill did not give it network rights or access to .env; real capabilities still depend on the host system's permissions and isolation.

Why this solution fits. A package has to be assessed as a whole, not by reading the top lines of SKILL.md. A static body can contain prompt injection, meaning instructions that try to change the model's behaviour; a script can perform effects the text does not explain. Repeat the review on every update, because a new commit can change the code or the target of a network request.

Limits. Reading the code does not prove it is safe in every configuration. Protection is strengthened by version control, a restricted sandbox, no secrets available by default, network access rules, vetted dependencies and review of changes to the package. A licence sets the terms of use, but it is not a security certificate.

Different processes need different contracts

The same principles carry over to different tasks, but they should not be mixed into one universal workflow:

Scenario	What a Skill can prepare	Where a stop or separate permission is needed
Jira → implementation	Check the requirements, list the gaps, map criteria to files and prepare evidence of completion	Do not change the status or assignee without the required authorisation; do not invent acceptance criteria
Migration	Read the current contract and the dependent readers, prepare a compatibility plan, checks and rollback	Before writing to a shared database, deleting data or applying to production
Release	Gather readiness artefacts, the version, the changes, open risks and the rollback path	Do not publish or deploy; do not declare success without confirmation from the environment
Incident	Build a timeline from logs, separate facts from hypotheses, find the owner and the next safe step	Do not run destructive commands, rotate keys or restore production without a separate procedure
Architecture decision	Compare alternatives by load, failure modes, data, cost of change and evidence	Do not present assumptions as fact; the decision belongs to the architecture owner

For example, for the football import system, a migration Skill can prepare the move from a single current_team_id field to a log of roster-change history, identify the readers and propose a compatibility plan. That is not the same as permission to apply the migration to a shared database. For an incident Skill, a timestamped log of evidence is useful, but the Skill must not automatically switch off the official transactions feed just because latency has increased.

Testing, maintenance and diagnosis

Test two separate properties:

1. Discovery. Does the Skill run on the tasks it is meant for, and stay out of similar but unrelated ones?
2. Execution quality. When invoked, did it collect the required evidence, return the expected result, flag what is unknown, and respect the limits on side effects?

Anthropic advises comparing realistic requests in fresh sessions with and without the Skill. A fresh context matters: while writing, the author already knows what they meant, and their earlier messages can mask a weakness in the text. For evaluation, use direct and paraphrased positive requests, negative examples, borderline or incomplete data, duplicated or contradictory instructions, and an attempt to perform an external action (Claude Code documentation on evaluating Skills).

A convenient diagnostic matrix:

Observation	Likely problem area	What to check
The Skill does not run on a direct request	Discovery, description, or install location	Whether the host sees the Skill, whether the task is named clearly, whether the source is enabled
It runs on irrelevant tasks	Scope too broad, or overlap with a neighbouring Skill	Edit the description, add negative boundaries, separate the processes
It runs but does not follow the procedure	The body or the resources	Check the order of steps, how specific the evidence is, the stop conditions and the links to references
It refers to a non-existent version or tool	Compatibility	Check the product, the API, the version and the tools actually available
It performs an unwanted side effect	The control architecture, not just the text	Restrict tool access, apply an ask/deny policy or external approval

Record the host product and version, the install directory, the package's commit or release, the test requests, the expectations, the actual results, the tools and the evaluator. Separately check instructions that rely on new frontmatter fields, shell execution, hooks or API attachments. Do not claim support on another host just because both read SKILL.md.

The current documentation ties some capabilities to versions. For example, background for a forked Skill requires Claude Code v2.1.218 or later; syncing Skills from claude.ai in the terminal requires v2.1.273 or later. These markers show why you should check the exact host and its version rather than carrying a capability over to other surfaces (Claude Code documentation). These minimum versions were checked on 10 October 2026; a later client may add other conditions.

Do not rely on implicit numbering of the directory as the package version. For reproducibility, record the commit or release that contains it, and describe the change in behaviour: what changed in the triggers, steps, resources, scripts and host requirements. Claude Code frontmatter has no separate standardised version field that a host is obliged to read; an arbitrary metadata.version only makes sense for your own catalogue or for a tool that explicitly consumes it. Review a third-party Skill again after each update, and keep its change history in a controlled repository (Agent Skills specification; Claude Code documentation).

A short design heuristic

Before publishing a Skill, it is worth going through this sequence:

1. Name one repeatable task, and what explicitly stays outside its boundaries.
2. Write a catalogue description with concrete triggers and negative examples.
3. Define the data sources, steps, decisions, the criterion for sufficient evidence, the response format and a safe stop condition.
4. Move bulky reference material or machine-repeatable work into a separate resource, with an explanation of when to read or run it.
5. Separate textual recommendation from actual permission to touch files, the network, tools and side effects.
6. Review the whole package: its authorship, licence, history, links, scripts, dependencies and any possible access to secrets.
7. Test in separate sessions when the Skill activates and what it produces, on positive, negative and borderline requests.
8. Repeat the testing for the product and version that will actually use the package.

If the procedure is stable but the model often skips a step, first make the instruction itself more specific; if the condition is precise and machine-checkable, move it into a deterministic script or CI. If relying on the model's intent is unsafe, change the access or a barrier in the host system. A good Skill does not grow into a miniature universal agent: it provides a clear workflow, knows its own limits, and leaves verifiable evidence.

Sources and further reading

Access to the changeable pages and the state of the examples were checked on 10 October 2026. Product documentation is rolling documentation: compare it with the version your workflow actually runs on.

1. Anthropic, Extend Claude with skills — Claude Code Docs, current online documentation, accessed 2026-10-10. Used for Skill paths, Claude Code frontmatter, discovery and loading, permissions, supporting files, evaluation, version caveats, and differences from other distribution methods.
2. Agent Skills, Specification, current format specification, accessed 2026-10-10. Used for the minimal directory structure, the required name and description, and the optional standard metadata.
3. Anthropic, Agent Skills overview, current online documentation, accessed 2026-10-10. Used for progressive loading, API prerequisites, and the limits of running Skills in an isolated environment.
4. OpenAI, Build skills — ChatGPT Learn, current online documentation, accessed 2026-10-10. Used only for a brief comparison of Codex/ChatGPT requirements, progressive disclosure and invocation by description.
5. OpenAI, Skills — API documentation, current online documentation, accessed 2026-10-10. Used to illustrate that loading Skills through the API depends on the execution type and how files are attached.
6. Anthropic, the skill-creator Skill at commit ef740771, its SKILL.md at that commit and the LICENSE.txt in that directory, checked 2026-10-10. A public example of the boundary between a short entry point, scripts, references and evaluation helper files; the directory's licence is Apache License 2.0. The file history shows a specific rewrite in commit 3d595115 of 2026-02-25: it removed the sentence "Do not include any other fields in YAML frontmatter.", which is still present in the ef740771 snapshot. Licences must be checked separately for each directory in a third-party repository.
7. Anthropic, issue #249 in anthropics/skills, an open report created 2026-01-18; accessed 2026-10-10. A historical report about the sentence "Do not include any other fields in YAML frontmatter.", which appeared in the SKILL.md snapshot cited by the source, from commit ef740771 of 2025-12-01. The sentence was removed when the file was rewritten in commit 3d595115 of 2026-02-25; the open issue does not mean that the current main branch still contains this instruction. The example shows why a report must be checked against the current commit rather than read as a description of the present state.