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

• What Is SKILL.md?
• Anatomy of a Skill File
• Step-by-Step: Building a Playwright Form-Testing Skill
• Testing That Your Skill Actually Fires
• Where to Put Skills: Project vs Personal
• Advantages of Using Skills, Recap
• 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."
3. 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

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!