What this skill does

--- name: qrcode description: Generate styled QR codes (SVG/PNG/JPG) with custom colors, shapes, and error correction. Agent should display generated files. Secure: all outputs saved to workspace root. homepage: https://github.com/HeXavi8/skills metadata: { "clawdbot": { "emoji": "", "requires": { "bins": ["node"], "packages": ["qrcode", "sharp"] }, "primaryEnv": null, }, } --- # QRCode Generator Generate customizable QR codes from text or URLs. Supports multiple formats (SVG/PNG/JPG) with styling options. ## Agent Instructions **After generating QR codes, you MUST:** 1. Display the generated file using appropriate markdown syntax: - For images (PNG/JPG): `` - For SVG: Display as image or provide download link 2. Confirm the file path and format to the user 3. Offer to regenerate with different styling if needed ## Quick Start ```bash # Basic usage (auto-generated filename) node {baseDir}/scripts/generate.mjs "Hello World" # Custom styled QR code node {baseDir}/scripts/generate.mjs "https://example.com" -o myqr.svg --dot circle --eye rounded --color "#2563eb" # High-resolution transparent PNG node {baseDir}/scripts/generate.mjs "Contact Info" --format png --size 2048 --transparent # Print-quality JPEG node {baseDir}/scripts/generate.mjs "https://example.com" --format jpg -o qr.jpg --size 2048 --quality 95 ``` ## Options ### Output - `-o, --out <filename>` - Output filename (workspace root only). Default: `qrcode_<text>_<timestamp>.<ext>` - `--format <svg|png|jpg>` - Output format (default: `svg`) ### Dimensions - `--size <px>` - Base pixel size (default: `1024`, max: `10000`) - `--scale <n>` - Resolution multiplier (default: `1`, max: `10`) - `--margin <modules>` - Quiet zone size (default: `4`, max: `100`) ### Styling - `--dot <square|circle>` - Data module shape (default: `square`) - `--eye <square|circle|rounded>` - Finder pattern style (default: `square`) - `--color <#RRGGBB>` - Foreground color (default: `#000000`) - `--background <#RRGGBB>` - Background color (default: `#ffffff`) - `--transparent` - Transparent background (PNG only, ignored for SVG/JPG) ### Quality - `--ec <L|M|Q|H>` - Error correction: Low/Medium/Quality/High (default: `M`) - **L (~7%)**: Clean environments, maximum data capacity - **M (~15%)**: General use, balanced capacity/reliability - **Q (~25%)**: Styled QR codes, moderate damage tolerance - **H (~30%)**: Logo embedding, heavy styling, outdoor use - `--quality <1-100>` - JPEG compression quality (default: `80`) ## File Handling **Security-enforced workspace root output:** - All files saved to workspace root directory only - Path components stripped: `-o ../path/file.svg` → `workspace/file.svg` - Auto-generated filenames include sanitized text and timestamp - Maximum text length: 4096 characters ## Installation ```bash cd {baseDir} npm install ``` **Dependencies:** `qrcode` (matrix generation), `sharp` (image conversion) **Platform notes:** macOS requires Xcode Command Line Tools. See [sharp docs](https://sharp.pixelplumbing.com/install) for other platforms. ## Examples ### WiFi QR Code ```bash node {baseDir}/scripts/generate.mjs "WIFI:S:MyNetwork;T:WPA;P:password123;;" --format png -o wifi.png --size 1024 ``` ### Styled Business Card ```bash node {baseDir}/scripts/generate.mjs "BEGIN:VCARD VERSION:3.0 FN:John Doe TEL:+1234567890 EMAIL:[email protected] END:VCARD" --dot circle --eye rounded --color "#1e40af" --background "#eff6ff" -o contact.svg ``` ### High-Resolution Print ```bash node {baseDir}/scripts/generate.mjs "https://example.com" --format jpg --size 4096 --quality 95 --ec H -o print.jpg ``` ### Transparent Logo Overlay ```bash node {baseDir}/scripts/generate.mjs "https://example.com" --format png --size 2048 --transparent --margin 2 -o overlay.png ``` ### Logo Embedding (Requires High Error Correction) ```bash # Use --ec H when QR code will have logo overlay (covers ~20-30% of center) node {baseDir}/scripts/generate.mjs "https://example.com" --format png --size 2048 --ec H -o logo-base.png ``` ## Security Features - ✅ **Path traversal protection** - All outputs forced to workspace root - ✅ **Symlink attack prevention** - Atomic writes with verification - ✅ **Input validation** - Length limits (4096 chars), character whitelisting - ✅ **Filename sanitization** - Dangerous characters stripped from filenames - ✅ **Resource limits** - Max size/scale to prevent DoS attacks ## Troubleshooting | Issue | Solution | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `npm install` fails | Install build tools:`xcode-select --install` (macOS) or see [sharp install guide](https://sharp.pixelplumbing.com/install) | | QR code won't scan | Increase `--size`, use higher error correction (`--ec H`), or simplify styling | | Colors not working | Use hex format `#RRGGBB` (e.g., `#FF5733`), not RGB or color names | | File too large | Reduce `--size`, `--scale`, or increase `--quality` for JPG | | Permission denied | Check workspace directory write permissions | ## Error Correction Levels Explained Error correction allows QR codes to remain scannable even when partially damaged or obscured: | Level | Recovery Capacity | Data Capacity | Use Case | | ----- | ----------------- | ------------- | ---------------------------------------------------------- | | `L` | ~7% damage | Maximum | Clean environments, screen display, maximum data | | `M` | ~15% damage | High | **General use (default)**, standard printing | | `Q` | ~25% damage | Medium | Styled designs (circles/rounded), possible minor damage | | `H` | ~30% damage | Minimum | Logo embedding, outdoor use, heavy styling, print-on-print | **Key principle:** Higher error correction = more damage tolerance but less data capacity. **When to use H level:** - Embedding logos (covers 20-30% of center) - Circular dots or rounded eyes - Outdoor/weathered environments - Low-quality printing - Stickers that may peel/scratch ## Format Comparison | Format | Transparency | Quality | File Size | Use Case | | ------ | ------------ | -------- | ---------- | -------------------------- | | SVG | ✅ | Infinite | Smallest | Web, scalable graphics | | PNG | ✅ | Lossless | Medium | Digital displays, overlays | | JPG | ❌ | Lossy | Smallest\* | Print, photos, email | \*With compression ## Tips - **Scanning distance**: Use `--size 1024` for mobile (1-2m), `--size 2048+` for print/posters - **Styling vs. reliability**: Higher `--ec` levels compensate for `--dot circle` or `--eye rounded` - **Transparent backgrounds**: Use PNG format with `--transparent`; JPG always uses white/specified background - **File size optimization**: SVG for web, JPG with `--quality 80-85` for print - **Data capacity**: L/M/Q/H levels affect max alphanumeric capacity: ~4296/3391/2420/1852 chars (Version 40) - **Logo placement**: Use `--ec H` and leave center area clear (approximately 30% of QR code) ## Common Use Cases | Scenario | Recommended Settings | | ------------------------- | ---------------------------------------------------------------- | | Website URL | `--format png --size 1024 --ec M` | | WiFi credentials | `--format png --size 1024 --ec M` | | Business card (vCard) | `--format svg --dot circle --eye rounded --ec Q` | | Print poster | `--format jpg --size 4096 --quality 95 --ec H` | | Logo overlay base | `--format png --size 2048 --ec H --transparent` | | Email signature | `--format png --size 512 --ec M` | | Product packaging | `--format svg --ec H` (scalable for any print size) | | Outdoor signage | `--format jpg --size 2048+ --ec H --quality 90` | | Social media profile | `--format png --size 1024 --transparent --dot circle --ec Q` | | Payment QR (high density) | `--format png --size 2048 --ec L --margin 2` (maximize capacity) |