@mclawnet/agent 0.5.9 → 0.6.2

package/skills/video-generation/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: video-generation
+description: Create structured video scripts, storyboards, and production plans for video content. Use when planning video productions, writing video scripts, creating storyboards, or structuring educational and marketing video content.
+disable-model-invocation: true
+---
+
+# Video Generation
+
+Create structured video scripts with storyboards, shot lists, timing, and production notes for video content creation.
+
+## Overview
+
+This skill helps create complete video production plans — from concept through script to storyboard. It covers explainer videos, tutorials, marketing content, presentations, and narrative shorts with proper visual storytelling, pacing, and audience engagement techniques.
+
+## When to Use
+
+- Planning video content (explainers, tutorials, demos, marketing)
+- Writing video scripts with visual and audio directions
+- Creating storyboards for pre-production
+- Structuring educational video series
+- Designing video presentations with narration
+
+## When NOT to Use
+
+- **Audio-only content** — use the `podcast-generation` skill
+- **Written articles or blog posts** — use the `content-research-writer` skill
+- **Live streaming** — different workflow, real-time, less structured
+- **Video editing instructions** — this skill plans content, not post-production
+
+## Video Types
+
+### Explainer Video (60-120 seconds)
+Explain a concept, product, or process clearly and concisely.
+- Hook: 5-10 seconds (the problem)
+- Solution: 15-20 seconds (what it does)
+- How it works: 30-60 seconds (key features/steps)
+- CTA: 10-15 seconds (what to do next)
+
+### Tutorial / How-To (5-15 minutes)
+Step-by-step instruction for completing a task.
+- Intro: What we'll build/learn (30 seconds)
+- Prerequisites: What you need (30 seconds)
+- Steps: One section per step, show-then-explain
+- Recap: Summary of what was accomplished
+- Next steps: What to explore next
+
+### Product Demo (2-5 minutes)
+Showcase a product's features and value.
+- Problem statement: The pain point (15 seconds)
+- Solution reveal: First look at the product (15 seconds)
+- Feature walkthrough: 3-5 key features (2-3 minutes)
+- Social proof: Testimonials or metrics (30 seconds)
+- CTA: How to get started (15 seconds)
+
+### Presentation / Talk (10-30 minutes)
+Structured presentation with slides and narration.
+- Opening hook: Provocative question or statistic
+- Agenda: What you'll cover
+- Main sections: 3-5 key points with supporting visuals
+- Summary: Key takeaways
+- Q&A or CTA
+
+## Script Creation Process
+
+### Step 1: Define the Video
+
+1. **Goal**: What should the viewer do/know after watching?
+2. **Audience**: Who is watching? What do they already know?
+3. **Format**: Explainer / Tutorial / Demo / Presentation
+4. **Duration**: Target length
+5. **Platform**: YouTube / Social / Internal / Presentation
+6. **Tone**: Professional / Casual / Fun / Serious
+
+### Step 2: Write the Script
+
+Use a two-column format for video scripts:
+
+```
+TIME    | VISUAL                        | AUDIO (Narration/VO)
+--------|-------------------------------|---------------------------
+0:00    | Logo animation                | [MUSIC: Upbeat intro]
+0:05    | Problem scenario:             | "Have you ever spent hours
+        | Person frustrated at desk     |  trying to..."
+0:15    | Product UI appears            | "Meet [Product]. It
+        | with smooth transition        |  solves this by..."
+0:30    | Screen recording:             | "Here's how it works.
+        | Feature 1 demo                |  First, you..."
+1:00    | Screen recording:             | "Next, simply click..."
+        | Feature 2 demo                |
+1:30    | Results/metrics               | "The result? Users save
+        | animated infographic          |  an average of..."
+1:45    | CTA screen with URL           | "Get started free at..."
+2:00    | End card with logo            | [MUSIC: Outro]
+```
+
+### Step 3: Storyboard
+
+For each scene, sketch or describe:
+
+```
+SCENE 1: Opening Hook
+┌─────────────────────────┐
+│                         │
+│   [Person looking       │
+│    frustrated at        │
+│    cluttered desk]      │
+│                         │
+│   LOWER THIRD:          │
+│   "Sound familiar?"     │
+│                         │
+└─────────────────────────┘
+Camera: Medium shot, eye level
+Movement: Slow zoom in
+Duration: 5 seconds
+Transition: Cut to Scene 2
+```
+
+### Step 4: Shot List
+
+```markdown
+| # | Scene | Shot Type | Camera | Movement | Duration | Notes |
+|---|-------|-----------|--------|----------|----------|-------|
+| 1 | Intro | Medium    | Eye level | Zoom in | 5s | Talent at desk |
+| 2 | Problem | Close-up | Slightly high | Static | 3s | Screen showing errors |
+| 3 | Solution | Wide | Eye level | Pan right | 5s | Product reveal |
+| 4 | Demo 1 | Screen cap | — | — | 15s | Feature walkthrough |
+| 5 | Demo 2 | Screen cap | — | — | 15s | Second feature |
+| 6 | Results | Medium | Eye level | Static | 10s | Metrics on screen |
+| 7 | CTA | Medium | Eye level | Static | 10s | URL and QR code |
+```
+
+## Visual Storytelling Principles
+
+### Show, Don't Tell
+
+- Bad: Narrator says "Our product is fast" over a static logo
+- Good: Screen recording showing a task completing in 2 seconds with a timer visible
+
+### Pacing
+
+**Rule of 8 seconds**: Change something visually every 8 seconds maximum to maintain attention.
+
+Changes can be:
+- Cut to a new scene
+- Animation or transition
+- Text appearing on screen
+- Camera movement
+- New visual element
+
+### Visual Hierarchy
+
+**What the viewer sees first (in order):**
+1. Motion (anything moving grabs attention)
+2. Faces (we're hardwired to look at faces)
+3. Text (especially if it appears/animates)
+4. Color contrast (bright against dark)
+5. Size (larger elements dominate)
+
+### Text on Screen
+
+- **Maximum 7 words** per text overlay
+- **Minimum 2 seconds** display time per text element
+- **High contrast**: White text on dark overlay, or dark text on light
+- **Consistent placement**: Pick a position and stick with it
+- **Font size**: Large enough to read on mobile (the smallest common screen)
+
+## Script Template
+
+```markdown
+# [Video Title]
+
+## Metadata
+- **Type**: [Explainer / Tutorial / Demo / Presentation]
+- **Duration**: [Target length]
+- **Audience**: [Who is this for]
+- **Goal**: [What should viewer do/know after]
+- **Platform**: [YouTube / Social / Internal]
+- **Tone**: [Professional / Casual / Fun]
+
+## Script
+
+### Scene 1: Hook [0:00 — 0:10]
+**Visual**: [Description of what's on screen]
+**Audio**: "[Narration text]"
+**Text on screen**: [Any overlay text]
+**Music/SFX**: [Audio cues]
+
+### Scene 2: Problem [0:10 — 0:25]
+**Visual**: [Description]
+**Audio**: "[Narration]"
+
+### Scene 3: Solution [0:25 — 0:45]
+**Visual**: [Description]
+**Audio**: "[Narration]"
+
+[Continue for all scenes...]
+
+### Final Scene: CTA [X:XX — X:XX]
+**Visual**: [End card with logo, URL]
+**Audio**: "[Call to action narration]"
+
+---
+
+## Production Notes
+- [Equipment needed]
+- [Locations]
+- [Graphics/animations to create]
+- [Stock footage needed]
+- [Music tracks]
+
+## Post-Production
+- [ ] Rough cut assembled
+- [ ] Color correction
+- [ ] Graphics and text overlays added
+- [ ] Music and SFX mixed
+- [ ] Captions/subtitles added
+- [ ] Final review
+- [ ] Export for target platform(s)
+```
+
+## Platform-Specific Guidelines
+
+| Platform | Aspect Ratio | Max Duration | Key Consideration |
+|---|---|---|---|
+| YouTube | 16:9 | No limit | SEO title, thumbnail, first 30s crucial |
+| TikTok / Reels | 9:16 | 3 min | Hook in first 1-2 seconds, vertical |
+| LinkedIn | 16:9 or 1:1 | 10 min | Professional tone, captions essential |
+| Twitter/X | 16:9 | 2:20 | Short, punchy, works without sound |
+| Presentation | 16:9 | Varies | Clean slides, readable at distance |
+
+## Common Pitfalls
+
+### No Hook
+**Problem**: Video starts with logo animation and slow intro — viewer clicks away.
+**Fix**: Start with the most compelling content. Logo can come after the hook.
+
+### Wall of Text
+**Problem**: Slides packed with paragraphs that the narrator reads verbatim.
+**Fix**: One idea per visual. Use images and short phrases, not paragraphs.
+
+### Monotone Pacing
+**Problem**: Same visual style and energy level throughout.
+**Fix**: Vary shot types, pacing, and energy. Mix screen recordings with face-to-camera.
+
+### Missing Captions
+**Problem**: No subtitles — excludes deaf viewers and those watching without sound (85% of social media video).
+**Fix**: Always add captions. Most platforms support SRT upload or auto-generation.

package/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: web-design-guidelines
+description: Audit web UI code for accessibility, responsiveness, performance, and UX best practices. Use when reviewing frontend code, checking accessibility compliance, auditing design patterns, or improving web interface quality.
+---
+
+# Web Design Guidelines
+
+Audit web UI code against industry-standard accessibility, responsiveness, performance, and UX best practices — producing actionable findings with file and line references.
+
+## When to Use
+
+- Reviewing UI code for accessibility compliance (WCAG 2.1)
+- Auditing responsive design across breakpoints
+- Checking web performance patterns (Core Web Vitals)
+- Evaluating UX patterns and interaction design
+- Validating semantic HTML and ARIA usage
+- Reviewing CSS architecture and specificity
+
+## When NOT to Use
+
+- **Visual design review** — this skill audits code, not mockups or screenshots
+- **Backend API review** — use the `code-review` or `security-audit` skill
+- **Mobile native apps** — different platform guidelines apply
+- **Content writing or copy review** — use `technical-writing` skill
+
+## Review Process
+
+### Step 1: Identify Files to Audit
+
+Read the specified files (or ask the user which files to review). Focus on:
+- HTML templates and JSX/TSX components
+- CSS/SCSS/Tailwind stylesheets
+- JavaScript/TypeScript interaction code
+- Framework config (Next.js, Vite, etc.)
+
+### Step 2: Run Checklist Audits
+
+Apply each category below. For every finding, output:
+```
+file:line — [category] description (severity: critical|important|suggestion)
+```
+
+### Step 3: Summarize
+
+Group findings by severity. Provide a score per category (pass / needs work / fail).
+
+## Audit Categories
+
+### 1. Accessibility (WCAG 2.1 AA)
+
+**Images and media:**
+- Every `<img>` must have a meaningful `alt` attribute (not "image", not empty for informational images)
+- Decorative images: use `alt=""` or CSS background
+- `<video>` and `<audio>` must have captions or transcripts
+
+**Keyboard navigation:**
+- All interactive elements must be reachable via Tab
+- Focus order must follow visual order
+- Custom components need proper `tabindex`, `role`, and key handlers
+- Focus must be visible (no `outline: none` without replacement)
+
+**Color and contrast:**
+- Text contrast ratio: minimum 4.5:1 (normal text), 3:1 (large text)
+- Information must not rely on color alone (add icons, patterns, or text)
+
+**Forms:**
+- Every input must have an associated `<label>` (or `aria-label`)
+- Error messages must be programmatically associated with the field
+- Required fields must be marked with `aria-required="true"`
+
+**ARIA:**
+- Use semantic HTML first (`<nav>`, `<main>`, `<aside>`) before ARIA roles
+- Don't add `role` to elements that already have implicit roles
+- Live regions (`aria-live`) for dynamic content updates
+
+### 2. Responsive Design
+
+**Breakpoints:**
+- Mobile-first approach (min-width media queries)
+- Test at common breakpoints: 320px, 768px, 1024px, 1440px
+- No horizontal scrollbar at any viewport width
+
+**Layout:**
+- Use relative units (rem, em, %, vw/vh) over fixed px for layout
+- Flexible containers: prefer `max-width` over fixed `width`
+- Grid and flexbox over float-based layouts
+
+**Touch targets:**
+- Minimum 44×44px touch target size (WCAG 2.5.5)
+- Adequate spacing between interactive elements on mobile
+
+**Typography:**
+- Base font size: minimum 16px (prevents iOS zoom on focus)
+- Line length: 45-75 characters for readability
+- Use `clamp()` for fluid typography
+
+**Images:**
+- Use `srcset` and `sizes` for responsive images
+- Serve WebP/AVIF with fallbacks
+- Lazy-load below-fold images (`loading="lazy"`)
+
+### 3. Performance
+
+**Loading:**
+- Critical CSS inlined or loaded with high priority
+- Non-critical JS deferred or loaded async
+- Fonts: use `font-display: swap` to prevent invisible text
+
+**Rendering:**
+- Avoid layout shifts: set explicit `width` and `height` on images
+- Minimize DOM depth and node count
+- Use CSS `contain` for isolated components
+
+**Bundle size:**
+- Check for unused imports and dead code
+- Prefer tree-shakeable ES modules
+- Lazy-load routes and heavy components
+
+**Core Web Vitals targets:**
+| Metric | Good | Needs Improvement |
+|--------|------|-------------------|
+| LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms |
+| CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 |
+
+### 4. Semantic HTML
+
+- Use `<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<aside>`, `<footer>` appropriately
+- Heading hierarchy: one `<h1>` per page, no skipping levels
+- Lists use `<ul>`/`<ol>`, not styled `<div>`s
+- Tables use `<table>` with `<thead>`, `<th scope>` — not div grids
+- Links (`<a>`) for navigation, buttons (`<button>`) for actions
+
+### 5. CSS Quality
+
+**Architecture:**
+- Consistent naming convention (BEM, utility-first, or CSS modules)
+- No `!important` except for utility overrides
+- Specificity: keep selectors shallow (≤ 3 levels)
+
+**Common issues:**
+- No orphaned or unused styles
+- Avoid `z-index` wars (use a scale: 10, 20, 30...)
+- Use CSS custom properties for theme values (colors, spacing, fonts)
+- Prefer logical properties (`margin-inline`) for internationalization
+
+### 6. UX Patterns
+
+**Feedback:**
+- Loading states for async operations (skeleton screens or spinners)
+- Error states with clear recovery actions
+- Success confirmations for form submissions
+
+**Navigation:**
+- Current page/section clearly indicated
+- Breadcrumbs for deep hierarchies
+- Back navigation works as expected
+
+**Forms:**
+- Inline validation on blur (not just on submit)
+- Preserve user input on validation failure
+- Autocomplete attributes for common fields (`name`, `email`, `tel`)
+
+## Output Format
+
+```markdown
+## Audit Results: [file or component name]
+
+### Summary
+| Category | Score | Findings |
+|----------|-------|----------|
+| Accessibility | needs work | 3 critical, 2 important |
+| Responsive | pass | 1 suggestion |
+| Performance | needs work | 1 critical |
+| Semantic HTML | pass | 0 |
+| CSS Quality | pass | 1 suggestion |
+| UX Patterns | needs work | 2 important |
+
+### Critical
+- `src/Login.tsx:42` — [accessibility] Input missing associated label
+- `src/App.css:18` — [performance] Large unoptimized background image (2.3MB)
+
+### Important
+- `src/Nav.tsx:15` — [accessibility] Focus indicator removed with no replacement
+- `src/Card.tsx:8` — [ux] No loading state for async data fetch
+
+### Suggestions
+- `src/Layout.tsx:30` — [responsive] Consider clamp() for fluid font sizing
+```
+
+## Common Anti-Patterns
+
+### Div Soup
+**Problem:** Everything is a `<div>` with click handlers — no semantic meaning.
+**Fix:** Use `<button>`, `<a>`, `<nav>`, `<main>`. Reserve `<div>` for layout wrappers.
+
+### Accessibility Afterthought
+**Problem:** ARIA added after the fact without testing with screen readers.
+**Fix:** Use semantic HTML first. Test with VoiceOver/NVDA during development.
+
+### Desktop-First Responsive
+**Problem:** Designed for 1440px, then patched for mobile.
+**Fix:** Start with mobile layout, progressively enhance for larger screens.

package/skills/webapp-testing/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: webapp-testing
+description: Test and interact with local web applications using Playwright. Use when verifying frontend functionality, debugging UI behavior, capturing browser screenshots, or automating browser-based testing workflows.
+---
+
+# Web Application Testing
+
+Test local web applications by writing Playwright scripts. This skill covers browser automation, UI testing, visual regression, and interactive debugging for any web-based application.
+
+## When to Use
+
+- Verifying frontend functionality works as expected
+- Debugging UI behavior and visual rendering issues
+- Capturing browser screenshots for documentation or comparison
+- Automating repetitive browser testing workflows
+- End-to-end testing of web applications
+- Checking responsive design across viewport sizes
+
+## When NOT to Use
+
+- **Unit testing logic** — use the `testing` skill for non-browser tests
+- **API testing** — use direct HTTP calls or test frameworks
+- **Performance benchmarking** — use browser DevTools or Lighthouse directly
+- **Static code analysis** — use the `code-review` skill
+
+## Decision Tree: Choosing Your Approach
+
+```
+User task → Is it static HTML?
+    ├─ Yes → Read HTML file directly to identify selectors
+    │         ├─ Success → Write Playwright script using selectors
+    │         └─ Fails/Incomplete → Treat as dynamic (below)
+    │
+    └─ No (dynamic webapp) → Is the server already running?
+        ├─ No → Start the server first (npm run dev, etc.)
+        │        Then write Playwright script
+        │
+        └─ Yes → Reconnaissance-then-action:
+            1. Navigate and wait for networkidle
+            2. Take screenshot or inspect DOM
+            3. Identify selectors from rendered state
+            4. Execute actions with discovered selectors
+```
+
+## Writing Playwright Scripts
+
+### Basic Pattern
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)
+    page = browser.new_page()
+    page.goto('http://localhost:5173')
+    page.wait_for_load_state('networkidle')  # CRITICAL: Wait for JS to execute
+    # ... your automation logic
+    browser.close()
+```
+
+### Starting the Server
+
+If the dev server is not running, start it first:
+
+```bash
+# Start in background, wait for ready, then run tests
+npm run dev &
+sleep 5  # or use wait-on to detect port availability
+python test_script.py
+```
+
+For more reliable server management, use a process manager or run in a separate terminal.
+
+## Reconnaissance-Then-Action Pattern
+
+The most reliable approach for dynamic web apps:
+
+### Step 1: Inspect Rendered DOM
+
+```python
+page.goto('http://localhost:5173')
+page.wait_for_load_state('networkidle')
+page.screenshot(path='/tmp/inspect.png', full_page=True)
+content = page.content()
+buttons = page.locator('button').all()
+```
+
+### Step 2: Identify Selectors
+
+From the inspection results, determine the best selectors for your target elements. Prefer role-based and text-based selectors over CSS selectors for resilience.
+
+### Step 3: Execute Actions
+
+```python
+page.locator('text=Submit').click()
+page.locator('[data-testid="email-input"]').fill('test@example.com')
+page.wait_for_selector('.success-message')
+```
+
+## Common Patterns
+
+### Form Testing
+
+```python
+page.fill('#username', 'testuser')
+page.fill('#password', 'testpass')
+page.click('button[type="submit"]')
+page.wait_for_url('**/dashboard')
+assert 'Welcome' in page.content()
+```
+
+### Visual Regression
+
+```python
+page.set_viewport_size({'width': 1280, 'height': 720})
+page.screenshot(path='screenshots/desktop.png')
+
+page.set_viewport_size({'width': 375, 'height': 667})
+page.screenshot(path='screenshots/mobile.png')
+```
+
+### Console Log Capture
+
+```python
+logs = []
+page.on('console', lambda msg: logs.append(f'{msg.type}: {msg.text}'))
+page.goto('http://localhost:5173')
+page.wait_for_load_state('networkidle')
+for log in logs:
+    print(log)
+```
+
+### Element Discovery
+
+```python
+# Find all interactive elements
+buttons = page.locator('button').all()
+links = page.locator('a').all()
+inputs = page.locator('input').all()
+
+for btn in buttons:
+    print(f'Button: {btn.text_content()} — visible: {btn.is_visible()}')
+```
+
+## Common Pitfalls
+
+- **Not waiting for networkidle**: Dynamic apps need JS to execute before DOM is ready. Always call `page.wait_for_load_state('networkidle')` before inspecting.
+- **Brittle selectors**: Prefer `text=`, `role=`, `data-testid=` over nth-child or deep CSS paths.
+- **Not closing the browser**: Always call `browser.close()` to free resources.
+- **Headless vs headed**: Use `headless=True` for CI/automation, `headless=False` for local debugging.
+- **Timeout errors**: Increase timeouts for slow pages: `page.wait_for_selector('.element', timeout=10000)`.
+
+## Best Practices
+
+- Use `sync_playwright()` for synchronous scripts (simpler and sufficient for most testing)
+- Always close the browser when done
+- Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs
+- Add appropriate waits: `page.wait_for_selector()` or `page.wait_for_timeout()`
+- Take screenshots at key steps for debugging
+- Capture console logs to detect JavaScript errors
+- Test multiple viewport sizes for responsive design
+- Use `page.evaluate()` for complex DOM inspection