setup-ss

What this skill does

<purpose>
Configure the screenshotr plugin. Verify the environment, gather preferences, and write a config file.
</purpose>

<steps>

  <step id="check-existing-config" number="1">
    <description>Check for Existing Config</description>

    <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>
  </step>

  <step id="verify-environment" number="2">
    <description>Verify Environment</description>

    <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>
  </step>

  <step id="gather-preferences" number="3">
    <description>Gather Preferences</description>

    <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>
  </step>

  <step id="write-config-file" number="4">
    <description>Write Config File</description>

    <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>
  </step>

  <step id="confirm" number="5">
    <description>Confirm</description>

    <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>
  </step>

</steps>