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**:
```bash
# 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**:
```bash
# 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

```bash
# 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](./contracts/script-interface.md):

**File**: `scripts/find-latest-screenshot.sh`
```bash
#!/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`
```bash
#!/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**:
```bash
chmod +x scripts/*.sh
```

### Step 3: Create SKILL.md

**File**: `SKILL.md`
```markdown
---
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:
   ```bash
   SCREENSHOT_PATH=$(~/.claude/skills/screenshot-analysis/scripts/find-latest-screenshot.sh "$SCREENSHOT_DIR")
   ```

3. Check if screenshot found:
   ```bash
   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

```bash
# 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`
```bash
#!/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**:
```bash
# From repository root
bats tests/skills/screenshot-analysis/unit/
```

---

## Integration with Agents

### Deploy to Claude Code

```bash
# 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

```bash
# 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**:
```bash
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**:
```bash
# 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**:
```bash
# 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](./spec.md) - Complete feature requirements
- [Implementation Plan](./plan.md) - Technical architecture
- [Research](./research.md) - Technology decisions
- [Data Model](./data-model.md) - Data structures
- [Script Interface Contract](./contracts/script-interface.md) - 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`)