agentleFS
bordenetbordenet/superpowers-plus/skills/productivity/screenshot/skill.md

screenshot

Skill8 starsChanged 4 days agoMITView on GitHub

Visual input bridge. Grabs the N most recent screenshots from the configured folder and dispatches to an intent-driven action. Supports fix (with project context), explain, compare, spec, do-this, recap, and free-form. Cross-platform folder discovery with auto-populate to ~/.codex/.env.

  • Reads credentials

52 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use spreadsheet, obsidian-vault and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JetBrainsSkill

    spreadsheet

    Use when tasks involve creating, editing, analyzing, or formatting spreadsheets (`.xlsx`, `.csv`, `.tsv`) with formula-aware workflows, cached recalculation, and visual review.

    Also in 3 projects that use this

  • simo97Skill

    obsidian-vault

    Also in 4 projects that use this

  • JetBrainsSkill

    slides

    Create and edit presentation slide decks (`.pptx`) with PptxGenJS and render/validation utilities. Use when tasks involve building a new PowerPoint deck, recreating slides from screenshots/PDFs/reference decks, modifying slide content while preserving editable output, adding charts/diagrams/visuals, or diagnosing layout issues such as overflow, overlaps, and font substitution.

    Also in 5 projects that use this

  • simo97Skill

    edit-article

    The user will invoke this skill to help them edit an article.

    Also in 3 projects that use this

  • LesaniSkill

    writing-beats

    Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.

    Also in 3 projects that use this

  • LesaniSkill

    writing-shape

    Take a markdown file of raw material and shape it into an article through a conversational session — drafting candidate openings, growing the piece paragraph by paragraph, arguing about format (lists, tables, callouts, quotes) at each step. Use when the user has a pile of notes, fragments, or a rough draft and wants help turning it into something publishable.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. 0 are common, 11 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 48 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Parse rule: If the first token after the command matches /^\d+$/ (one or more digit characters, no sign), it is parsed as count N.

    line 39
  2. Very specific:

    If intent is omitted entirely, default to huh.

    line 44
  3. Very specific:

    Read SCREENSHOT_DIR from ~/.codex/.env:

    line 61
  4. Very specific:

    Use the Bash tool: grep "^SCREENSHOT_DIR=" ~/.codex/.env 2>/dev/null | cut -d= -f2- — extract only this key, do NOT read the full .env file …

    line 62
  5. Distinctive:

    If set and the path exists → use it, skip discovery.

    line 63
  6. Distinctive:

    If not set or the path no longer exists → run platform discovery below.

    line 64
  7. Very specific:

    Validate before persisting: After discovery returns a path, resolve it to a canonical path using realpath to prevent symlink and traversal …

    line 99
  8. Distinctive:

    If the check fails, fall back to the next discovery step rather than persisting an invalid path.

    line 105
  9. Distinctive:

    Use atomic writes to prevent concurrent modification race conditions:

    line 109
  10. Very specific:

    If the write fails (read-only .env): print "Add SCREENSHOT_DIR=<path> to ~/.codex/.env to persist this setting." Then proceed with the …

    line 126
  11. Distinctive:

    Count > available: Use all available, note: "Only X screenshots found.

    line 138
  12. Distinctive:

    Count invalid: Default to 1, note: "Invalid count.

    line 139
  13. Very specific:

    No image files found: Stop. Print: "No screenshots found in <path>.

    line 140
  14. Very specific:

    Staleness warning (advisory only): If the newest file is older than SCREENSHOT_STALENESS_MINUTES (default 30), print: "⚠️ Newest screenshot …

    line 141
  15. Very specific:

    Read each selected file using the Read tool.

    line 145
  16. Distinctive:

    When multiple rows match, use the Priority column — lowest number wins

    line 151
  17. Distinctive:

    Read the screenshot(s) and classify before dispatching:

    line 168
  18. Very specific:

    If UI/design → proceed with spec generation.

    line 173
  19. Very specific:

    If code/error/terminal → print: "This looks like a code/error screenshot — routing to fix instead.

    line 174
  20. Distinctive:

    If ambiguous → ask the user: "Is this a UI screenshot (spec) or a code/error screenshot (fix)?"

    line 175
  21. Distinctive:

    Before interpreting the screenshot, check the current working directory for project markers.

    line 179
  22. Very specific:

    If a marker is found, inject a 1–2 sentence prefix before interpreting the screenshot: *"Project: <name> (<detected tech stack>)."*

    line 187
  23. Distinctive:

    If no marker is found in CWD: proceed without injection, no error, no mention.

    line 190
  24. Very specific:

    iCloud on macOS: If screenshots are saved to iCloud Drive, the resolved path may be inside ~/Library/Mobile Documents/.

    line 212

“Common” is measured: kept by at least 6 in 10 of the 48 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
skill.md
<!-- Credit: Allie K. Miller (https://www.linkedin.com/posts/alliekmiller_give-me-one-minute-and-ill-improve-your-share-7457142778410594304-_cdB) — original /ss concept. This skill extends that design with a formal intent dispatch table, cross-platform folder discovery, context injection, and operational guardrails. -->

Screenshot

Wrong skill? Take a screenshot → use your OS. Debug without a screenshot → systematic-debugging. Build a feature → feature-development.

Visual input bridge: grab screenshots and act on them.

Syntax

/sp-ss [N] [intent text...]
/sp-screenshot [N] [intent text...]

Parse rule: If the first token after the command matches /^\d+$/ (one or more digit characters, no sign), it is parsed as count N. Otherwise N=1 and the entire remainder is the intent. Details:

  • Tokens like 1.5 and abc do not match the regex → become intent text
  • 0 matches the regex but fails range validation (count must be ≥1) → default to 1 with a note
  • Negative numbers (e.g., -1) do not match the regex → become intent text, not a defaulted count

If intent is omitted entirely, default to huh.

Examples:

CommandCountIntent
/sp-ss1huh (default)
/sp-ss huh1huh
/sp-ss 3 fix3fix
/sp-ss 4 compare4compare
/sp-ss spec1spec
/sp-ss 2 make me an infographic2free-form
/sp-ss 0 fix1fix (invalid count, defaulted to 1)
/sp-ss abc fix1abc fix (non-numeric, treated as intent)

Step 1: Resolve Screenshot Folder

Read SCREENSHOT_DIR from ~/.codex/.env:

  • Use the Bash tool: grep "^SCREENSHOT_DIR=" ~/.codex/.env 2>/dev/null | cut -d= -f2- — extract only this key, do NOT read the full .env file (it may contain unrelated secrets).
  • If set and the path exists → use it, skip discovery.
  • If not set or the path no longer exists → run platform discovery below.

Platform discovery:

macOS:
  path=$(defaults read com.apple.screencapture location 2>/dev/null)
  Quote the result when testing: [ -n "$path" ] && [ -d "$path" ]
  If path exists → use it
  Else → use ~/Desktop

WSL (detected via /proc/version containing "Microsoft" or "microsoft"):
  Try in order:
    1. username=$(cmd.exe /c "echo %USERNAME%" 2>/dev/null | tr -d '\r\n')
    2. Sanitize: `username="${username//[^a-zA-Z0-9._-]/}"` (whitelist alphanumeric, dot, underscore, hyphen)
    3. If empty → username=$USER
    4. If still empty → username=$(whoami)
    5. If all fail → stop; print: "Could not determine Windows username for WSL path resolution. Set SCREENSHOT_DIR manually in ~/.codex/.env."
  Construct: `/mnt/c/Users/"${username}"/Pictures/Screenshots` (quote to prevent injection)
  Note: Sanitization removes special characters; if username is unrecognizable after sanitization, fall back to next method.

Linux (non-WSL):
  try $XDG_SCREENSHOTS_DIR (rarely set — not part of XDG Base Dir spec; treat
    as a bonus hint, not a reliable default)
  → ~/Pictures/Screenshots
  → ~/Screenshots

Windows (PowerShell):
  path = [Environment]::GetFolderPath('MyPictures') + '\Screenshots'
  Note: on enterprise machines this may be a UNC path (\\server\...).
  UNC paths cannot be used directly in ~/.codex/.env without escaping.
  If GetFolderPath returns a UNC path, print a warning and ask the user to
  set SCREENSHOT_DIR manually.

Validate before persisting: After discovery returns a path, resolve it to a canonical path using realpath to prevent symlink and traversal attacks:

resolved_path=$(realpath "$path" 2>/dev/null) || { echo "Invalid path"; return 1; }
[ -d "$resolved_path" ] || { echo "Path is not a directory"; return 1; }
path="$resolved_path"

If the check fails, fall back to the next discovery step rather than persisting an invalid path.

Persist after discovery (atomic upsert, not append-only):

Use atomic writes to prevent concurrent modification race conditions:

tmp=$(mktemp ~/.codex/.env.XXXXXX 2>/dev/null) || { echo "Cannot create temp file"; exit 1; }
trap "rm -f '$tmp'" EXIT
grep -v "^SCREENSHOT_DIR=" ~/.codex/.env > "$tmp" 2>/dev/null || true
echo "SCREENSHOT_DIR=$discovered_path" >> "$tmp"
mv "$tmp" ~/.codex/.env 2>/dev/null || { echo "Write failed"; exit 1; }

This approach:

  1. Creates a temporary file atomically
  2. Removes any existing SCREENSHOT_DIR line(s)
  3. Appends the new value
  4. Atomically replaces .env (mv is atomic on same filesystem)

This prevents duplicate keys and ensures consistency even with concurrent invocations.

If the write fails (read-only .env): print "Add SCREENSHOT_DIR=<path> to ~/.codex/.env to persist this setting." Then proceed with the discovered path for this session only.

Step 2: List and Select Files

List image files in the resolved folder, sorted newest-to-oldest by modification time. Use case-insensitive extension matching. Include: .png, .jpg, .jpeg, .gif, .webp, .heic, .bmp, .tif, .tiff (and their uppercase variants on case-sensitive filesystems).

Select the N most recent files.

Guardrails:

  • File size limit: Skip any file exceeding SCREENSHOT_MAX_FILE_MB MB (default 10). If the configured value is ≤0 or non-numeric, treat as 10 and warn: "Invalid SCREENSHOT_MAX_FILE_MB; using default 10MB." To get file size in bytes: stat -f%z <file> (macOS) or stat -c%s <file> (Linux/WSL); divide by 1048576 to compare against the MB limit. Print: "Skipped <filename> (exceeds limit)." If all selected files are skipped, stop and report.
  • Max images per invocation: SCREENSHOT_MAX_IMAGES in ~/.codex/.env (default 4). If the configured value is ≤0 or non-numeric, treat as 4 (default) and warn: "Invalid SCREENSHOT_MAX_IMAGES; using default 4." If requested count > cap, warn and truncate: "Capped at N images (set SCREENSHOT_MAX_IMAGES to increase)."
  • Count > available: Use all available, note: "Only X screenshots found; using X instead of requested N."
  • Count invalid: Default to 1, note: "Invalid count; using 1."
  • No image files found: Stop. Print: "No screenshots found in <path>. Have you taken a screenshot recently?"
  • Staleness warning (advisory only): If the newest file is older than SCREENSHOT_STALENESS_MINUTES (default 30), print: "⚠️ Newest screenshot is <age> old — is this the right one?" Then proceed immediately without waiting.

Step 3: Read Images

Read each selected file using the Read tool. For HEIC files that fail: "Could not read <filename>.heic — HEIC may not be supported here. Save screenshots as PNG (System Settings → Screenshots → Format) for best compatibility." Skip the failed file and continue with remaining selections.

Step 4: Dispatch Intent

Match the intent text against the table using case-insensitive semantic matching: the keyword list for each row is illustrative, not a regex. Use judgment to recognize intent. Key rules:

  • spec does NOT match "specification" (different concept); fix DOES match "fixing" or "broken" (same semantic family)
  • When multiple rows match, use the Priority column — lowest number wins
  • For genuinely ambiguous input (e.g., "compare and fix"), apply the highest-priority matching row

Priority ordering (first matching row wins):

PriorityIntent keywordsAction
1compare, diff, vs, versus, differenceHard gate: requires N≥2. If N=1: stop and print "compare requires N≥2 screenshots. Try /sp-ss 2 compare." Otherwise: diff/contrast the screenshots — layout, content, state changes, or visual differences.
2spec, requirements, prd, design docContent-type inference first (see below). If UI/design → generate product/design spec. If code/error/terminal → offer fix instead and explain why.
3fix, error, bug, broken, crashInject project context first (see below), then diagnose the problem shown and apply the fix.
4do this, apply, implement, learn, remixInject project context first (see below), then identify the concept or pattern in the screenshot and adapt it to the current project's goals.
5huh, explain, what, describe, what isDescribe the screenshot content clearly. Identify what it shows and what state it represents.
6recap, summarize, summary, overviewOne-paragraph synthesis of all N screenshots. What do they collectively show?
7(no match)Free-form fallback: prepend the screenshots as context and treat the full intent text as the prompt. No transformation.

Content-Type Inference (for spec intent)

Read the screenshot(s) and classify before dispatching:

  • UI/design indicators: Color gradients, component layouts (buttons, cards, nav bars), wireframe outlines, typography specimens, design system elements, mockup annotations.
  • Code/terminal indicators: Monospace font regions, command prompts ($, >, #), stack traces, syntax highlighting, line numbers, IDE chrome.

If UI/design → proceed with spec generation. If code/error/terminal → print: "This looks like a code/error screenshot — routing to fix instead. Type /sp-ss spec anyway if you want a spec from this." Then run Project Context Injection (see below) before running the fix flow. If ambiguous → ask the user: "Is this a UI screenshot (spec) or a code/error screenshot (fix)?"

Project Context Injection (for fix and do this intents)

Before interpreting the screenshot, check the current working directory for project markers. Use the Read tool on each file found:

  1. package.json → extract name and top-level dependencies/devDependencies keys
  2. go.mod → extract module name
  3. Cargo.toml → extract [package] name
  4. pyproject.toml → extract [project] name (preferred over setup.py if both exist)
  5. setup.py → extract name= argument (fallback if no pyproject.toml)

If a marker is found, inject a 1–2 sentence prefix before interpreting the screenshot: "Project: <name> (<detected tech stack>)."

If no marker is found in CWD: proceed without injection, no error, no mention.

Configuration Reference

KeyDefaultDescription
SCREENSHOT_DIRauto-discoveredFolder to scan for screenshots
SCREENSHOT_MAX_IMAGES4Max images per invocation (minimum 1)
SCREENSHOT_MAX_FILE_MB10Max file size in MB; files exceeding this are skipped
SCREENSHOT_STALENESS_MINUTES30Age threshold (minutes) for staleness warning

Platform Notes

PlatformDiscovery methodDefault path if unset
macOSdefaults read com.apple.screencapture location~/Desktop
Linux$XDG_SCREENSHOTS_DIR (rarely set)~/Pictures/Screenshots
WSLWindows %USERNAME% via cmd.exe, then $USER, then whoami/mnt/c/Users/<user>/Pictures/Screenshots
WindowsPowerShell GetFolderPath('MyPictures')%USERPROFILE%\Pictures\Screenshots

Image reading: Uses the Read tool. Claude Code and Augment Code both support image reading. Other platforms may vary — if images fail to load, confirm your platform supports image input.

iCloud on macOS: If screenshots are saved to iCloud Drive, the resolved path may be inside ~/Library/Mobile Documents/. Files may not be immediately readable due to sync latency. If listing succeeds but Read fails, wait a moment and retry, or move screenshots to a local folder.

Failure States

SituationResponse
SCREENSHOT_DIR path vanishedRe-run discovery, upsert .env with new path
No image files"No screenshots found in <path>."
All files exceed size limit"All selected screenshots exceed the SCREENSHOT_MAX_FILE_MB limit. Resize or save as PNG, or increase the limit in ~/.codex/.env."
Re-discovery also failsPrint: "Screenshot folder not found and auto-discovery failed. Set SCREENSHOT_DIR manually in ~/.codex/.env."
Read-only .envPrint path for manual addition, continue for session
HEIC unreadableSkip with PNG recommendation, continue with remaining files
compare with N=1Hard stop, prompt user to add count
Count > capWarn, truncate to cap
Count > availableUse all available, note shortfall
WSL username resolution failsStop, ask user to set SCREENSHOT_DIR manually
UNC path from Windows enterpriseWarn, ask user to set SCREENSHOT_DIR manually

Execution Traces

Trace A (/sp-ss 2 fix, first-discovery): No SCREENSHOT_DIR key → run macOS discovery (fallback ~/Desktop) → list 4 images, select 2 → read both → fix intent + project context injection (React+TS detected).

Trace B (/sp-ss 1 compare, hard-gate): Read cached SCREENSHOT_DIR from .env → list 6 images → hard gate: N=1 < 2 required → STOP with "compare requires N≥2".

Trace C (/sp-ss huh, stale path): Read stale SCREENSHOT_DIR (/Volumes/External, unmounted) → re-discover to ~/Desktop → atomically update .env via temp+grep+mv → list 3 images, staleness warning (47 min > 30 min threshold) → huh intent dispatch.

Companion Skills

  • systematic-debugging: For complex errors requiring root-cause investigation
  • feature-development: For building features visible in a screenshot
  • brainstorming: For exploring design directions suggested by a screenshot

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.