agents-united 0.5.0

package/registry/skills/onboarding-cro/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: onboarding-cro
+description: Production-grade Onboarding Conversion Rate Optimization (CRO)
+  playbook for time-to-value (TTV) acceleration, activation milestone
+  gamification, and drop-off reduction.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: ✨
+disable-slash-command: true
+---
+
+# Product Onboarding CRO & Time-to-Value (TTV) Acceleration
+
+## Overview & Purpose
+The Onboarding CRO skill provides a production playbook for auditing, designing, and optimizing user onboarding flows in product-led growth (PLG) SaaS applications.
+
+Following this skill minimizes Time-to-Value (TTV), guides users directly to their first "Aha! moment", eliminates signup friction, implements progressive profiling, provides interactive checklists and empty-state guidance, and maximizes new user activation rates.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Low user activation rate (< 25% of signups achieving core product value milestone).
+- High drop-off during multi-step setup or configuration wizards.
+- Launching new self-serve product tiers or redesigned onboarding experiences.
+- User session recordings showing confusion during initial product workspace exploration.
+
+### Prerequisites
+- Analytics instrumentation tracking onboarding step completions (PostHog, Mixpanel, Segment).
+- Clearly defined user activation metric (e.g. "created 1 project and invited 1 team member").
+- UI component library supporting modal wizards, checklists, and empty state cards.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `activation_metric` | String | Yes | Exact definition of user activation milestone |
+| `current_funnel_steps`| Array<String> | Yes | Sequence of current onboarding steps |
+| `target_ttv_seconds` | Number | Optional | Target Time-to-Value ceiling in seconds (e.g. 180) |
+| `template_options` | Array<Object> | Optional | Starter templates pre-loaded for empty states |
+| `checklist_milestones`| Array<Object> | Yes | Gamified onboarding checklist items and rewards |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Onboarding CRO Spec | `docs/onboarding-cro/onboarding-spec.md` | Funnel architecture, checklist specs, TTV benchmarks |
+| Checklist Component | `src/components/onboarding/OnboardingChecklist.tsx` | Interactive progress tracker UI component |
+| Funnel Drop-off Report | `reports/onboarding-cro/funnel-analysis.json` | Drop-off rates and activation improvements by cohort |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Activation Milestone Definition & Funnel Drop-off Mapping
+1. Audit existing user signup-to-activation flow to identify the primary "Aha! moment".
+2. Measure baseline drop-off across all intermediate onboarding steps (Email verification, Persona survey, Team invite, Workspace setup).
+3. Identify friction points: defer non-essential profile questions to post-activation settings.
+4. Calculate baseline Time-to-Value (TTV) median duration from account creation to first core action.
+
+### Phase 2: Friction Reduction & Progressive Profiling UX Redesign
+1. Eliminate mandatory upfront credit card requirements and multi-field surveys.
+2. Implement 1-click social authentication (Google, GitHub, Apple) and magic link sign-in.
+3. Replace blank modal forms with sensible smart defaults and pre-selected common use cases.
+4. Implement progressive profiling: prompt for team size and advanced permissions only when triggering collaborative features.
+
+### Phase 3: Interactive Checklist & Micro-Commitment Component Implementation
+1. Construct persistent, collapsible onboarding checklist widget pinned to product dashboard.
+2. Structure checklist with 3-5 high-impact micro-commitments:
+   - Step 1: Select starter template (instant gratification, 30 seconds).
+   - Step 2: Run first execution / create first asset (core value, 60 seconds).
+   - Step 3: Invite team collaborator or share link (network effect hook).
+3. Attach visual progress bars and celebratory micro-animations (confetti, badge unlock) on completion.
+
+### Phase 4: Empty State & Template Pre-Population Architecture
+1. Audit all product dashboards to replace empty blank slates with interactive sample data.
+2. Provide 1-click "Clone Starter Project" buttons pre-populating fully functional templates.
+3. Embed contextual tooltips and in-line helper microcopy guiding the user's next logical click.
+4. Ensure empty states contain clear primary CTA buttons directing back to core activation path.
+
+### Phase 5: A/B Testing, Heatmap Session Auditing & Cohort Activation Tracking
+1. Deploy onboarding redesign as an A/B experiment against legacy control flow.
+2. Track key funnel telemetry events: `onboarding_started`, `step_completed`, `checklist_opened`, `activated`.
+3. Review session recordings of dropped-off users to isolate unhandled edge cases or confusion points.
+4. Compile final optimization report at `reports/onboarding-cro/funnel-analysis.json`.
+5. Commit onboarding components to repository.
+   ```bash
+   git add src/components/onboarding/ docs/onboarding-cro/
+   git commit -m "feat(onboarding-cro): implement interactive onboarding checklist and empty states"
+   ```
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Onboarding Flow State Machine Configuration
+```json
+{
+  "version": "2.0.0",
+  "flowId": "plg-saas-activation-v2",
+  "targetTtvSeconds": 120,
+  "milestones": [
+    {
+      "id": "step-1-template-select",
+      "title": "Choose your starter workspace",
+      "estimatedDurationSeconds": 15,
+      "isRequired": true,
+      "eventTrigger": "workspace_template_selected"
+    },
+    {
+      "id": "step-2-first-run",
+      "title": "Execute your first workflow",
+      "estimatedDurationSeconds": 45,
+      "isRequired": true,
+      "eventTrigger": "first_workflow_executed"
+    },
+    {
+      "id": "step-3-team-invite",
+      "title": "Invite a teammate",
+      "estimatedDurationSeconds": 30,
+      "isRequired": false,
+      "eventTrigger": "team_invitation_sent"
+    }
+  ]
+}
+```
+
+### Exemplar 2: TypeScript React Onboarding Checklist Component
+```typescript
+import React, { useState } from 'react';
+
+export interface MilestoneItem {
+  id: string;
+  title: string;
+  completed: boolean;
+  actionUrl: string;
+}
+
+export function OnboardingChecklist({ initialItems }: { initialItems: MilestoneItem[] }): React.JSX.Element {
+  const [items, setItems] = useState(initialItems);
+  const completedCount = items.filter(i => i.completed).length;
+  const progressPercent = Math.round((completedCount / items.length) * 100);
+
+  return (
+    <div className="onboarding-card border rounded-lg p-4 bg-white shadow-sm">
+      <div className="flex justify-between items-center mb-2">
+        <h3 className="text-sm font-semibold">Getting Started ({completedCount}/{items.length})</h3>
+        <span className="text-xs text-blue-600 font-bold">{progressPercent}%</span>
+      </div>
+      <div className="w-full bg-gray-200 h-2 rounded-full mb-4">
+        <div className="bg-blue-600 h-2 rounded-full transition-all duration-300" style={{ width: `${progressPercent}%` }} />
+      </div>
+      <ul className="space-y-2">
+        {items.map(item => (
+          <li key={item.id} className="flex items-center text-sm gap-2">
+            <input type="checkbox" checked={item.completed} readOnly className="rounded text-blue-600" />
+            <span className={item.completed ? 'line-through text-gray-400' : 'text-gray-800'}>{item.title}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: User Closes Onboarding Wizard Prematurely
+1. **Diagnosis**: User dismisses initial modal wizard without completing core activation steps.
+2. **Recovery Protocol**:
+   - Step 1: Persist incomplete checklist state to user profile database and browser localStorage.
+   - Step 2: Render non-intrusive floating checklist widget in bottom-right corner of main workspace.
+   - Step 3: Trigger contextual in-app reminder banner when user accesses dashboard with zero projects.
+
+### Scenario B: Team Invitation Failure During Onboarding Step
+1. **Diagnosis**: Email invite fails due to rate limits or invalid teammate email formatting, blocking wizard progression.
+2. **Recovery Protocol**:
+   - Step 1: Make team invitation step strictly non-blocking with an explicit "Skip for now" link.
+   - Step 2: Display inline error explaining the email issue without resetting previously entered workspace data.
+   - Step 3: Allow user to proceed directly into workspace and generate a shareable invite link instead.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Progressive profiling rules and Time-to-Value acceleration steps defined.
+- [ ] Interactive checklist component exemplar provided.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/paid-acquisition-ppc/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: paid-acquisition-ppc
+description: Production-grade Paid Acquisition PPC playbook for multi-channel ad
+  campaign structure, bidding algorithms, audience segmentation, UTM taxonomy,
+  and ad copy matrix.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 💰
+disable-slash-command: true
+---
+
+# Multi-Channel Paid Acquisition & PPC Campaign Management
+
+## Overview & Purpose
+The Paid Acquisition PPC skill provides an end-to-end framework for architecting, launching, and managing pay-per-click (PPC) campaigns across Google Ads (Search, Performance Max, Display), Meta Ads (Facebook & Instagram Feed, Reels, Stories), and LinkedIn Ads (Sponsored Content, Text, Message).
+
+Following this skill enforces strict campaign naming taxonomy, negative keyword management, audience segment exclusions, smart bidding optimization (tCPA, tROAS, Maximize Conversions), and multi-variant ad copy testing.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Launching new paid customer acquisition campaigns across search and social channels.
+- Restructuring underperforming ad accounts to improve Quality Score and reduce CPA.
+- Implementing standardized UTM tracking and conversion event tags.
+- Scaling budget while maintaining target ROAS and CAC efficiency thresholds.
+
+### Prerequisites
+- Active ad accounts (Google Ads, Meta Business Manager, LinkedIn Campaign Manager).
+- Configured conversion tracking tags (Google Tag Manager, Meta Pixel, LinkedIn Insight Tag).
+- Target customer personas, keyword research data, and approved ad copy/creative assets.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `channels` | Array<String> | Yes | Target channels: `['google', 'meta', 'linkedin']` |
+| `monthly_budget` | Number | Yes | Total monthly budget in USD |
+| `target_cpa` | Number | Yes | Target Cost Per Acquisition ceiling |
+| `target_roas` | Number | Optional | Target Return on Ad Spend multiplier (e.g. 3.5) |
+| `bidding_strategy` | String | Optional | Strategy: `tCPA`, `tROAS`, `MaximizeConversions`, `ManualCPC` |
+| `utm_campaign_name` | String | Yes | Canonical UTM campaign parameter string |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Campaign Architecture Spec | `docs/paid-acquisition-ppc/campaign-spec.md` | Full account hierarchy, match types, ad copy matrix |
+| Campaign Config JSON | `configs/ppc/campaign-matrix.json` | Programmatic campaign structure and budget splits |
+| Negative Keyword Lists | `configs/ppc/negative-keywords.txt` | Universal and campaign-level negative keyword filters |
+| Tracking URL Engine | `src/marketing/utm-builder.ts` | Programmatic UTM generator and URL validator |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Account Hierarchy Design & Funnel Intent Mapping
+1. Structure account hierarchy into Top-of-Funnel (TOF - Awareness/Problem Aware), Middle-of-Funnel (MOF - Solution Aware/Category Search), and Bottom-of-Funnel (BOF - Brand & High-Intent Purchase).
+2. Establish standardized campaign naming convention:
+   `[Dept]_[Channel]_[Objective]_[FunnelStage]_[Audience/KeywordTheme]_[Geo]_[Language]`
+3. Allocate budget across channels based on historical CAC and channel intent (e.g. 50% Google Search, 35% Meta Feed, 15% LinkedIn B2B).
+4. Establish budget pacing rules and daily spend caps to prevent front-loaded overspend.
+
+### Phase 2: Audience Segmentation, Keyword Sculpting & Negative Matching
+1. Segment audiences by intent: Custom Intent / In-Market, Lookalike / Retargeting, Customer CRM Match.
+2. Structure Google Ads Search Ad Groups using Single-Theme Ad Groups (STAGs) combining Exact Match (`[keyword]`) and Phrase Match (`"keyword"`).
+3. Build comprehensive universal negative keyword list (excluding terms like "free", "crack", "jobs", "internship", "salary", "login").
+4. Configure Meta Ads custom audience exclusions (exclude past 30-day converters, active paying subscribers, internal employees).
+
+### Phase 3: Ad Copy & Responsive Creative Matrix Generation
+1. Author Responsive Search Ads (RSAs) for Google Ads with 15 headlines and 4 descriptions:
+   - 3 Headlines with exact keyword insertion.
+   - 3 Value proposition and differentiation hooks.
+   - 3 Call-to-action hooks with urgency/proof.
+2. Author Meta & LinkedIn ad copy variations testing 3 primary text hooks against 2 creative angles.
+3. Configure sitelink extensions, callout extensions, structured snippets, and lead form assets.
+4. Verify compliance with advertising policies (no sensationalist claims, valid landing page URLs).
+
+### Phase 4: Bidding Algorithm Calibration & Conversion Tracking Setup
+1. Configure conversion goals in ad platforms with primary conversion actions (Purchase, Sign Up, Demo Request).
+2. Set up initial bidding strategy: Maximize Conversions with soft tCPA during 2-week learning phase (minimum 30 conversions).
+3. Transition to tROAS or strict tCPA once conversion volume exceeds 50 events per month per ad group.
+4. Validate conversion pixel fires and server-side tracking verification.
+
+### Phase 5: Campaign Launch, Budget Pacing & Dayparting Governance
+1. Upload campaign configurations via platform bulk sheets or API dispatchers.
+2. Enable dayparting / ad scheduling to concentrate spend during high-conversion business hours.
+3. Monitor real-time search terms report on days 1, 3, and 7 to immediately add newly discovered irrelevant queries to negative lists.
+4. Compile campaign setup summary at `docs/paid-acquisition-ppc/campaign-spec.md`.
+5. Commit campaign configuration files to git repository.
+   ```bash
+   git add configs/ppc/ docs/paid-acquisition-ppc/
+   git commit -m "feat(paid-acquisition-ppc): configure multi-channel PPC campaign architecture"
+   ```
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Multi-Channel PPC Campaign Matrix Specification
+```json
+{
+  "version": "2.0.0",
+  "campaigns": [
+    {
+      "id": "MKT_GGL_SEARCH_BOF_HIGHINTENT_US_EN",
+      "channel": "google-ads",
+      "network": "search",
+      "biddingStrategy": "tCPA",
+      "targetCpaUsd": 45.0,
+      "dailyBudgetUsd": 150.0,
+      "adGroups": [
+        {
+          "name": "Multi-Agent Frameworks",
+          "matchTypes": {
+            "exact": ["[multi agent framework]", "[ai agent registry]"],
+            "phrase": ["\"multi agent orchestration\"", "\"ai agent tools\""]
+          },
+          "rsaHeadlines": [
+            "Autonomous AI Agent Suite",
+            "Agents United - Dev Tools",
+            "Deploy AI Teams in Minutes"
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Exemplar 2: TypeScript UTM Tracking Parameter Engine
+```typescript
+export interface UtmParameters {
+  source: string;
+  medium: string;
+  campaign: string;
+  content?: string;
+  term?: string;
+}
+
+export function buildCampaignUrl(baseUrl: string, utm: UtmParameters): string {
+  const url = new URL(baseUrl);
+  url.searchParams.set('utm_source', utm.source.toLowerCase().trim());
+  url.searchParams.set('utm_medium', utm.medium.toLowerCase().trim());
+  url.searchParams.set('utm_campaign', utm.campaign.toLowerCase().trim());
+  if (utm.content) url.searchParams.set('utm_content', utm.content.toLowerCase().trim());
+  if (utm.term) url.searchParams.set('utm_term', utm.term.toLowerCase().trim());
+  return url.toString();
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Search Query Budget Bleed via Loose Broad Match Queries
+1. **Diagnosis**: High ad spend with low conversion rate caused by irrelevant broad search matches.
+2. **Recovery Protocol**:
+   - Step 1: Export Search Terms Report for the past 7 days.
+   - Step 2: Filter for queries with > 10 clicks and 0 conversions.
+   - Step 3: Add offending keywords as exact negative keywords in `configs/ppc/negative-keywords.txt` and sync to ad platform.
+
+### Scenario B: Ad Creative Policy Disapproval or Trademark Flag
+1. **Diagnosis**: Ad creative rejected by Google Ads or Meta for restricted keywords or trademarked brand names.
+2. **Recovery Protocol**:
+   - Step 1: Inspect platform rejection reason code in ad manager.
+   - Step 2: Update copy variations to replace flagged terms with approved descriptive synonyms.
+   - Step 3: Resubmit ad group for automated re-review.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Multi-channel campaign structures (Google, Meta, LinkedIn) detailed.
+- [ ] Negative keyword governance and UTM generation scripts included.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/performance-optimization/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: performance-optimization
+description: Production-grade Performance Optimization playbook for Core Web
+  Vitals, Node.js event-loop tuning, and caching layers.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: ⚡
+disable-slash-command: true
+---
+
+# Full-Stack Performance Profiling & Latency Optimization
+
+## Overview & Purpose
+The Full-Stack Performance Profiling & Latency Optimization skill provides a deterministic, battle-tested framework for executing performance-optimization processes across the Agents United multi-agent ecosystem.
+
+Following this skill ensures high quality, zero-regression execution, rigorous testing gates, and seamless cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request or workflow step invoking performance-optimization.
+- Auditing, implementing, or standardizing performance-optimization procedures.
+- Addressing technical debt, architectural reviews, or production readiness gates.
+- Preparing pull requests or automated release validations.
+
+### Prerequisites
+- Active project repository workspace with version control configured.
+- Operational testing, typechecking, and build toolchains.
+- Domain requirements, architectural constraints, or user stories defined.
+- Clean git working tree before beginning execution.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target module, service, component, or file path |
+| `config` | Object | Optional | Specific domain configurations, thresholds, and options |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts and reports |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation and high test coverage |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/performance-optimization/spec.md` | Full technical specification and architectural plan |
+| Implementation Files | `src/performance-optimization/*` | Production-ready source code, tests, and configurations |
+| Execution Report | `reports/performance-optimization/summary.json` | Verification metrics, test results, and audit summary |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Baseline Measurement & Bottleneck Profiling
+1. Establish rigorous baseline metrics before applying any optimizations (never guess).
+2. Profile frontend Core Web Vitals using Chrome DevTools, Lighthouse, and Web Vitals SDK.
+3. Profile backend Node.js workloads using Clinic.js (clinic doctor, clinic flame).
+4. Profile database query execution times and identify N+1 queries and full table scans.
+5. Document top 5 performance bottlenecks ranked by latency impact.
+
+### Phase 2: Frontend Asset & Rendering Optimization
+1. Optimize Largest Contentful Paint (LCP): inline critical CSS, preload hero image with fetchpriority="high".
+2. Eliminate Cumulative Layout Shift (CLS): reserve explicit dimensions on images and dynamic embeds.
+3. Optimize Interaction to Next Paint (INP): break long tasks (>50ms) using scheduler.yield().
+4. Implement route-based dynamic code splitting (React.lazy, dynamic import()).
+5. Compress images using modern AVIF / WebP formats and responsive srcset.
+
+### Phase 3: Backend Concurrency & Event Loop Optimization
+1. Eliminate synchronous blocking CPU operations in the Node.js main thread (offload to Worker Threads).
+2. Implement DataLoader batching for database queries to collapse N+1 queries into single IN (...) queries.
+3. Enable HTTP/2 and gzip/brotli compression on web server responses.
+4. Tune Node.js garbage collection parameters (--max-old-space-size, --v8-pool-size).
+5. Optimize memory allocations and eliminate object creation inside tight loops.
+
+### Phase 4: Multi-Tier Caching Architecture
+1. Configure HTTP Cache-Control headers: public, max-age=31536000, immutable for hashed assets.
+2. Implement Redis caching layer for expensive database queries with TTL and cache invalidation hooks.
+3. Deploy Edge CDN caching (Cloudflare / Fastly) with stale-while-revalidate policies.
+4. Implement browser local storage / IndexedDB caching for static client state.
+5. Verify cache hit ratio exceeds 90% under production-like traffic.
+
+### Phase 5: Benchmark Verification & Budget Enforcement
+1. Re-run automated Lighthouse and Clinic.js profiling against optimized code.
+2. Verify Core Web Vitals meet target thresholds: LCP < 2.5s, INP < 200ms, CLS < 0.1.
+3. Verify backend p99 latency meets target SLA.
+4. Configure bundle size limits in CI using bundlesize / size-limit.
+5. Publish performance benchmark comparison report.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: Full-Stack Performance Profiling & Latency Optimization Configuration & Specification
+```yaml
+// Redis tiered caching with stale-while-revalidate pattern
+export async function getCachedOrFetch<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+  ttlSeconds: number = 300
+): Promise<T> {
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached) as T;
+  const fresh = await fetcher();
+  await redis.setex(key, ttlSeconds, JSON.stringify(fresh));
+  return fresh;
+}
+```
+
+### Exemplar 2: Full-Stack Performance Profiling & Latency Optimization TypeScript Type Contract
+```typescript
+export interface PerformanceBudgets {
+  coreWebVitals: {
+    lcpMs: number; // < 2500ms
+    inpMs: number; // < 200ms
+    cls: number;   // < 0.1
+  };
+  backendSLO: {
+    p95LatencyMs: number; // < 100ms
+    p99LatencyMs: number; // < 250ms
+  };
+  bundleSizeKb: number;   // < 200kb gzipped
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in Full-Stack Performance Profiling & Latency Optimization
+1. **Diagnosis**: Static analysis, typechecking, or unit tests fail validation rules during execution.
+2. **Recovery Protocol**:
+   - Step 1: Inspect detailed error log output in test/build terminal.
+   - Step 2: Formulate targeted hypothesis and isolate failing line or assertion.
+   - Step 3: Implement surgical code fix and re-run verification suite.
+
+### Scenario B: Missing or Incompatible Dependency
+1. **Diagnosis**: Required toolchain binary or library dependency is missing from the environment.
+2. **Recovery Protocol**:
+   - Step 1: Verify `package.json` engine requirements and local environment versions.
+   - Step 2: Install required peer dependencies cleanly with lockfile sync.
+   - Step 3: Resume runbook from Phase 1.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/playwright-best-practices/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: playwright-best-practices
+description: Playwright E2E browser automation standards, Page Object Models,
+  auto-waiting locators, test fixtures, and visual regression.
+metadata:
+  author: Currents / Microsoft (currents-dev/playwright-best-practices-skill)
+  version: 1.0.0
+  source: https://skills.sh/currents-dev/playwright-best-practices-skill/playwright-best-practices
+  icon: 🎭
+disable-slash-command: true
+---
+
+# Playwright E2E Testing Best Practices Playbook
+
+## Overview & Purpose
+`playwright-best-practices` provides authoritative guidelines for building fast, stable, and deterministic end-to-end browser tests using Microsoft Playwright.
+
+## Rules & Constraints
+1. **Use User-Facing Locators** — Always prefer `page.getByRole()`, `page.getByLabel()`, or `page.getByPlaceholder()` over fragile CSS classes or XPath.
+2. **Never Use Hardcoded Sleeps** — Never invoke `page.waitForTimeout()`; use web assertions that auto-wait (`await expect(locator).toBeVisible()`).
+3. **Encapsulate with Page Object Models (POM)** — Structure reusable page interactions into dedicated POM classes.
+4. **Isolate Test State** — Run tests in independent browser contexts with dedicated user sessions or `test.use({ storageState })`.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Test Configuration
+- Configure `playwright.config.ts` with parallel workers, trace recording (`on-first-retry`), and multi-project browser configs.
+
+### Phase 2 — Page Object & Spec Construction
+- Author POM classes with explicit methods returning locators or executing user actions.
+- Write readable, assertive test specs covering positive and negative edge cases.
+
+### Phase 3 — Verification
+- Execute tests headlessly via `npx playwright test` and verify HTML report generation.
+
+## Verification Checklist
+- [ ] Tests run deterministically without flakes.
+- [ ] Trace viewer and video artifacts saved on failure.
+- [ ] No hardcoded sleep timeouts in test code.