What Is SKILL.md? Building a Reusable Playwright Testing Skill for Claude Code

Part 4 (final) of the "Automating Playwright with Claude Code" series. If you're just joining, start with Part 1: Getting Started with Claude Code and Playwright CLI, then Part 2: CLI vs MCP and Part 3: Token-Saving Habits.

Across this series, we've set up Playwright CLI, compared it against MCP, and covered habits for keeping Claude Code sessions token-efficient. One idea kept coming up: pushing repeatable steps into a Skill instead of re-explaining them every session. This final post shows exactly what that means — what SKILL.md is, how to write one, and a full working example you can drop straight into your own project.

Why Skills Matter for Test Automation

• Consistency across the team. Once a Skill is committed to your repo, every teammate gets the same testing conventions automatically — no more "well, I usually test forms by..." tribal knowledge.
• Context stays lean. A Skill's instructions only load when Claude actually decides they're relevant — unlike a CLAUDE.md file, which is always present in every session.
• Token-efficient by design. Skills can bundle scripts and reference files that Claude only reads on demand, keeping routine work cheap even across many sessions.
• Portable and shareable. It's an open markdown-based format, so the same Skill folder works across projects and, increasingly, across other agent tools too.
• No new syntax to memorize. You don't need to remember a slash command — Claude recognizes when a Skill applies based on your plain-language request.

Prerequisites

• Claude Code installed (see Part 1).
• Playwright CLI installed, ideally with playwright-cli install --skills already run.
• A project you're comfortable committing a .claude/skills/ folder into.

Table of Contents

1. What Is SKILL.md?
2. Anatomy of a Skill File
3. Step-by-Step: Building a Playwright Form-Testing Skill
4. Testing That Your Skill Actually Fires
5. Where to Put Skills: Project vs Personal
6. Advantages of Using Skills, Recap
7. Conclusion

Step 1: What Is SKILL.md?

A Skill in Claude Code is a folder — typically containing a SKILL.md file — that packages instructions Claude loads only when it's relevant to the task at hand, rather than sitting in context for every single session:

.claude/skills/
└── playwright-form-tester/
    └── SKILL.md

Think of it as documentation written specifically for Claude to read at the right moment: not a static reference you consult, but a file Claude actively decides to pull into its own context based on what you ask.

Step 2: Anatomy of a Skill File

Every SKILL.md has two parts:

---
name: skill-name-here
description: "A clear description of what this does and when to use it."
---

# Skill instructions in markdown go here.

• YAML frontmatter — name and description. The description is the most important field in the entire file: Claude reads every installed Skill's description at session start to decide which one(s) to load for a given request. Vague descriptions mean the Skill just won't fire.
• Markdown body — the actual process, conventions, or knowledge you want followed once the Skill is triggered. Plain instructions, same as you'd give a new team member.

Step 3: Building a Playwright Form-Testing Skill

Let's build a real one — a Skill that teaches Claude your team's standard approach to testing any form using Playwright CLI (the tool from Parts 1–2 of this series).

---
name: playwright-form-tester
description: Test HTML forms using Playwright CLI. Use this whenever the user
  asks to test, validate, or verify a form (login, signup, checkout, contact,
  etc.) on a web page, or mentions form submission, validation errors, or
  success messages.
---

# Playwright form tester

## When to use this
Any time a form needs to be exercised end-to-end: filling fields, submitting,
and checking the result (success message, redirect, or validation error).

## Process
1. Navigate to the target page with `playwright-cli navigate <url>`.
2. Run `playwright-cli snapshot` to get element references (e.g. `e12`).
3. Fill each field with `playwright-cli fill <ref> "<value>"`.
4. For negative test cases, submit with at least one required field empty
   and confirm a validation message appears — check for the presence of
   the specific error text, not just the absence of errors.
5. Submit the form and re-run `playwright-cli snapshot` to confirm the
   expected end state (success message, redirect URL, or error banner).
6. Report pass/fail clearly, quoting the exact text found on the page.

## Notes
- Always test one valid case and at least one invalid case per form.
- If the form has a CAPTCHA or OTP step, stop and ask the user how to
  proceed rather than guessing.

Save this exactly as .claude/skills/playwright-form-tester/SKILL.md in your project.

Step 4: Testing That Your Skill Actually Fires

Skills load at session start, so:

1. Restart your Claude Code session (or start a new one) after adding the file.
2. Ask something that matches the description, e.g.:

Test the checkout form on staging.

1. Claude should recognize the match and follow your defined process — navigating, filling fields, checking both a valid and invalid case, and reporting results in the format you specified.

If it doesn't fire, double-check:

• The file is named exactly SKILL.md (case-sensitive on some systems).
• The frontmatter is valid YAML (watch for missing colons or bad indentation).
• The description field actually contains the trigger words someone would naturally use.

Step 5: Where to Put Skills — Project vs Personal

Location	Scope	Use for
.claude/skills/ in your repo	Project-only, shared with team via git	Testing conventions specific to this app
~/.claude/skills/	Personal, available across all your projects	Your own general-purpose habits (e.g. "always test one negative case")

Commit project-scoped Skills to version control so the whole team benefits the moment they pull the branch — no separate setup instructions needed.

Step 6: Advantages of Using Skills — Recap

• Keeps context lean by loading only when relevant, unlike an always-present CLAUDE.md.
• Makes testing conventions consistent across an entire team, automatically.
• Turns tribal knowledge ("we usually test forms this way") into a versioned, shareable artifact.
• Works alongside everything else in this series — pair it with Playwright CLI (Part 1–2) and the token-saving habits (Part 3) for genuinely efficient, repeatable test automation sessions.

Conclusion

That wraps up the series: Playwright CLI setup, how it compares to MCP, the everyday habits that keep sessions efficient, and now Skills — the piece that makes all of it repeatable and shareable across your team. If you build a Skill from this template, I'd love to see how you've adapted it for your own project's forms and flows.

Have you built a Skill of your own yet? Share what it does in the comments — and thanks for following along with the whole series!