Turn a Python Script into a Skill

Almost every engineering team has a folder of internal Python scripts. You have a script that calculates monthly revenue recognition, one that validates sitemap XML files, and another that scrubs customer PII from database dumps.

These scripts are fast, deterministic, and accurate. But they often gather dust because nobody remembers the exact command-line arguments, which virtual environment to activate, or where the output file gets written. Turning a Python utility into a Claude skill gives it a natural-language interface while preserving its exact deterministic calculation.

Why wrap scripts instead of letting the model calculate

Large language models are probabilistic reasoning engines. They excel at language understanding, synthesis, and planning. They are noticeably less reliable at arithmetic, precise date math, and strict data hashing.

By pairing a Python script with a Claude skill, you get the best of both worlds: Claude interprets the user's natural-language request, formats the command arguments, executes the Python script to do the math, and presents the results clearly.

Directory layout for script-backed skills

Store the Python script directly inside the skill directory under a `scripts/` subfolder. This ensures that the code travels with the skill wherever it is installed.

The standard library dependency rule

In my experience building skills across dozens of teams, the most common operational failure is dependency drift. If `audit_headings.py` imports `beautifulsoup4` or `requests`, it will crash the moment someone runs it without the correct virtualenv activated.

Always prefer Python's standard library: `urllib.request`, `json`, `sys`, `re`, `html.parser`, and `sqlite3`. A script that uses only the standard library executes reliably on any machine with python3 installed.

Writing the SKILL.md orchestration prompt

Now write `SKILL.md` to instruct Claude when to trigger and how to execute the Python script:

---
name: seo-heading-audit
description: Use when auditing HTML pages for proper heading hierarchy and H1 tag compliance.
---

# SEO heading audit

When asked to audit headings on a page:
1. Identify the target HTML file path from the user request.
2. Execute the bundled python script:
   `python3 .claude/skills/seo-heading-audit/scripts/audit_headings.py <path>`
3. Parse the JSON response from stdout.
4. If h1_count is not exactly 1, report an SEO violation and explain why.