stablyai/agent-skills/stably-sdk-rules
Claude Code and agent skill by stablyai/agent-skills
- community
Checking that the SKILL.md file is still in the repository.
AI rules for writing tests with Stably Playwright SDK. Use this skill when writing or modifying Playwright tests with Stably AI features. Covers when to use Playwright vs Stably methods, plus minimal patterns for aiAssert, extract, getLocatorsByAI, agent.act, Inbox, and Google auth.
Install
npx vskill@latest install stablyai/agent-skills/stably-sdk-rulesSKILL.md
Stably SDK Rules
Quick Rules
- Prefer raw Playwright for deterministic actions/assertions (faster + cheaper).
- Prioritize reliability over cost when Playwright becomes brittle.
- Use
agent.act()for canvas, coordinate-based drag/click, or unstable multi-step flows. - Use
expect(...).aiAssert()for dynamic visual assertions; keep prompts specific. - Use
page.extract()/locator.extract()when you need visual-to-data extraction. - Use
page.getLocatorsByAI()when semantic selectors are hard with standard locators. - Use
Inboxfor OTP/magic-link/verification email flows. - All prompts must be self-contained; never rely on implicit previous context.
- Keep
agent.act()tasks small; do loops/calculations/conditionals in code. - Use
fullPage: trueonly if content outside viewport matters. - Always add
.describe("...")to locators for trace readability. - For email isolation, use unique
Inbox.build({ suffix })per test and clean up.
Setup (Single Block)
Optional: set API key programmatically.
Core Rules
- Locator rule: every locator interaction should use
.describe("..."). - Assertion choice:
- Use Playwright assertions first.
- Use
aiAssertfor dynamic/visual-heavy checks. - Interaction choice:
- Use Playwright for deterministic steps.
- Use
agent.actfor brittle or semantic tasks (especially canvas/coordinates). - Prompt quality:
- Include explicit target, intent, and constraints.
- Pass cross-step data through variables, not vague references.
Minimal Usage Patterns
aiAssert
Use fullPage: true only when assertion needs off-screen content.
extract
With schema:
getLocatorsByAI
Requires Playwright >= 1.54.1.
agent.act
Good pattern: compute values in code, then pass concrete values into the prompt.
Inbox (Email Isolation)
Install: npm install -D @stablyai/email. Requires STABLY_API_KEY and STABLY_PROJECT_ID env vars (or pass to Inbox.build()).
Inbox.build Options
| Option | Type | Description | |
|---|---|---|---|
suffix | string | Suffix for test isolation (e.g., "test-123" → "org+test-123@mail.stably.ai") | |
apiKey | string | Defaults to STABLY_API_KEY env var | |
projectId | string | Defaults to STABLY_PROJECT_ID env var |
Always use a unique suffix per test for parallel isolation. The inbox automatically filters out emails received before it was created.
waitForEmail
Throws EmailTimeoutError if no match arrives within the timeout.
extractFromEmail
Returns { data, reason }. Throws EmailExtractionError on failure.
Inbox Properties
| Property | Type | Description | ||
|---|---|---|---|---|
address | string | Full email address (with suffix if provided) | ||
suffix | string \ | undefined | The suffix passed to Inbox.build() | |
createdAt | Date | Inbox creation time; emails before this are auto-filtered |
listEmails
| Option | Type | Default | Description | ||
|---|---|---|---|---|---|
from | string | — | Filter by sender address | ||
subject | string | — | Filter by subject | ||
subjectMatch | 'contains' \ | 'exact' | 'contains' | Subject matching mode | |
limit | number | 20 | Max results (max: 100) | ||
cursor | string | — | Pagination cursor from previous nextCursor | ||
since | Date | — | Override the default creation-time filter | ||
includeOlder | boolean | false | Include emails received before inbox creation |
Other Methods
Email Object Properties
| Property | Type | Description | |
|---|---|---|---|
id | string | Unique identifier | |
mailbox | string | Container (e.g., "INBOX") | |
from | { address: string, name?: string } | Sender | |
to | { address: string, name?: string }[] | Recipients | |
subject | string | Subject line | |
receivedAt | Date | Arrival timestamp | |
text | string? | Plain text body | |
html | string[]? | HTML body parts |
Playwright Fixture Pattern
Finding Your Organization's Email Address
Your email address is visible in the Stably dashboard:
- Settings > Email Inbox: Displays the full address with a copy button
- In code:
inbox.addressafter callingInbox.build()returns your full address
The pattern is {org-name}@mail.stably.ai. If the user needs to allowlist, they should add mail.stably.ai to their email provider's allowlist.
Direct users to the dashboard Settings > Email Inbox to find their specific address.
Auth Flows (Google)
Use the helper instead of custom popup scripting:
Required env vars:
GOOGLE_AUTH_EMAILGOOGLE_AUTH_PASSWORDGOOGLE_AUTH_OTP_SECRET
Use a dedicated test Google account only.
Troubleshooting (Short)
aiAssertis slow/flaky: scope to a locator, tighten prompt, avoid unnecessaryfullPage: true.agent.actfails: split into smaller tasks, pass explicit constraints, raisemaxCyclesonly when needed.- Email timeout: verify subject/from filter and use unique inbox suffixes.
Full References
- Stably docs: https://docs.stably.ai
- SDK setup skill:
skills/stably-sdk-setup/SKILL.md - Package docs: https://www.npmjs.com/package/@stablyai/playwright-test
- Email package docs: https://www.npmjs.com/package/@stablyai/email
- Local overview:
skills/stably-sdk-rules/README.md
Security
- Security scanPassed, 92 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/stably-sdk-rules/SKILL.md
Popularity
- Repository stars
- 6
- Repository forks
- 2
- 7-day trend score
- 10
Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 10 May 2026, 6 months ago.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/stablyai/agent-skills/stably-sdk-rules)