A skill is a short document that teaches Claude about one of your applications, so that anyone on your team can ask for a test in plain English and get one that already understands your domain. This article shows you how to write one, with a complete worked example you can copy.
You do not need to be an engineer to write a skill. If you can describe your application to a new colleague, you can write one.
Why a skill makes such a difference
Without a skill, a request like "test that a broker can submit a new claim" means Claude has to discover everything from scratch: what a broker is, where claims are submitted, what a valid claim looks like, what "submitted" looks like when it worked. It will explore the application and usually get there, but it will ask questions, make assumptions, and take longer.
With a skill, that same sentence lands on a system that already knows your roles, your key screens, your business rules and your vocabulary. The request that used to need three rounds of clarification produces a usable test on the first attempt.
The broader case for this is in Why Skills Matter. This article is the practical how-to.
What a skill actually is
A folder with one required file:
anaqa-store/
SKILL.md <- the only required file
reference/
checkout.md <- optional: deeper detail, loaded only when needed
test-data.mdSKILL.md is a plain text file with a short header and then ordinary prose. That is
the whole format.
The header
---
name: anaqa-store
description: The Anaqa online store - product catalogue, basket and checkout. Use when writing or fixing tests for the Anaqa storefront.
---Two fields matter:
- name — lowercase, hyphenated, matching the folder name.
- description — the most important line in the file. Claude reads descriptions to decide which skill applies, so it must say what the application is and when to use it. "Anaqa store" is too vague. The example above names the domain and the trigger.
A complete worked example
Here is a full skill for the Anaqa demo store used throughout our Exercises. Copy it, then replace the content with your own application.
---
name: anaqa-store
description: The Anaqa online store - product catalogue, basket and checkout. Use when writing, fixing or reviewing tests for the Anaqa storefront.
---
# Anaqa store
An OpenCart storefront selling consumer electronics. Customers browse by
category, open a product, add it to a basket and check out.
Base URL: https://ecom.functionizeapp.com/testsites/anaqa/index.php?route=common/home
## Who uses it
- **Guest shopper** - browses, searches and fills a basket without an account.
Most tests should use this role; it needs no credentials.
- **Registered customer** - additionally has an account, order history and a
wish list. Only needed for order-history and saved-address tests.
## The structure
Products live under **Electronics**, which has these categories:
| Category | Products | Notes |
|---|---|---|
| Mobiles | 30 | The largest category; good for pagination and sort tests |
| Air Conditioner | 5 | Stable prices; good for price assertions |
| Computer Accessories | 3 | Small, good for exact-count assertions |
| Laptops | 2 | Smallest; the fastest category to assert against |
Category pages show a product grid, a Sort By control, a Show (page size)
control, and a "Showing 1 to N of N" counter that is reliable to assert on.
## Rules that matter
- The basket works **signed out**. Do not sign in unless the test is
specifically about an account feature.
- Prices are shown in US dollars with two decimals, e.g. `$175.00`. Product
pages also show an "Ex Tax:" line - assert on the main price, not that one.
- Adding to the basket updates the header basket total in place. It can lag
briefly; verify the basket contents rather than only the header count.
- Category product counts are shown in the sidebar and are trustworthy.
## Vocabulary
- "basket" and "cart" mean the same thing; the UI says **Cart**.
- "listing" means a category page, not a product page.
- "the store" means the storefront, never the OpenCart admin.
## Known-good test data
| Item | Value |
|---|---|
| Cheap product | Vostro 3458, $175.00, in Laptops |
| Expensive product | Boltas 2 Ton 3 Star Split AC, $966.00, in Air Conditioner |
| Category with exactly 2 products | Electronics > Laptops |
## Writing tests for this application
- Prefer assertions on product name **and** price together. Either alone is
weak - names repeat across variants and prices repeat across products.
- Use the "Showing 1 to N of N" counter for count assertions; it is more
stable than counting tiles.
- Never assert on the promotional carousel on the home page. It rotates.What makes a skill good
Write the things a new starter would ask in week one. Not the things in the user manual — the things people only learn by being told. "The basket works signed out" is worth more than a description of what a basket is.
Include the traps. The "Ex Tax" line and the rotating carousel in the example above are exactly the sort of detail that otherwise produces a flaky test and an afternoon of confusion.
Include vocabulary. If your business says "policy" and your UI says "contract", say so. Mismatched vocabulary is the single most common reason a generated test tests the wrong thing.
Give known-good test data. A short table of values that reliably exist saves every future test from inventing its own.
Keep it short. One to two pages. If you need more, put the detail in
reference/ files and mention them in SKILL.md — they are read only when
relevant.
Never put these in a skill
A skill is a shared document. Treat it as readable by everyone in your company.
- No passwords, API keys or tokens. Not even test ones. Use Studio's environment settings and preset variables instead — the exercises deliberately use the store signed out for this reason.
- No customer data. Real names, emails, account numbers or anything personal.
- No internal-only URLs you would not want shared beyond the team that needs them.
Installing it
Claude Desktop or claude.ai
- Put
SKILL.md(and anyreference/files) in a folder named after the skill. - Zip the folder.
- Open Settings → Capabilities → Skills and upload the zip.
Claude Code
Drop the folder into either location — no upload step:
.claude/skills/anaqa-store/SKILL.md # this project only
~/.claude/skills/anaqa-store/SKILL.md # you, everywhereSharing it with colleagues
This is the part that turns one person's knowledge into everyone's.
Keep the skill in version control alongside the application it describes. It changes when the application changes, and it should be reviewed like anything else.
Give business users the zip. A tester or analyst who installs the skill and connects to Functionize over MCP can then write tests in their own words without knowing anything about selectors. That is the point: the engineer writes the skill once, and everyone else gets the benefit.
Name an owner. A skill nobody maintains slowly becomes wrong, and a wrong skill is worse than none — it confidently teaches Claude something untrue.
Checking it works
Install it, then ask for something that should only work if the skill was read:
Which Anaqa category has exactly two products, and what are they?If it answers from the skill, it is loaded. Then try a real request:
Using Functionize, write a test that checks the cheapest laptop is listed at the right price, and run it.Note what you did not have to say: no URL, no product name, no price, no "don't sign in". The skill supplied all of it.
To connect Claude to Functionize so it can create tests directly, see Getting Started with the Functionize MCP Server and Exercise 7.
Start small
Do not try to document a whole ERP in one sitting. Write half a page covering one workflow you test often, install it, and use it for a week. Add the things you find yourself repeatedly explaining. A skill that grows from real use beats one written in a vacuum.
Or let us write it for you
We build skills for customers' systems under test at no charge — SAP, Oracle, Salesforce, Workday, Guidewire, or your own in-house application. You give us access and a walkthrough; we produce the skill and hand it to your team.
See Complimentary Skill Building for Your System Under Test, or raise a ticket and ask.