setup-ss

Configure the screenshotr plugin. Verify the environment, gather preferences, and write a config file. Check for Existing Config

<load-config>
  <action>Read `.claude/screenshotr.local.md` if it exists.</action>
  <if condition="config-found">Tell the user their current settings and ask if they want to reconfigure.</if>
  <if condition="arguments-contain-reconfigure">Skip the prompt and proceed to reconfigure.</if>
</load-config>

Verify Environment

<action>Run the following checks.</action>

<validate name="macos">Run `uname -s` -- must return "Darwin". If not, tell the user this plugin only works on macOS and stop.</validate>
<validate name="screencapture">Run `which screencapture` -- must be available. If not, something is very wrong with their macOS install.</validate>
<validate name="sips">Run `which sips` -- must be available. Same as above.</validate>
<validate name="python3-quartz">Run `python3 -c "import Quartz"` (optional). If this fails, note that window capture by app name will use a JXA fallback (slightly less reliable). Not a blocker.</validate>

<action>Report the results briefly.</action>

Gather Preferences

<action>Use AskUserQuestion for each setting.</action>

<ask-user-question>
  <question>Output directory -- Where should screenshots be saved?</question>
  <option>`./screenshots` (relative to project root) -- recommended</option>
  <option>`~/Desktop`</option>
  <option>`~/Screenshots`</option>
  <option-with-text-input>Custom path</option-with-text-input>
</ask-user-question>

<action>Create the directory with `mkdir -p` after the user chooses.</action>

<ask-user-question>
  <question>Default format:</question>
  <option>png (default, lossless)</option>
  <option>jpg (smaller files)</option>
  <option>heic (efficient, macOS-native)</option>
  <option>pdf (for documents)</option>
</ask-user-question>

<ask-user-question>
  <question>Naming convention -- How should screenshot files be named?</question>
  <option>"descriptive" -- Claude generates a kebab-case name from context (e.g., `finder-preferences-window.png`)</option>
  <option>"timestamp" -- automatic timestamp (`screenshot-2025-01-15-143022.png`)</option>
  <option>"both" -- descriptive name with timestamp suffix (`finder-preferences-143022.png`)</option>
</ask-user-question>

<ask-user-question>
  <question>Include window shadow:</question>
  <option>No (recommended, cleaner screenshots)</option>
  <option>Yes</option>
</ask-user-question>

<ask-user-question>
  <question>Play capture sound:</question>
  <option>No (recommended, silent operation)</option>
  <option>Yes</option>
</ask-user-question>

<ask-user-question>
  <question>Default delay -- Seconds to wait before capturing:</question>
  <option>0 (immediate, recommended)</option>
  <option>1</option>
  <option>2</option>
  <option>3</option>
</ask-user-question>

<ask-user-question>
  <question>Default max dimension -- Automatically resize screenshots to a max dimension?</question>
  <option>None -- keep original resolution</option>
  <option>1280 -- good for documentation</option>
  <option>1920 -- good for presentations</option>
  <option>Ask each time</option>
</ask-user-question>

<constraint>If they choose a number, set `default_max_dimension` to that number. If "None", set to `null`. If "Ask each time", set to `"ask"`.</constraint>

Write Config File

<action>Ensure `.claude/` directory exists, then write `.claude/screenshotr.local.md`.</action>

<write path=".claude/screenshotr.local.md">

<template name="screenshotr-config">

```markdown
---
output_dir: "./screenshots"
default_format: png
naming: descriptive
include_shadow: false
play_sound: false
default_delay: 0
default_max_dimension: null
---

# screenshotr Configuration

This file was generated by `/setup-ss`. Run it again to reconfigure.

Settings are used by the capture, screenshot, and list-windows skills.
```

</template>
</write>

Confirm

<completion-message>
Config saved! Available skills:

- `/capture-ss` -- capture a screenshot with full control over target, format, and post-processing
- `/list-windows` -- list open windows and their IDs
- The `screenshot` skill can be invoked automatically by Claude when context suggests a screenshot is needed
</completion-message>