Claude Code Playwright Skill：轻量级浏览器自动化方案

通用浏览器自动化 Claude Skill

这是一个 Claude Skill，可让 Claude 编写并即时执行任何 Playwright 自动化 —— 从简单的页面测试到复杂的多步骤流程。打包为 Claude Code 插件，便于安装和分发。

Claude 根据你的浏览器自动化需求自主决定是否使用此 Skill，只加载特定任务所需的最少信息。

由 Claude Code 制作。

任何自动化任务 —— Claude 为你的特定需求编写自定义代码，不限于预构建脚本

默认可见浏览器 —— 使用 headless: false 实时查看自动化过程

零模块解析错误 —— 通用执行器确保正确的模块访问

渐进式信息披露 —— 简洁的 SKILL.md，完整 API 参考仅在需要时加载

安全清理 —— 无竞争条件的智能临时文件管理

全面的辅助函数 —— 常见任务的可选实用函数

此仓库采用 Claude Code 插件结构，包含一个 Skill。可以作为插件安装（推荐）或作为独立 Skill 提取。

了解结构

此仓库使用插件格式和嵌套结构：

playwright-skill/              # Plugin root
├── .claude-plugin/           # Plugin metadata
└── skills/
    └── playwright-skill/     # The actual skill
        └── SKILL.md

Claude Code 期望 Skill 直接位于 .claude/skills/ 下的文件夹中，因此手动安装需要提取嵌套的 Skill 文件夹。

选项 1：插件安装（推荐）

通过 Claude Code 的插件系统安装，自动获得更新和团队分发：

# Add this repository as a marketplace
/plugin marketplace add lackeyjb/playwright-skill

# Install the plugin
/plugin install playwright-skill@playwright-skill

# Navigate to the skill directory and run setup
cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
npm run setup

运行 /help 以验证 Skill 已加载。

选项 2：独立 Skill 安装

若要作为独立 Skill 安装（不使用插件系统），仅提取 Skill 文件夹：

全局安装（处处可用）：

# Clone to a temporary location
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# Copy only the skill folder to your global skills directory
mkdir -p ~/.claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill ~/.claude/skills/

# Navigate to the skill and run setup
cd ~/.claude/skills/playwright-skill
npm run setup

# Clean up temporary files
rm -rf /tmp/playwright-skill-temp

项目级安装：

# Clone to a temporary location
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# Copy only the skill folder to your project
mkdir -p .claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill .claude/skills/

# Navigate to the skill and run setup
cd .claude/skills/playwright-skill
npm run setup

# Clean up temporary files
rm -rf /tmp/playwright-skill-temp

为什么是这样的结构？插件格式需要 skills/ 目录来组织插件中的多个 Skill。作为独立 Skill 安装时，你只需要内层的 skills/playwright-skill/ 文件夹内容。

选项 3：下载 Release

从 GitHub Releases 下载并提取最新版本

仅将 skills/playwright-skill/ 文件夹复制到：

• 全局：~/.claude/skills/playwright-skill
• 项目：/path/to/your/project/.claude/skills/playwright-skill

导航至 Skill 目录并运行 setup：

cd ~/.claude/skills/playwright-skill  # or your project path
npm run setup

运行 /help 确认 Skill 已加载，然后要求 Claude 执行简单的浏览器任务，比如"测试 google.com 是否能加载"。

使用方法

安装后，只需要求 Claude 测试或自动化任何浏览器任务。Claude 将编写自定义 Playwright 代码、执行它，并返回包含截图和控制台输出的结果。

基础测试：

"Test the homepage"
"Check if the contact form works"
"Verify the signup flow"

响应式设计测试：

"Take screenshots of the dashboard in mobile and desktop"
"Test responsive design across different viewports"

交互测试：

"Fill out the registration form and submit it"
"Click through the main navigation"
"Test the search functionality"

验证测试：

"Check for broken links"
"Verify all images load"
"Test form validation"

工作流程

1. 描述你想要测试或自动化的内容

2. Claude 为该任务编写自定义 Playwright 代码

3. 通用执行器 (run.js) 运行它，带有正确的模块解析

4. 浏览器打开（默认可见）并执行自动化

5. 返回包含控制台输出和截图的结果

默认配置

• Headless: false（浏览器可见，除非明确请求 headless 模式）

• 慢动作：100ms，便于查看

• 截图：保存至 /tmp/

目录结构

playwright-skill/
├── .claude-plugin/
│   ├── plugin.json          # Plugin metadata for distribution
│   └── marketplace.json     # Marketplace configuration
├── skills/
│   └── playwright-skill/    # The actual skill (Claude discovers this)
│       ├── SKILL.md         # What Claude reads
│       ├── run.js           # Universal executor (proper module resolution)
│       ├── package.json     # Dependencies & setup scripts
│       └── lib/
│           └── helpers.js   # Optional utility functions
│       └── API_REFERENCE.md # Full Playwright API reference
├── README.md                # This file - user documentation
├── CONTRIBUTING.md          # Contribution guidelines
└── LICENSE                  # MIT License

Claude 在需要时会自动加载 API_REFERENCE.md，提供关于选择器、网络拦截、认证、视觉回归测试、移动设备仿真、性能测试和调试的全面文档。

要求

• Playwright（通过 npm run setup 安装）

• Chromium（通过 npm run setup 安装）

故障排查

Playwright 未安装？ 导航至 Skill 目录并运行 npm run setup。

模块未找到错误？ 确保自动化通过 run.js 运行，它会处理模块解析。

浏览器不打开？ 验证 headless: false 已设置。Skill 默认使用可见浏览器，除非明确请求 headless 模式。

安装所有浏览器？ 从 Skill 目录运行 npm run install-all-browsers。

关于 Agent Skills

Agent Skills 是指令、脚本和资源的文件夹，Agent 可以发现并使用它们来更准确和高效地完成任务。当你要求 Claude 测试网页或自动化浏览器交互时，Claude 发现此 Skill、加载必要的指令、执行自定义 Playwright 代码，并返回包含截图和控制台输出的结果。

此 Playwright Skill 实现了开放 Agent Skills 规范，使其在 Agent 平台中兼容。

贡献

欢迎贡献。Fork 仓库，创建特性分支，做出更改，并提交 pull request。详见 CONTRIBUTING.md。

相关资源

• Agent Skills 规范 —— Agent Skills 的开放规范

• Claude Code Skills 文档

• Claude Code 插件文档

• API_REFERENCE.md —— 完整的 Playwright 文档

• MIT License —— 详见 LICENSE 文件