stablyai/agent-skills

Overview

This skill provides AI rules and an SDK reference for writing Playwright tests with the Stably Playwright SDK. It guides when to use Stably AI methods versus raw Playwright, and documents aiAssert, agent.act(), page.extract(), page.getLocatorsByAI(), and email Inbox testing. Use it to improve test reliability for visual, dynamic, or email-driven flows.

How this skill works

The skill explains available API primitives and their signatures, how to pick models, and how to combine Playwright code with Stably AI features. It covers AI assertions (aiAssert) for visual intent checks, AI extraction for structured data from pages or emails, accessibility-driven locator finding, autonomous agent workflows via agent.act(), and disposable inboxes for email verification flows.

When to use it

• When an assertion is visual or intent-based and Playwright selectors are brittle—use aiAssert.
• When extracting structured data from rendered content or emails—use page.extract or inbox.extractFromEmail with optional Zod schemas.
• When elements are hard to target with CSS/XPath but have accessible labels—use page.getLocatorsByAI.
• When operations require canvas interactions, coordinate-based clicks, or highly dynamic decision making—use agent.act().
• When verifying OTPs, magic links, or confirmation emails—use @stablyai/email Inbox.

Best practices

• Prioritize test stability: prefer Playwright for deterministic actions and use Stably SDK only when necessary.
• Keep AI prompts self-contained and explicit; never rely on implicit previous state.
• Scope visual assertions with locators where possible and avoid fullPage screenshots unless required.
• Offload calculations, loops, and deterministic logic to Playwright code; reserve agent.act() for human-like decisions.
• Check getLocatorsByAI count before interacting and prefer accessible properties (labels, roles, text) in prompts.
• Use Zod schemas for reliable typed extraction from pages and emails.

Example use cases

• Assert that a dashboard card and trend chart are present with aiAssert scoped to specific locators.
• Extract invoice details (amount, date, invoice ID) from a rendered invoice using page.extract with a Zod schema.
• Find and click a hard-to-select login button using page.getLocatorsByAI and verify count === 1.
• Use agent.act() to complete a multi-step, canvas-driven workflow that Playwright selectors cannot express reliably.
• Create an Inbox to receive a verification email, waitForEmail, then extract the OTP or magic link with inbox.extractFromEmail.