jazzyalex/sc-skill

SC Skill

Overview

Use this skill to produce repeatable screenshots for two modes:

• testing: stable evidence screenshots for QA/regression workflows.
• marketing: polished, consistently framed screenshots for docs/site/release assets.

This skill is macOS-first and uses Peekaboo as primary automation with native screencapture fallback.

Quick Start

1. Normalize window size and position:

skills/sc-skill/scripts/sc_window_preset.sh --app "AgentSessions" --preset marketing

2. Capture one screenshot (auto-select tool):

skills/sc-skill/scripts/sc_capture.sh \
  --app "AgentSessions" \
  --mode marketing \
  --delay 0.25 \
  --max-edge auto \
  --window-preset auto \
  --output artifacts/screenshots/agent-sessions-main.png

3. Run a manifest batch:

skills/sc-skill/scripts/sc_capture_suite.sh \
  --manifest skills/sc-skill/references/examples/agent-sessions.tsv \
  --outdir artifacts/screenshots

Workflow

1. Choose mode:

• testing: prioritize determinism and speed.
• marketing: prioritize composition consistency.

2. Choose tool:

• Start with --tool auto (defaults to Peekaboo when available and permitted).
• Use --tool native when you need zero external dependency and simple window-region capture.

3. Enforce layout before capture:

• Always run sc_window_preset.sh first.
• Use consistent presets across runs to reduce visual drift.

4. Capture and archive:

• Save to artifacts/screenshots/....
• Sidecar metadata (.json) is opt-in via --metadata; default runs keep artifacts cleaner.
• Default output uses mode-based max edge (--max-edge auto): testing=1800, marketing=2560, optimized/compressed for sharing/upload.
• AgentSessions windows are normalized to a realistic working preset before capture (mode-based testing/marketing) to avoid distorted/compressed UI composition.
• Single capture closes the target app window by default (--no-close-window to keep it open).
• Suite runs close captured app windows after all requested screenshots by default (--no-close-after-suite to keep them open).
• For AgentSessions, transcript readiness retry includes a built-in selection nudge (key down + 0.5s pause) to force transcript loading before capture.
• Default transcript readiness remains fast-fail if loading still does not occur after nudge attempts.
• If transcript readiness times out, capture fails fast by default; pass --allow-blank-transcript only when blank transcript output is acceptable.

Guardrails

• Never run captures from XCTest-driven launches when validating user-visible UI behavior; use a normal app launch.
• Keep screenshot naming stable and descriptive (screen-purpose-state.png).
• Avoid manual resize/drag between shots; use presets.
• For multi-shot runs, use the suite manifest instead of ad-hoc commands.

Resources

• scripts/sc_window_preset.sh: deterministic window sizing/placement.
• scripts/sc_capture.sh: single-shot capture with Peekaboo/native fallback.
• scripts/sc_capture_suite.sh: manifest-driven batch capture.
• references/tool-matrix.md: tooling decision matrix and tradeoffs.
• references/workflow-checklist.md: repeatable QA/marketing checklist.