Checkly

View saved version →

---
name: checkly
description: Set up, create, test and manage monitoring checks using the Checkly CLI. Use when working with API Checks, Browser Checks, URL Monitors, ICMP Monitors, Playwright Check Suites, Heartbeat Monitors, Alert Channels, Dashboards, or Status Pages. Access Checkly account plan, entitlements, feature limits, members, and pending invites. Includes generic API pass-through (`checkly api`) for endpoints without dedicated commands.
allowed-tools: Bash(npx checkly:*), Bash(npm install:*)
metadata:
  author: checkly
---

# Checkly

## CLI or MCP? Establish your path first

This skill drives the `npx checkly` CLI in a shell. The Checkly MCP server covers a subset — live account work: check status and results, test sessions, root cause analyses (RCA), triggering existing checks, and incidents. Only the CLI can author, test, and deploy Monitoring as Code.

Before your first command that talks to the Checkly API, establish your path:

1. **No shell access** (chat-only session): stop following this skill and use the Checkly MCP tools if they're connected; if not, tell the user you need either a shell or the Checkly MCP server to work with Checkly.
2. **Shell access**: run `npx checkly whoami` once.
   - **Succeeds** → use the CLI for everything and keep following this skill, even when Checkly MCP tools are also connected.
   - **Fails with an auth error, or prints an `action_required` login line** (not logged in) → route by task:
     - *Authoring, testing, or deploying checks*: MCP cannot do this. Log in through the CLI yourself (see "Logging in as an agent" below), or, when the user prefers keys, ask for `CHECKLY_API_KEY` + `CHECKLY_ACCOUNT_ID` in the environment or `.env`. Then re-run `whoami`. Don't work around a missing login.
     - *Live account work* (status, results, test sessions, RCA, triggering, incidents): fall back to the Checkly MCP tools if they're connected; ignore the login code. Call the MCP `whoami` tool first and tell the user which account you're operating on. If MCP isn't connected either, ask the user to authenticate the CLI as above.

Two rules that survive any fallback:

- **Account parity.** CLI auth and the MCP session can point at different accounts — users often belong to several. Never mix CLI and MCP results in one task without confirming both use the same account ID, and always name the account after a fallback.
- **Writes still need confirmation.** The CLI's confirmation protocol (below) does not travel with you to MCP. If you fall back for a write action (e.g. creating an incident), present the intended change and get the user's approval before calling the tool.

## Logging in as an agent

`npx checkly login` needs no terminal, and any command that requires authentication starts it for you when no credentials are stored, so you rarely run it by hand. It prints one JSON line and exits; when another command started it, the line goes to stderr. Relay what it says; never guess:

- `{"status":"action_required","reason":"login_required","verification_uri_complete":…,"user_code":…,"expires_in":…}` — a human must approve. Give the user the URL and the code (valid for `expires_in` seconds). Users without a Checkly account can sign up on the same page. Then, without waiting for the user to say they are done, run the first `next` command (`npx checkly login --wait`): it returns once they have approved, with the line below. Run it in the background: it can wait up to `expires_in` seconds, often longer than your shell's command timeout. If it is stopped before the user approves, run it again; the same code stays valid. (When another command started the login, run that command again afterwards, as the second `next` entry says.) A run without `--wait` before the approval shows the code again (or a new one when the old one is about to expire); always relay the latest `user_code`. Until the login is done, don't run several Checkly commands in parallel.
  - If the line has a `verification_uri` but n

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: playwright-best-practices-for-agents
description: "Agent-first best practices for writing, structuring, debugging, and stabilizing Playwright tests in TypeScript/JavaScript, built around Playwright's agent CLI (`playwright-cli`) and no-GUI agentic debugging flows. Use when authoring or reviewing Playwright tests: choosing locators, writing web-first assertions, fixing flaky tests, handling authentication (SSO/2FA), mocking network/API requests, structuring projects and fixtures, generating test data, building forms and validation, pressing keys and keyboard shortcuts, hovering and other mouse actions, handling native alert/confirm/prompt dialogs, uploading or downloading files, testing iframes, multiple tabs/popups or multi-user flows, mobile and device emulation, mocking time and dates, visual regression and screenshots, tagging and annotating tests, catching console errors, testing error/offline/loading states, configuring global setup, or running Playwright in CI."
metadata:
  author: checkly
---

# Playwright best practices

Condensed, opinionated guidance for writing Playwright tests that are **readable, isolated, and resilient** — built for coding **agents**, around Playwright's **agent CLI** (`playwright-cli`) and its no-GUI debugging flows. Maintained by [Checkly](https://www.checklyhq.com/?utm_source=ai-skill) — the same practices apply whether you run these tests in CI or as production monitors.

Load a reference file from `references/` only when the task needs it (see routing table). Each reference ends with links to the full `/learn` articles for depth.

> **Scope:** all guidance assumes the **`@playwright/test`** test runner with **TypeScript** — its `test`, fixtures, projects, config, and web-first `expect`. Examples are TypeScript (`.spec.ts`); the same APIs work in JavaScript. It does not target the standalone `playwright` automation library (which has no test runner, fixtures, or auto-retrying assertions). Imports are `import { test, expect } from '@playwright/test'`.

> **The agent CLI is what makes this skill shine.** Playwright's **agent CLI** — `playwright-cli`, package `@playwright/cli` — is a separate, token-efficient, **no-GUI** browser you drive command by command to discover locators and step through failing tests. It's distinct from the standard `npx playwright` CLI, and the **Agentic workflow** below leans on it throughout. → [references/debugging.md](references/debugging.md)

## Core rules (always apply)

1. **Locator priority:** prefer user-facing locators — `getByRole` > `getByLabel` / `getByPlaceholder` / `getByText` > `getByTestId` > CSS/XPath. CSS/XPath tie tests to implementation and break easily. → [references/locators.md](references/locators.md)
2. **Web-first assertions:** use auto-retrying `expect(locator).toBeVisible()` / `toHaveText()` etc. Never assert on a one-shot value you pulled out manually (`innerText()` then `toBe`). → [references/assertions.md](references/assertions.md)
3. **No hard waits:** never `waitForTimeout()`. Trust auto-waiting actions and web-first assertions; for explicit waits use `waitForURL` / `waitForLoadState` / `waitForResponse`. Avoid `networkidle`. → [references/waiting.md](references/waiting.md)
4. **Isolated & independent:** each test sets up its own state and can run in any order, in parallel. No test depends on another. Provision state via API in setup, not through the UI. → [references/test-structure.md](references/test-structure.md), [references/flakiness.md](references/flakiness.md)
5. **One feature per test:** if a test's assertions span more than one feature, split it. Keep tests short and focused.
6. **Reuse auth, don't re-login:** sign in once, persist `storageState`, reuse it across tests via a setup project. → [references/auth.md](references/auth.md)

## Routing table

| When the task is about… | Read |
|---|---|
| Picking selectors, strict mode, `data-testid` | [references/locators.md](references/locators.md) |
| Assertions, soft assert

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 24 — file references are metadata, not package contents.