What Are Agent Skills?.

What they are

An Agent Skill is a self-contained package of instructions for an AI coding agent. You put a SKILL.md file (plus any supporting scripts, references, or templates) into a directory, place that directory somewhere your agent can find it, and the agent knows how to use it — autonomously deciding when the skill applies and loading only what it needs.

The core insight is that agents should not need a new system prompt for every task. Instead of re-explaining “how to write a Playwright test” every conversation, you write it once in a skill and the agent recalls it whenever the task matches.

Skills are version-controlled, shareable across a team, composable with each other, and — because they follow an open standard — portable across Claude Code, OpenAI Codex, GitHub Copilot, Cursor, and other compatible agents.

Skill folder anatomy

A skill is a directory. The only required file is SKILL.md. Everything else is optional and loaded on demand:

my-skill/
├── SKILL.md            ← required: frontmatter + instruction body
├── scripts/            ← optional: shell/Python helpers the agent can run
│   └── run-tests.sh
├── references/         ← optional: docs, specs, style guides the agent reads
│   └── playwright-conventions.md
├── templates/          ← optional: output templates (test file skeletons, etc.)
│   └── test-template.ts
├── examples/           ← optional: worked examples the agent can cite
│   └── example-test.spec.ts
└── assets/             ← optional: any other supporting files

Skills live in a well-known location that your agent scans on startup. The exact folder path varies by tool — see per-tool locations.

SKILL.md anatomy

A SKILL.md file is a Markdown file with a YAML frontmatter block. The frontmatter provides machine-readable metadata; the Markdown body provides the instructions the agent follows when the skill is active.

---
name: playwright-test-generator
description: |
  Generates Playwright TypeScript tests from a feature description, acceptance
  criteria, or user story. Use when asked to write, scaffold, or generate
  end-to-end tests using Playwright. Do NOT use for unit tests, API tests,
  or non-Playwright frameworks.
version: "1.0.0"
metadata:
  author: QA Team
  tags: [playwright, e2e, test-generation]
---

## When to use
- User provides a feature description, AC, or user story and asks for tests
- User asks to "write a Playwright test" or "generate e2e coverage"

## Inputs
- Feature description or acceptance criteria
- URL or route under test (if known)
- Auth state (logged-in / logged-out), if relevant

## Instructions
1. Identify the happy path and the top 3 edge cases from the provided spec.
2. Scaffold a `*.spec.ts` file using the Page Object Model pattern.
3. Use `@playwright/test`; import from `../fixtures` if a fixtures file exists.
4. Include assertions for both visible UI state and network responses where relevant.
5. Add a comment above each test block explaining what it covers.

## Output format
Return the full `*.spec.ts` file. After the code block, list any assumptions
you made and flag any AC ambiguities.

## Anti-patterns
- Do not use `page.waitForTimeout()` — use auto-waiting assertions instead.
- Do not hard-code test data; use variables or fixtures.

Progressive disclosure: how an agent uses a skill

Skills are designed for efficiency. An agent does not load every skill's full content on startup — it uses a three-stage loading model called progressive disclosure:

1. 1
   Discovery — at startup, the agent scans the skills folder and reads only the name and description fields from every SKILL.md. This is cheap — a few lines per skill.
2. 2
   Activation — when the user's request matches a skill's description, the agent loads the full SKILL.md body (instructions, when-to-use, output format, anti-patterns, etc.) into context. Only the matched skill is loaded.
3. 3
   Execution — as the agent works through the instructions, it loads referenced files from references/, templates/, or examples/ on demand, and runs scripts from scripts/ if needed. Only what is actually required gets loaded.

This is why the description field is the most important part of your SKILL.md. The agent decides whether to use your skill based on the description alone — before it reads anything else. A vague description means missed activations; an overreaching one means false positives. See writing a good description.

Skills vs prompts

Prompts and Agent Skills solve related but different problems:

They are complementary. Use the AI Prompt Library for one-off queries; use skills to package your best prompts into a repeatable, version-controlled workflow.

Skills vs tools, plugins, and MCP servers

It is easy to confuse Agent Skills with other agent extension mechanisms. Here is the key distinction:

Skills teach the agent how to think about a task. Tools give the agent new capabilities it can call. They complement each other: a skill can instruct the agent to call a specific tool, and a tool can be referenced from a skill's scripts/ directory.

Why Agent Skills matter for QA engineers

QA work is highly repeatable but highly contextual. Every project has the same shapes of work — write tests, review PRs, generate test data, triage failures — but the specifics differ (tech stack, naming conventions, risk tolerance, test pyramid, CI setup). That combination is exactly what skills are designed for.

• Write your Playwright conventions once — stop repeating them in every prompt.
• Share the same skill across your whole QA team — consistent output, consistent style.
• Version-control your testing standards alongside your tests.
• Compose skills — use a test-generation skill alongside a bug-report skill in the same session.
• Onboard new engineers faster — skills encode the team's QA expertise as discoverable, readable files.
• Carry your skills across Claude Code, Codex, Copilot, and Cursor without rewriting anything (with per-tool verification).