Playwright 技能，适用于 Claude Code

作为 Claude 技能的通用浏览器自动化

这是一个 Claude 技能，使 Claude 能够即时编写并执行任何 Playwright 自动化任务——从简单的页面测试到复杂的多步骤流程。该技能以 Claude Code 插件 的形式打包，便于安装和分发。

Claude 会根据您的浏览器自动化需求自主决定何时使用此技能，仅加载完成特定任务所需的最少信息。

由 Claude Code 构建。

功能特性

• 任意自动化任务：Claude 会根据您的具体请求编写自定义代码，不限于预构建的脚本。
• 默认可见浏览器：通过 headless: false 实时查看自动化过程。
• 零模块解析错误：通用执行器确保正确访问所有模块。
• 渐进式披露：简洁的 SKILL.md 文件包含完整的 API 参考文档，仅在需要时加载。
• 安全清理：智能临时文件管理，避免竞态条件。
• 全面辅助工具：可选的常用任务实用函数。

安装

本仓库采用 Claude Code 插件 结构，包含一个技能。您可以将其作为 插件（推荐）安装，或提取为 独立技能。

结构说明

本仓库使用插件格式，具有嵌套结构：

playwright-skill/              # 插件根目录
├── .claude-plugin/           # 插件元数据
└── skills/
    └── playwright-skill/     # 实际技能
        └── SKILL.md

Claude Code 要求技能直接位于 .claude/skills/ 目录下，因此手动安装时需提取嵌套的技能文件夹。

---

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

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

# 将本仓库添加到市场
/plugin marketplace add lackeyjb/playwright-skill

# 安装插件
/plugin install playwright-skill@playwright-skill

# 进入技能目录并运行设置
cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
npm run setup

运行 /help 验证安装，确认技能已可用。

---

选项 2：独立技能安装

若要作为独立技能安装（不使用插件系统），只需提取技能文件夹：

全局安装（随处可用）：

# 克隆到临时位置
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# 仅将技能文件夹复制到全局技能目录
mkdir -p ~/.claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill ~/.claude/skills/

# 进入技能目录并运行设置
cd ~/.claude/skills/playwright-skill
npm run setup

# 清理临时文件
rm -rf /tmp/playwright-skill-temp

项目专用安装：

# 克隆到临时位置
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# 仅将技能文件夹复制到项目目录
mkdir -p .claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill .claude/skills/

# 进入技能目录并运行设置
cd .claude/skills/playwright-skill
npm run setup

# 清理临时文件
rm -rf /tmp/playwright-skill-temp

为何采用这种结构？ 插件格式要求使用 skills/ 目录来组织插件内的多个技能。当作为独立技能安装时，您只需内层的 skills/playwright-skill/ 文件夹内容即可。

---

选项 3：下载发布版本

1. 从 GitHub Releases 下载并解压最新发布版本。
2. 仅复制 skills/playwright-skill/ 文件夹至：
   • 全局：~/.claude/skills/playwright-skill
   • 项目：/path/to/your/project/.claude/skills/playwright-skill
3. 进入技能目录并运行设置：

   cd ~/.claude/skills/playwright-skill  # 或项目路径
   npm run setup
   

---

验证安装

运行 /help 确认技能已加载，然后让 Claude 执行一个简单的浏览器任务，例如“测试 google.com 是否加载”。

快速入门

安装完成后，只需让 Claude 测试或自动化任何浏览器任务。Claude 会编写自定义 Playwright 代码，执行并返回结果，附带截图和控制台输出。

使用示例

测试任意页面

“测试首页”
“检查联系表单是否正常工作”
“验证注册流程”

视觉测试

“分别截取移动端和桌面端的仪表盘截图”
“测试不同视口下的响应式设计”

交互测试

“填写注册表单并提交”
“点击浏览主导航”
“测试搜索功能”

验证测试

“检查是否有损坏的链接”
“验证所有图片是否加载”
“测试表单验证”

工作原理

1. 描述您想要测试或自动化的内容。
2. Claude 为该任务编写自定义 Playwright 代码。
3. 通用执行器（run.js）负责运行代码，并确保正确解析所有模块。
4. 浏览器打开（默认可见），自动化任务开始执行。
5. 最终结果显示控制台输出和截图。

配置

默认设置：

• 无头模式：false（浏览器默认可见，除非明确指定）
• 慢动作：100ms 以提高可见性。
• 超时时间：30秒。
• 截图：保存至 /tmp/。

项目结构

playwright-skill/
├── .claude-plugin/
│   ├── plugin.json          # 插件元数据，用于分发
│   └── marketplace.json     # 市场配置
├── skills/
│   └── playwright-skill/    # 实际技能（Claude 会发现它）
│       ├── SKILL.md         # Claude 读取的内容
│       ├── run.js           # 通用执行器（确保模块正确解析）
│       ├── package.json     # 依赖项及设置脚本
│       └── lib/
│           └── helpers.js   # 可选的实用函数
│       └── API_REFERENCE.md # 完整的 Playwright API 参考
├── README.md                # 当前文件——用户文档
├── CONTRIBUTING.md          # 贡献指南
└── LICENSE                  # MIT 许可证

高级用法

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

依赖项

• Node.js
• Playwright（通过 npm run setup 安装）
• Chromium（通过 npm run setup 安装）

故障排除

Playwright 未安装？ 导航到技能目录并运行 npm run setup。

出现“模块未找到”错误？ 确保自动化通过 run.js 运行，该文件负责处理模块解析。

浏览器未打开？ 请确认已设置 headless: false。默认情况下，技能会以可见模式运行浏览器，除非明确请求无头模式。

安装所有浏览器？ 在技能目录下运行 npm run install-all-browsers。

什么是技能？

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

此 Playwright 技能实现了 开放的 Agent Skills 规范，使其能够在不同的智能体平台上兼容。

贡献

我们欢迎您的贡献。请 fork 仓库，创建功能分支，进行更改，并提交 pull request。详情请参阅 CONTRIBUTING.md。

了解更多

• Agent Skills 规范 - 开放的智能体技能规范
• Claude Code 技能文档
• Claude Code 插件文档
• 插件市场
• API_REFERENCE.md - 完整的 Playwright 文档
• GitHub Issues

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

Playwright Skill 快速上手指南

Playwright Skill 是一个专为 Claude Code 设计的浏览器自动化技能。它允许 Claude 根据您的需求动态编写并执行 Playwright 代码，从简单的页面测试到复杂的多步骤流程均可胜任。默认情况下，浏览器将以可见模式运行，方便实时观察自动化过程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Node.js：已安装 Node.js (推荐 LTS 版本)
• Claude Code：已安装并配置好 Claude Code 客户端
• 网络环境：能够访问 GitHub 和 npm 仓库（如遇网络问题，建议配置国内镜像源）

提示：该工具在安装过程中会自动下载 Playwright 依赖及 Chromium 浏览器内核，首次运行可能需要少量时间。

安装步骤

您可以选择通过 插件系统（推荐，支持自动更新）或 独立技能 方式安装。

方式一：插件安装（推荐）

这是最简便的方式，适合大多数用户。

1. 添加市场源并安装插件 在 Claude Code 终端中依次执行以下命令：

   /plugin marketplace add lackeyjb/playwright-skill
   /plugin install playwright-skill@playwright-skill
   

2. 初始化环境 进入插件目录并运行设置脚本以安装 Playwright 依赖：

   cd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
   npm run setup
   

3. 验证安装 返回 Claude Code 主界面，输入 /help 确认技能已加载。

方式二：独立技能安装

如果您希望将技能全局部署或仅在特定项目中使用，可手动提取技能文件夹。

全局安装（对所有项目可用）

# 1. 克隆仓库到临时目录
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# 2. 创建技能目录并复制核心文件
mkdir -p ~/.claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill ~/.claude/skills/

# 3. 进入目录并初始化
cd ~/.claude/skills/playwright-skill
npm run setup

# 4. 清理临时文件
rm -rf /tmp/playwright-skill-temp

项目级安装（仅对当前项目可用）

# 1. 克隆仓库到临时目录
git clone https://github.com/lackeyjb/playwright-skill.git /tmp/playwright-skill-temp

# 2. 在当前项目下创建技能目录并复制
mkdir -p .claude/skills
cp -r /tmp/playwright-skill-temp/skills/playwright-skill .claude/skills/

# 3. 进入目录并初始化
cd .claude/skills/playwright-skill
npm run setup

# 4. 清理临时文件
rm -rf /tmp/playwright-skill-temp

基本使用

安装完成后，无需编写任何代码，直接用自然语言向 Claude 描述您的浏览器自动化需求即可。Claude 会自动调用该技能，生成 Playwright 代码，启动可见浏览器执行任务，并返回结果（包含截图和控制台输出）。

简单示例

示例 1：测试页面加载

测试 google.com 是否能正常加载

示例 2：表单交互测试

打开注册页面，填写用户名和密码，然后点击提交按钮，验证是否成功

示例 3：视觉测试

截取当前仪表盘页面在移动端和桌面端视图下的截图

示例 4：功能验证

检查首页是否存在失效链接，并验证所有图片是否都能正常加载

工作原理简述

1. 您描述任务（如“测试登录流程”）。
2. Claude 读取技能文档，动态编写定制的 Playwright 脚本。
3. 通过内置的执行器 (run.js) 运行脚本，确保模块解析无误。
4. 浏览器自动打开（默认非无头模式），执行操作。
5. 执行结果、日志及截图直接反馈给您。

注意：默认配置下浏览器会以可见模式运行（headless: false），并带有 100ms 的慢动作延迟以便观察。如需无头模式，可在指令中明确告知 Claude。