Key takeaway
- See how reusable skill files add vocabulary, rules and reference files so a general AI acts like an industry specialist, plus how to test a skill.
Reusable skill files turn a general AI model into an industry specialist by giving it three things it does not have by default: your sector's vocabulary, your business rules and your reference documents. The model stays the same. The skill tells it what the words mean in your business, which steps to follow and which files to check.
This guide is for anyone curious about agent skills, with no technical background needed. You will learn what a skill is, how a retail, energy and telecom skill could be laid out, and how to test that a skill really works. Sources, including Claude's official documentation, were read on 13 November 2026.
What is an agent skill, in plain words?
A skill is a folder that holds a job manual for an AI agent. Think of the laminated card a new shop assistant keeps by the till: what to do, in what order, and where to look when unsure. According to the Agent Skills overview in Claude's documentation, a skill is a folder with one main file called SKILL.md. That file starts with a short name and description, then holds the instructions.
The folder can also hold extra files, such as longer reference documents or small programs called scripts. Anthropic's engineering post describes skills as organised folders of instructions, scripts and resources that agents discover and load dynamically. The format was published as an open standard on 18 December 2025 and is described at agentskills.io.
The agent does not read everything at once. According to the documentation, it keeps only each skill's name and description in view, about 100 tokens per skill (a token is a small chunk of text, roughly a word), and opens the full instructions only when a task matches. Extra files are opened only if needed.
Availability varies. According to the documentation, custom skills do not sync between the Claude apps, Claude Code and the API, and in the Claude apps they need code execution to be switched on. Plan rules differ between the documentation pages, so check the support article for your plan.
How does a skill make a general model act like a specialist?
A general model knows a little about every industry. It does not know that your company calls a refund a "credit note", or that your network team says "port-out" when a customer leaves. A skill closes that gap with four ingredients.
| Ingredient | Everyday comparison | What it does for the agent |
|---|---|---|
| Vocabulary | The staff glossary | Makes the agent use your terms the way your team does |
| Rules and steps | The procedure card | Sets the order of work, the limits and when to hand over to a person |
| Reference files | The folder under the counter | Holds policies and price lists the agent checks instead of guessing |
| Scripts | The calculator | Does exact sums and lookups with code, so the agent need not work them out in words |
According to Anthropic's announcement, skills can include code for tasks where traditional programming is more reliable than having the model write out the answer. The best practices page adds a useful rule of thumb. Give the agent freedom when many approaches are fine, and give it an exact script when a step is fragile.
What could a retail, energy and telecom skill look like?
The three examples below are illustrations of structure, not real products or customers. Each is a folder with the same shape: a short SKILL.md, a glossary, a policy file and, where useful, a script.
| Sector | Skill folder (illustrative) | Vocabulary and reference files | Stop and hand over to a person |
|---|---|---|---|
| Retail | returns-and-refunds | glossary.md (credit note, store credit, restocking); returns-policy.md; refund-calc script | Refunds above an agreed value, or any request to read out card details |
| Energy | billing-query | glossary.md (kWh, meter read, estimated bill, standing charge); tariffs.md; bill-check script | A customer who may be in a vulnerable situation, or a disputed bill |
| Telecom | complaint-handling | glossary.md (SIM, porting, roaming, ADR letter); complaints-process.md; complaint-clock script | A complaint close to its escalation deadline |
Retail
A returns skill would hold the refund rules and the shop's own words. Card handling needs care. According to the PCI Security Standards Council site, PCI DSS is a baseline of technical and operational requirements for protecting payment account data, and it applies to organisations that store, process or transmit cardholder data. A sensible rule in the skill is that the agent never asks for full card numbers in chat. Confirm your exact obligations on the official PCI page.
Energy
A billing skill would explain bills in plain language and call a script for the arithmetic. Care for customers matters too. In a press release dated 25 October 2016, Ofgem described a wider Priority Services Register and said suppliers would have to take reasonable steps to spot customers who may be vulnerable. That page is old, so check Ofgem's current rules before you write the hand-over step.
Telecom
A complaints skill would track how long a complaint has been open. According to Ofcom's page on quicker complaints resolution, providers must send home and small business customers a letter about independent dispute resolution (ADR) when a complaint is still open after a set time, and that point moves from eight weeks to six from 8 April 2026. A small script can count the days and flag the case early. Confirm the detail on Ofcom's page.
Where do skills live, and how does the agent pick one?
According to the Claude Code skills documentation, a skill can be personal, kept in a folder in your own user account, or shared with a project by keeping it in the project folder. It can also arrive inside a plugin, which is an add-on package. The agent decides for itself: it compares your request with each skill's description and uses the one that fits.
That makes the description the most important line you write. The best practices page asks for a description that says what the skill does and when to use it, written in the third person. Vague wording such as "helps with documents" is a poor trigger. The Claude Code documentation adds that if the wrong skill is chosen, similar skills need clearer, different trigger words.
The Claude support article adds that Team and Enterprise owners can provide skills to everyone in their organisation, which helps keep one approved version in use.
How do you test that a skill really works?
A skill that reads well can still fail. Testing means giving the agent real tasks and checking the results. The best practices page recommends building evaluations before writing long instructions, so the skill solves real problems. Its steps are listed below, followed by one example for each sector.
- Find the gaps. Run the agent on typical tasks without the skill and note where it fails or lacks context.
- Write at least three test scenarios that cover those gaps.
- Record a baseline. Measure how the agent does without the skill.
- Write minimal instructions. Add only what closes the gaps.
- Repeat the tests and compare. Refine until the skill beats the baseline.
The documentation says each test can be a simple record: the request, any files, and the behaviours you expect. It also notes that no built-in test runner exists, so teams build their own, and that the skill should be tried on every model you plan to use.
| Sector | Example test (our suggestion) | Pass looks like |
|---|---|---|
| Retail | A refund request above the agreed limit | The agent stops and routes it to a person |
| Energy | A customer says they cannot read their meter because of an injury | The agent flags possible vulnerability and hands over |
| Telecom | A complaint open for five weeks and six days | The agent warns of the escalation date |
What can a skill not do?
- It does not enforce rules or approvals by itself. A skill tells an agent how to work. Whether an action is allowed needs policy, approval and an audit record around the agent. See our guide to agentic analytics for the data side of that design.
- It can carry risk. According to the documentation, a malicious skill can direct an agent to misuse tools or run harmful code, so use skills you wrote or trust, and audit every file in any other. Anthropic gives the same advice in its engineering post.
Related reading
These posts in the series cover the neighbouring questions.
- AI Agent Skills for Healthcare, Finance and More: Worked skill examples for healthcare, manufacturing, finance and government.
- AI Agent Skills: Enterprise-Ready Digital Workers: How skills turn a chat model into a dependable digital worker.
- Reusable AI Skills for Enterprise Automation: How one skill is reused across teams and tools, and what does not travel.
Try it on one decision first
If you want to see where a specialist skill fits with policy and audit, bring one live decision to the free half-day Context Workshop. ElixirData, a XenonStack product company, offers the Context Workshop and Context OS. Its architects help your team map it, and you leave with a one-page decision map and a go or no-go call. You can request a Context OS demo or book the Context Workshop.
Sources
- Agent Skills overview, Claude documentation
- Agent Skills best practices, Claude documentation
- Skills in Claude Code, Claude documentation
- What are skills?, Claude support
- Anthropic announcement of Skills
- Equipping agents for the real world with Agent Skills, Anthropic engineering
- Agent Skills specification
- PCI DSS, PCI Security Standards Council
- Priority Services Register press release, Ofgem
- Quicker complaints resolution, Ofcom
Frequently asked questions
What is an AI agent skill?
It is a folder with a main file called SKILL.md that tells an AI agent how to do a specific job. It can also hold reference documents and small scripts, and the agent opens it only when a task matches.
How does a skill make a general AI act like a specialist?
It adds your sector's vocabulary, your rules and steps, and your reference files. The model stays the same, but it now follows your procedure and checks your documents instead of guessing.
Do I need to code to write a skill?
No. A skill is mostly written instructions in plain text with simple formatting (Markdown). Scripts are optional and are useful for exact sums or lookups.
How do I test that a skill works?
Run the agent on real tasks without the skill to set a baseline, write at least three test scenarios, add minimal instructions, then repeat the tests and compare. The documentation also advises testing on every model you plan to use.
Can a skill decide whether an action is allowed?
No. A skill describes how to work. Permission, approval and audit must be set up around the agent, and high-risk steps should go to a person.
Are skills safe to install?
Only from sources you trust. According to the documentation, a malicious skill can direct an agent to misuse tools, so audit every bundled file in any skill you did not write.
Follow XenonStack on LinkedIn: XenonStack on LinkedIn for new guides on agentic AI, data and platform engineering.
Ready to put AI agents to work? Explore ElixirClaw, the agentic OS platform to build, orchestrate and govern AI agents.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE
