feat: mirror skill directories from upstream + add playwright-best-practices-for-agents

[stefanjudis]

What

Adds the playwright-best-practices-for-agents skill (SKILL.md + 23 references/ files) from checkly/docs, and reworks the sync so this and every other skill stays in lockstep with upstream automatically.

Why the sync changed

The skill ships a references/ directory of 23 files that will grow and change. The old per-file list in skills.config.ts didn't fit:

• additions upstream were silently missed,
• a removed file 404'd and broke the whole daily sync,
• removed files lingered locally forever (sync only ever wrote).

How it works now

scripts/sync.ts mirrors the entire source.path directory per skill:

• lists every file via the GitHub git-trees API (?recursive=1),
• wipes and rewrites skills/<name>/ so upstream deletions propagate,
• fails loudly on a truncated tree rather than mirror a partial skill,
• supports optional GITHUB_TOKEN auth (the workflow now passes the Actions token).

The per-file files key is gone — both skills now mirror directories. Both track main and sync daily, matching the existing behavior (the old docs said "synced on release", which was never true — fixed).

The formatter now ignores the whole skills/ tree: its contents are synced-verbatim or standalone docs, and this also stops a daily sync of new upstream files from tripping the pre-commit format check.

Notes for review

• The skills/checkly/ diff is real upstream drift the mirror picked up (new API pass-through section, investigate test-sessions, expanded description) — it would have landed on the next daily run regardless, not a hand edit.
• No plugin-manifest changes needed — skills are discovered by directory convention.

Test plan

• npm test — 8 tests (TDD, written failing first): directory enumeration, nested dirs, out-of-path filtering, stale-file deletion, ref pinning, auth header, truncation guard, both non-2xx paths
• npm run typecheck / npm run lint / npm run format:check clean
• npm run sync against live repos → 26 files (checkly: 2; playwright: SKILL.md + 23 references), matching upstream exactly

[Copilot]

Pull request overview

This PR adds the new playwright-best-practices-for-agents skill (mirrored from checkly/docs) and updates the skill sync mechanism so each skill mirrors its entire upstream directory (including nested references/), keeping local skills/<name>/ in lockstep with upstream.

Changes:

• Reworked scripts/sync.ts to enumerate files via the GitHub git-trees API, then wipe-and-rewrite skills/<name>/ on each sync (propagating upstream deletions).
• Added comprehensive sync tests covering directory mirroring, deletion of stale files, auth header usage, and truncated-tree/non-2xx failure modes.
• Added the Playwright skill + docs updates (sync workflow token, .prettierignore, README/CONTRIBUTING updates).

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/sync.test.ts	Adds tests for directory mirroring, deletion propagation, auth header, and error cases.
scripts/sync.ts	Implements git-tree enumeration + wipe-and-rewrite directory mirroring for skills.
skills.config.ts	Removes per-file lists and adds the new Playwright skill source directory.
.github/workflows/sync.yml	Passes GITHUB_TOKEN to the sync job for authenticated tree listing.
.prettierignore	Excludes the entire skills/ tree from formatting.
README.md	Updates the skills table and clarifies daily sync/tracking behavior.
CONTRIBUTING.md	Updates contributor guidance to match directory-mirroring sync behavior.
skills/playwright-best-practices-for-agents/SKILL.md	Adds the new Playwright best-practices skill definition and routing table.
skills/playwright-best-practices-for-agents/references/assertions.md	Reference doc for web-first assertions and retry semantics.
skills/playwright-best-practices-for-agents/references/auth.md	Reference doc for auth setup projects, storageState, SSO/2FA patterns.
skills/playwright-best-practices-for-agents/references/ci.md	Reference doc for CI setup, reporters, artifacts, sharding guidance.
skills/playwright-best-practices-for-agents/references/clock.md	Reference doc for deterministic time via page.clock.
skills/playwright-best-practices-for-agents/references/config.md	Reference doc for Playwright config baseline and project patterns.
skills/playwright-best-practices-for-agents/references/console-errors.md	Reference doc for gating on pageerror/console.error via fixtures.
skills/playwright-best-practices-for-agents/references/debugging.md	Reference doc for agent-friendly debugging flows and --debug=cli.
skills/playwright-best-practices-for-agents/references/error-states.md	Reference doc for testing offline/500/loading/retry flows via routing.
skills/playwright-best-practices-for-agents/references/files.md	Reference doc for upload/download patterns (setInputFiles, download events).
skills/playwright-best-practices-for-agents/references/flakiness.md	Reference doc for flake root causes, retries, parallelism, isolation.
skills/playwright-best-practices-for-agents/references/forms.md	Reference doc for form interaction and validation assertions.
skills/playwright-best-practices-for-agents/references/global-setup.md	Reference doc comparing globalSetup vs setup projects.
skills/playwright-best-practices-for-agents/references/iframes.md	Reference doc for frameLocator / contentFrame() patterns.
skills/playwright-best-practices-for-agents/references/interactions.md	Reference doc for keyboard/mouse/dialog handling (plus cleanup needed).
skills/playwright-best-practices-for-agents/references/locators.md	Reference doc for locator priority ladder and strict-mode narrowing.
skills/playwright-best-practices-for-agents/references/mobile.md	Reference doc for device emulation, touch, viewport, permissions.
skills/playwright-best-practices-for-agents/references/multi-context.md	Reference doc for popups vs new contexts and multi-user testing.
skills/playwright-best-practices-for-agents/references/network.md	Reference doc for routing, mocks, HAR replay, APIRequestContext usage.
skills/playwright-best-practices-for-agents/references/tags-annotations.md	Reference doc for annotations/tags, test.only, --grep usage.
skills/playwright-best-practices-for-agents/references/test-data.md	Reference doc for unique test data, factories, API seeding/teardown.
skills/playwright-best-practices-for-agents/references/test-structure.md	Reference doc for fixtures, POM, and test-step structuring.
skills/playwright-best-practices-for-agents/references/visual.md	Reference doc for screenshots, aria snapshots, and baseline stability.
skills/playwright-best-practices-for-agents/references/waiting.md	Reference doc for avoiding hard waits and using explicit waits correctly.

Comments suppressed due to low confidence (1)

scripts/sync.ts:146

• file values come from the upstream git tree. It’s worth defensively rejecting absolute paths, Windows separators, or .. segments before using join(skillDir, file) so a malformed tree entry can’t write outside skills/<name>/.

    for (const file of files) {
      const url = buildRawUrl({
        repo: skill.source.repo,
        ref: skill.source.ref,
        path: skill.source.path,
        file,
      });
      const res = await fetchImpl(url);
      if (!res.ok) {
        throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
      }
      const body = await res.text();
      const dest = join(skillDir, file);
      await mkdir(dirname(dest), { recursive: true });

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.