Create a skill

This is the practical guide. By the end you'll have a working SKILL.md you can submit. We'll cover four authoring paths — pick the one that fits how you already work.

Frame: skills run inside an agent that can use your computer

Most regional tasks don't have an API. There's no public endpoint to file a GST return at IRD, fix a HOP-card concession issue at AT, claim a refund through the Woolworths app, or look up your council's building consent records. The institutions publish web UIs and apps — that's it.

That means the runtime that makes regional skills broadly useful is Computer Use— the AI agent operating the browser / app on the user's behalf, with their consent, on their machine. Anthropic's Claude has this built in (Computer Use, available in Claude Desktop and Claude Code). Other agents are catching up.

Your skill's SKILL.md is, in that sense, a runbook for the agent driving the user's computer. It says: when this scenario comes up, do these steps in this UI, watch for these states, refuse these requests, output a final result in this shape. The clearer and more grounded the runbook, the better the agent can follow it.

Skills are still useful in draft-onlymode (the agent produces a message the user pastes themselves) — that's what most of the NZ seed skills do at launch. But the natural trajectory is toward Computer Use as the primary execution model. Build your SKILL.md so it works both ways.

Path A — Supervised execution with Computer Use (recommended)

This is the highest-leverage authoring path. Open the target service (website / app / portal) on one side of your screen, Claude Desktop on the other, and authorise Computer Use. Then you and Claude do the task together — Claude actually executes it for real. Pick one of two modes:

Mode 1 — Dictation (you drive, Claude executes)

You tell Claude what to do, step by step in plain language. Claude clicks, types, and scrolls via Computer Use. You correct it when it goes wrong; you explain the reasoning when it's not obvious from the action alone.

"Open the Woolworths app. Click the chat icon. Tell Olive I want a refund for order WW1234567 — specifically the strawberries because they arrived mouldy. Cite section 6 of the CGA — Olive's escalation logic recognises statute references."

Best when the workflow has non-obvious decision points you want to teach explicitly.

Mode 2 — Autopilot (Claude attempts, you correct)

You give Claude the goal in one line. Claude figures out which app to open, how to navigate, what to type — all via Computer Use. You watch and correct in real time when it goes wrong.

"Get a refund for the spoiled strawberries in my last Woolworths order. Order number WW1234567. I have photos in ~/Downloads."

Best when you want to see what an agent would do unsupervised, and refine from there.

Why either mode works

• Claude actually does the task. The SKILL.md you draft afterward is grounded in real screenshots and real clicks — not abstracted description. Tacit knowledge ("wait two seconds after submit before checking the result") gets captured because Claude lived it.
• Refusal moments come up naturally.When you say "no, don't click that — that would be impersonating someone" while correcting Claude, that moment becomes a refusal rule in SKILL.md.
• It's symmetric.The skill is authored by the same kind of agent that will execute it later. The model writing the runbook understands what it can and can't do at runtime, so the runbook doesn't ask the impossible.

The shortest path: install the skill-creator skill

We ship a meta-skill that packages all of this. Install it once and Claude walks you through scope → supervised execution → drafting → validation for any new skill you want to build:

curl -fsSL https://localskills.ai/api/install/claude-code/global/skill-creator \
  -o /tmp/skill-creator.zip && \
  unzip -o /tmp/skill-creator.zip -d ~/.claude/skills/

Then in Claude: "Use skill-creator to help me build a skill for <your task>." See the skill page for the full install for other agents.

Tips for a good supervised-execution session

• Pick one specific task. "File my GST return" is a skill. "Help with my taxes" is a category.
• Run through the happy path first. Then go back and explain edge cases.
• Talk through refusals out loud."I wouldn't use this for change-of-mind refunds" → that's a refusal rule. Say it.
• Don't let Claude help you on the first pass.You're demonstrating, not collaborating. Computer Use can assist later — for now you're the source of truth.
• Scrub the draft before publishing. Search for your name, your IRD number, your email address. Computer Use captures everything on screen; you decide what to keep.

Path B — Lived-experience harvesting (no Computer Use needed)

You've done this task many times. You know it cold. You don't need to observe yourself doing it — you can just write the runbook from memory. This is how the Woolworths Refund Helper was authored.

1. Write the SKILL.md as if instructing a careful junior colleague. Step-by-step. Specific. Cite the statute or policy where it matters.
2. Write a worked example at the same time.If you can't write a worked example, you don't understand the task well enough to author a good skill yet.
3. List 3–5 refusal cases. What requests should the skill not handle? Change of mind? Anything moving money without confirmation? Anything that needs a human decision?
4. Test by reading it back as if you don't know the task. Anywhere you have to use outside knowledge to interpret a step, fix it.

Path C — From scratch

You have a written SOP, a policy document, or a help-centre article that's already authoritative. Distil it into SKILL.md.

• Keep what's decision-relevant. Cut what's decorative.
• Translate jargon to plain language.
• Note where the source document is wrong, ambiguous, or out-of-date — the skill should warn the user when it hits those.

Path D — Extract from an existing chat

You've already used Claude (or another agent) to help with this task ad-hoc. You found a prompt + response pattern that works. Convert it.

1. Open the chat. Find the system / context prompt you ended up with (or the running set of instructions that worked).
2. Ask the same agent: "Promote this conversation into a skill. Draft skill.json, SKILL.md, and a worked example. Be conservative on permissions."
3. Review carefully — agents writing their own runbooks tend to over-claim capability. Tighten.

The structure (all paths share this)

Six files. Five are required.

<your-slug>/
  skill.json       # manifest — required, validated
  README.md        # human-facing docs — required
  SKILL.md         # the runbook the agent runs — required
  LICENSE          # OSI-approved licence — required
  CHANGELOG.md     # version history — required
  examples/        # at least 2 worked examples — strongly recommended

The minimum viable structure is at _examples/minimal-skill in the skills repo. Copy that folder, rename it to your slug, and edit.

What goes in SKILL.md

Think of SKILL.md as a one-page runbook a careful agent would consult before doing the task. Standard sections:

• Operating rules— the contract the agent follows. Five to eight short rules. Always include: never contact services that aren't in permissions.network; never ask for credentials; refuse out-of-scope requests.
• Inputs you accept — what the user can hand in (receipts, screenshots, free-text descriptions, file paths).
• Step-by-step — the actual sequence, in the UI the user / agent will operate. Be specific about field names, button labels, success states.
• Output format — a fenced block showing exactly what the skill returns, with template placeholders the agent fills in.
• What you will not do — refusal cases. Specific. Be opinionated.
• Edge cases— situations the user might bring that look like the main case but aren't.
• Tone — how the skill should speak. "NZ-direct, factual, no marketing fluff." Two lines max.
• Self-check — three to five questions the agent should ask itself before outputting. Forces a final sanity pass.

Permissions — narrowest possible

The validator flags over-claimed permissions. The reviewer rejects them. The user inspects them on the skill page before installing. Be specific.

• network — exact hostnames the skill actually contacts. ["api.example.com"], not ["*"], not ["https://...path"].
• fileSystem — explicit scopes (read:downloads, write:outputs). Read from where the user's files actually live; write only where they'd expect output.
• shell — false if not needed (the strong preference). If yes, declare allowed commands as an array; never true.

Tone — the localskills voice

• Specific, not flowery. Dates, dollar amounts, route numbers, statute references.
• Plain language. Don't mimic the institution's register. Translate.
• Regional honesty. NZ English, NZ idioms only when natural. Same applies to other regions in their own register.
• No marketing. "Easy", "the best way to…", "save time on…" — out. The skill shows what it does; users decide.
• No threats. Statute references replace threats; never write "I'll take legal action" into a draft.
• Brevity. If the output is more than 250 words on the happy path, you're padding.

Testing before submission

1. Run the local validator:

   node scripts/validate.mjs <region>/<your-slug>

   It must pass (warnings are OK; errors block the PR).
2. Install your draft into Claude Code or Claude Desktop locally and run it against a realistic input. The skill detail page on this site has the install command per agent.
3. If you have Computer Use available, run the skill on a real (or sandbox) instance of the target UI. Catch the gaps between what you wrote and what the agent does.
4. Re-read your refusal cases. Try the obvious abuse paths (someone using the skill for fraud, harassment, scraping). Make sure the skill says no, specifically.

Common mistakes

• Over-scoping. Trying to cover four sub-tasks in one skill instead of shipping four small skills. Smaller is better.
• Under-specifying refusals.A skill with no refusal section will be used for things you didn't intend. Be explicit.
• Padded SKILL.md. If you can delete a paragraph without anyone noticing at runtime, delete it now.
• Permissions wider than needed. If the skill drafts a message and never sends it, network: []. The validator and the reviewer will flag wider scope.
• Confident statements about law / tax / consents. Cite the statute by section, but tell the user when something should go to a professional. The Woolworths skill cites s 6 CGA; it doesn't pretend to give legal advice.
• Including PII. No real IRD numbers, no real card numbers, no real customer names in examples. Use templates and obvious placeholders.

Submit

1. Fork localskills-ai/skills.
2. Drop your folder at <region>/<your-slug>/.
3. Run node scripts/validate.mjs <region>/<your-slug> locally.
4. Open a PR using the template. CI re-runs the validator.
5. Review feedback usually within 48 hours.

See /submit for the full flow and /moderation-policy for what gets rejected.

Worked walkthrough — a 30-minute skill

Concrete: you want to build a "Spark broadband bill checker" skill using dictation mode. Here's how it plays out in real time:

1. Set up two panes. Spark account portal on the right of your screen. Claude Desktop on the left, with Computer Use authorised.
2. Tell Claude the task."I want to build a skill for checking my Spark broadband bill for incorrect charges. Let's do it in dictation mode — I'll tell you each step, you execute via Computer Use, I'll correct you."
3. Dictate the steps."Sign in to my.spark.co.nz. Click 'Bills'. Open the latest bill PDF. Compare the data add-on line to last month's bill — I cancelled it but I think they're still charging." Claude executes each step.
4. Catch the comparison."I'm comparing line-by-line, not the total. The total might look normal because of seasonal usage; the line item is where the error hides." That becomes a step in SKILL.md.
5. Note the refusal moment.Claude offers to submit the dispute via the Spark contact form. You say "no — I want to verify it's actually wrong before disputing, and the dispute submission has to be reviewed by me each time." That's a refusal rule.
6. End the execution. Ask Claude to draft the full skill folder from what it just did.
7. Edit. Scrub your account number. Tighten the tone. Add the worked example you just walked through as examples/01-data-addon-overcharge.md.
8. Validate, open PR. Done. ~30 minutes from start to first draft.

Get help

• Read the docs index for the manifest schema reference.
• Read the moderation policy before publishing anything that touches money, government services, or personal data.
• Look at the Woolworths Refund Helper for the flagship example, and _examples/minimal-skill for the floor.