skills/specs/001-screenshot-analysis/quickstart.md

Quickstart: Screenshot Analysis Skill

Feature: 001-screenshot-analysis
Target: Developers implementing or testing the screenshot analysis skill

Goal

Get the screenshot analysis skill running in under 5 minutes for local development and testing.

---

Prerequisites

Required:

• Bash 4.0 or later
• GNU coreutils (find, stat, sort, test)
• jq (JSON processor)

Optional (for testing):

• bats-core (bash testing framework)
• Sample screenshot files

Check Prerequisites:

# Check bash version (need 4.0+)
bash --version | head -1

# Check jq availability
jq --version

# Check bats (optional, for testing)
bats --version

Install Missing Tools:

# Ubuntu/Debian
sudo apt install jq bats

# Fedora
sudo dnf install jq bats

# NixOS (add to environment.systemPackages or use nix-shell)
nix-shell -p jq bats

---

Quick Setup

Step 1: Create Skill Directory Structure

# From repository root
cd skills
mkdir -p screenshot-analysis/{scripts,templates,examples}
cd screenshot-analysis

Step 2: Create Helper Scripts

Create the four core scripts from the script interface contract:

File: scripts/find-latest-screenshot.sh

#!/usr/bin/env bash
set -euo pipefail

DIR="${1:-$($(dirname "$0")/load-config.sh)}"

[[ -d "$DIR" ]] || { echo "Error: Directory not found: $DIR" >&2; exit 1; }
[[ -r "$DIR" ]] || { echo "Error: Directory not readable: $DIR" >&2; exit 1; }

find "$DIR" -maxdepth 1 -type f \( -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" \) \
    -exec stat -c '%Y %n' {} + 2>/dev/null | sort -rn -k1,1 -k2,2 | head -1 | cut -d' ' -f2-

File: scripts/load-config.sh

#!/usr/bin/env bash
set -euo pipefail

DEFAULT_DIR="$HOME/Pictures/Screenshots"

# Check for config files
for config in "$HOME/.config/opencode/skills/screenshot-analysis/config.json" \
              "$HOME/.claude/skills/screenshot-analysis/config.json"; do
    [[ -f "$config" ]] || continue
    
    if command -v jq &>/dev/null; then
        CUSTOM_DIR=$(jq -r '.screenshot_dir // empty' "$config" 2>/dev/null || true)
        if [[ -n "$CUSTOM_DIR" ]]; then
            echo "${CUSTOM_DIR/#\~/$HOME}"
            exit 0
        fi
    fi
done

echo "$DEFAULT_DIR"

Make scripts executable:

chmod +x scripts/*.sh

Step 3: Create SKILL.md

File: SKILL.md

---
name: screenshot-analysis
description: Automatically find and analyze recent screenshots without typing file paths. Use when user requests screenshot analysis.
---

# Screenshot Analysis Skill

Automatically locates the most recent screenshot from ~/Pictures/Screenshots.

## When to Use

- "look at my last screenshot"
- "analyze my recent screenshot"
- "what's in my latest screenshot"
- "show me the previous screenshot"

## Process

1. Load screenshot directory:
   ```bash
   SCREENSHOT_DIR=$(~/.claude/skills/screenshot-analysis/scripts/load-config.sh)

2. Find latest screenshot:

   SCREENSHOT_PATH=$(~/.claude/skills/screenshot-analysis/scripts/find-latest-screenshot.sh "$SCREENSHOT_DIR")
   

3. Check if screenshot found:

   if [[ -z "$SCREENSHOT_PATH" ]]; then
       echo "No screenshots found in $SCREENSHOT_DIR"
       exit 0
   fi
   

4. Pass screenshot path to image analysis and display result.

Requirements

• Bash environment with find, stat, sort
• jq for JSON config parsing
• Screenshots directory readable

### Step 4: Create Example Config

**File**: `templates/config.json`
```json
{
  "screenshot_dir": "~/Pictures/Screenshots"
}

---

Testing

Manual Test

# Create test directory with sample screenshots
mkdir -p ~/Pictures/Screenshots
touch ~/Pictures/Screenshots/test-{1,2,3}.png

# Test find-latest-screenshot.sh
./scripts/find-latest-screenshot.sh

# Expected output: Path to most recently created/modified file
# Example: /home/user/Pictures/Screenshots/test-3.png

Unit Test (with bats)

File: tests/skills/screenshot-analysis/unit/test-find-latest.bats

#!/usr/bin/env bats

setup() {
    TEST_DIR="$(mktemp -d)"
    export TEST_DIR
    
    # Create test screenshots
    touch -t 202501010900 "$TEST_DIR/old.png"
    touch -t 202501011200 "$TEST_DIR/latest.png"
}

teardown() {
    rm -rf "$TEST_DIR"
}

@test "finds latest screenshot" {
    result=$(./scripts/find-latest-screenshot.sh "$TEST_DIR")
    [[ "$result" == "$TEST_DIR/latest.png" ]]
}

Run tests:

# From repository root
bats tests/skills/screenshot-analysis/unit/

---

Integration with Agents

Deploy to Claude Code

# Symlink for development
ln -s $(pwd)/skills/screenshot-analysis ~/.claude/skills/screenshot-analysis

# Or copy for testing
cp -r skills/screenshot-analysis ~/.claude/skills/screenshot-analysis

Deploy to OpenCode

# Symlink for development
ln -s $(pwd)/skills/screenshot-analysis ~/.config/opencode/skills/screenshot-analysis

# Or copy for testing
cp -r skills/screenshot-analysis ~/.config/opencode/skills/screenshot-analysis

# Ensure opencode-skills plugin is enabled in ~/.config/opencode/config.json

Test with Agent

Claude Code / OpenCode:

1. Take a screenshot (or create a test file in ~/Pictures/Screenshots)
2. Ask the agent: "look at my last screenshot"
3. Verify the agent finds and analyzes the file without asking for the path

---

Troubleshooting

Scripts Not Executable

Symptom: Permission denied when running scripts

Solution:

chmod +x skills/screenshot-analysis/scripts/*.sh

---

jq Not Found

Symptom: Warning: jq not found, using default directory

Solution: Install jq (see Prerequisites section) or accept default directory behavior

---

No Screenshots Found

Symptom: Empty output from find-latest-screenshot.sh

Check:

# Verify directory exists
ls -la ~/Pictures/Screenshots

# Create test screenshot
touch ~/Pictures/Screenshots/test.png

# Retry script
./scripts/find-latest-screenshot.sh

---

Symlinks Not Ignored

Symptom: Script returns symlinked files

Debug:

# Check if symlinks present
find ~/Pictures/Screenshots -type l

# Verify -type f flag in script
grep "type f" scripts/find-latest-screenshot.sh

Expected: Script uses find -type f which excludes symlinks

---

Next Steps

1. Implement remaining scripts:

   • find-nth-screenshot.sh (P2 feature)
   • filter-by-time.sh (P2 feature)

2. Write comprehensive tests:

   • Edge cases (empty directory, permissions, symlinks)
   • Performance tests (1000+ files)

3. Create README.md:

   • User-facing documentation
   • Installation instructions
   • Usage examples

4. Add examples:

   • Example agent interactions
   • Screenshot of skill in action

---

Development Workflow

Branch Strategy: Feature is developed on 001-screenshot-analysis branch

File Organization:

specs/001-screenshot-analysis/    # Planning docs (you are here)
skills/screenshot-analysis/       # Implementation
tests/skills/screenshot-analysis/ # Tests

Iterate:

1. Update scripts based on testing
2. Run tests (bats tests/skills/screenshot-analysis/unit/)
3. Test with real agent
4. Commit incremental progress

---

Reference Documentation

• Specification - Complete feature requirements
• Implementation Plan - Technical architecture
• Research - Technology decisions
• Data Model - Data structures
• Script Interface Contract - API specifications

---

Success Criteria Checklist

• Scripts are executable and have proper shebang
• find-latest-screenshot.sh returns correct file
• Config loading works (with and without config file)
• Symlinks are excluded
• Timestamp tiebreaker works (lexicographic ordering)
• Error messages are clear and actionable
• Performance: <1s for 1000 files
• Unit tests pass (if bats available)
• Agent can invoke skill via natural language
• No file paths required from user

When all checked: Skill is ready for implementation phase (/speckit.implement)