Claude skills are the lowest-friction way to hand your Python scripts to an AI agent: you describe when the tool applies in one paragraph, point it at the script, and from then on the agent can find and run it without you repeating instructions. Trading-skill packs hitting GitHub Trending last week are one signal; the quieter signal is that a well-written skill turns "here's a repo, good luck" into "Claude, watch this product page and ping me when it drops below $40."

This post is the SKILL.md format explained with a real, working example — a price-drop watcher I use daily. Everything below is copy-pasteable.

The entire required format is two YAML fields

A skill is a folder. The only mandatory file is SKILL.md at its root:

price-watcher/ ├── SKILL.md ├── monitor.py ├── config.example.json └── README.md

And the only mandatory content in SKILL.md is frontmatter with name and description:

--- name: price-watcher description: "Watch product prices on any webpage, keep history in a CSV," and alert (email or Telegram) when a price hits a target or drops by a set percentage. Use when the user asks to track a product price, monitor for price drops, or build a price history. --- # Price Watcher  ## How to run a check 1. Collect from the user: product URL(s), a target price OR a drop percentage, and optionally a CSS selector for the price element. 2. Copy config.example.json to config.json and fill in urls and rules. 3. Run: python monitor.py --config config.json 4. Read the results table back to the user.

That's it. No manifest, no build step, no plugin registration.

Why the description matters more than the body

Skills load progressively: the agent keeps only the description line in context at all times, and pulls in the full SKILL.md body only when it decides the skill applies to the current request. Two consequences:

  1. The description is a router, not a summary. Write the phrasings a user would actually type. Compare:
  • Weak: description: A tool for monitoring websites.
  • Strong: description: Watch product prices ... Use when the user asks to track a product price, monitor for price drops, or build a price history.

The weak one fires on nothing. The strong one fires on "track this laptop price for me" — without the word "skill" appearing anywhere in the request.

  1. The body is read once, right before use. Put the procedure there: argument collection, exact commands, how to report results back. The example above tells Claude to ask for a target price before running anything, which is what makes it behave like a tool instead of a guess.

What goes in the script itself

Nothing exotic. monitor.py is a plain argparse script:

  • Fetch each configured URL once.
  • Find the price in order: user's CSS selector → og:price:amount / product:price:amount meta tags → JSON-LD offers.price.
  • Append to history.csv, compare against rules, fire a Telegram message on trigger.

(That extraction chain, with a regex fallback, is the subject of my previous post — Watching product pages for price drops with ~80 lines of Python.)

The skill wrapper adds zero dependencies: it's text describing an ordinary script.

Three mistakes that kill a skill

Vague description. Covered above — it's the #1 reason a skill silently never runs.

A novel instead of a procedure. The body gets loaded in full right before execution. Keep it under a page or two of imperative steps. Background essays belong in README.md, which the agent reads only if it chooses to.

Secrets in the folder. Skills get shared and installed by others. Ship config.example.json; keep real tokens in the user's own config.json, which is gitignored and never part of the package.

Packaging and distribution

Two line-level conventions make a skill installable anywhere:

# agentskills.io standard (works with Claude Code, OpenCode, and 50+ hosts) npx skills add <github-user>/<repo> # plain zip — most hosts accept a folder dropped into their skills directory zip -r price-watcher.skill price-watcher/

If you publish, add the SHA256 of the zip to your README. It costs one line and lets installers verify integrity — a convention the recently-trended trading-skill packs all follow.

The honest limits

Skills describe how to run a script; they don't make the script smarter. Price watching still means: HTML-embedded prices only (JavaScript-rendered stores without structured data won't work), and sites occasionally redesign their markup — updating one CSS selector is the whole maintenance cost. A good skill says this out loud in its body, so the agent can set expectations honestly.

This same watcher ships pre-packaged, together with a backtesting skill, in a $1 bundle at datafixtools.sell.app. It's priced at $1 on purpose while collecting the first honest reviews — if the content isn't useful, say so in the comments. The free skill folder above is complete on its own; the bundle only saves you the packaging steps.