Image compress and docs

Skill EntityProcess/agentv/plugins/agentv-self/skills/image-compress-and-docs

Light-weight AI agent evaluation and optimization framework

Install

npx -y skills add EntityProcess/agentv --skill image-compress-and-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Capture, optimize, and publish screenshots to Astro docs. Use when asked to take screenshots for docs, update doc images, compress PNG assets, or add visual documentation to the agentv.dev docs site. Triggers on "add screenshots to docs", "update docs images", "compress screenshots", "optimize PNG", "document with screenshots".

SKILL.md

5.2 KB, as published. Nobody here has run it

Image Compression & Docs Update

Capture browser screenshots, optimize them for the web, and publish to the Astro docs site at apps/web/src/content/docs/.

Prerequisites

Install optimization tools if not present:

# Ubuntu/Debian (usually pre-installed)
sudo apt-get install -y pngquant optipng

# macOS
brew install pngquant optipng

Verify:

which pngquant optipng

Step 1 — Capture Screenshots

Use agent-browser with a named session and 1440×860 viewport for docs-quality screenshots. Always use --session to isolate, never --headed.

# Start the target server first (e.g., Dashboard)
bun apps/cli/src/cli.ts dashboard --port 14800 &
sleep 3

# Open, set viewport, navigate, screenshot
agent-browser --session docs-shots open http://localhost:14800
agent-browser --session docs-shots wait --load networkidle
agent-browser --session docs-shots set viewport 1440 860
agent-browser --session docs-shots snapshot -i          # discover refs
agent-browser --session docs-shots click <ref>          # navigate if needed
agent-browser --session docs-shots wait --load networkidle
agent-browser --session docs-shots screenshot           # saved to /run/user/1000/agent-browser/tmp/screenshots/

# Clean up
agent-browser --session docs-shots close
kill $(lsof -ti:14800) 2>/dev/null

Screenshots with realistic data: Dashboard screenshots must have populated data — multiple runs with varying pass rates and real targets. If results are sparse, create synthetic run bundles under .agentv/results/<run_id>/ with summary.json plus .internal/index.jsonl rows before launching Dashboard.

Synthetic JSONL record format:

{"test_id": "my-test", "score": 0.95, "target": "claude-sonnet", "experiment": "default", "timestamp": "2026-04-08T09:15:44.003Z", "status": "pass", "suite": "my-suite", "duration_ms": 3500, "token_usage": {"input_tokens": 1200, "output_tokens": 400}, "scores": [{"type": "llm-rubric", "score": 0.95, "pass": true}], "grading_path": "my-test--demo/sample-1/grading.json", "metrics_path": "my-test--demo/sample-1/metrics.json", "error": null}

Step 2 — Optimize

Always apply both passes: pngquant (lossy, 50–70% savings) then optipng (lossless polish).

SHOT="/run/user/1000/agent-browser/tmp/screenshots/screenshot-<id>.png"
OUT="/home/christso/projects/agentv/apps/web/src/assets/screenshots/my-feature.png"

# Pass 1: lossy quantization (creates <name>-fs8.png or use --output)
pngquant --quality 80-95 --force --output /tmp/opt.png "$SHOT"

# Pass 2: lossless polish
optipng -o5 -quiet /tmp/opt.png

# Copy to docs assets
cp /tmp/opt.png "$OUT"

# Check savings
ls -lh "$SHOT" "$OUT"

Typical results: 116 KB raw → 44 KB optimized (62% reduction).

For multiple files:

SHOTS_DIR="/run/user/1000/agent-browser/tmp/screenshots"
ASSETS_DIR="/home/christso/projects/agentv/apps/web/src/assets/screenshots"

for f in shot1.png shot2.png shot3.png; do
  pngquant --quality 80-95 --force --output "$SHOTS_DIR/opt-$f" "$SHOTS_DIR/$f"
  optipng -o5 -quiet "$SHOTS_DIR/opt-$f"
  cp "$SHOTS_DIR/opt-$f" "$ASSETS_DIR/$f"
done
ls -lh "$ASSETS_DIR"

Step 3 — Update Astro Docs

Docs live at: apps/web/src/content/docs/docs/next/
Assets live at: apps/web/src/assets/screenshots/

Import pattern (Astro <Image> for automatic optimization):

import { Image } from 'astro:assets';
import myFeature from '../../../../assets/screenshots/my-feature.png';
import myDetail from '../../../../assets/screenshots/my-detail.png';

<Image src={myFeature} alt="Descriptive alt text for accessibility" />

Alt text rules:

Describe what the screenshot shows, not just what the feature is
Include key data visible in the image (e.g., "showing 100% pass rate across 5 tests")
Never use "screenshot of" — just describe the content

Placement:

Put the hero image directly after the intro paragraph (before ## Usage)
Put feature-specific images directly after the section that describes them
Don't cluster all images at the top or bottom

Step 4 — Commit

# Feature branch: UI changes
cd /path/to/worktree
git add apps/dashboard/...
git commit -m "fix(studio): ..."

# Main repo: docs changes  
cd /home/christso/projects/agentv
git add apps/web/src/assets/screenshots/ apps/web/src/content/docs/
git commit -m "docs(<feature>): add screenshots and update documentation"
git push

Checklist

Screenshots show realistic data (multiple runs, real targets, varying scores)
Viewport set to 1440×860 before capturing
Both pngquant and optipng applied
File size verified (target: <50 KB per screenshot)
Alt text is descriptive and specific
Image placed close to the content it illustrates
Astro <Image> component used (not raw <img>)
Docs committed separately from code changes