github-screenshot git:20261016.04e815bA

Immutable. This exact content never changes and is served at /api/v1/blob/b26bda358dfa7bec.

---
name: github-screenshot
description: >
  Generates GitHub-ready image markdown for screenshots using raw.githubusercontent.com URLs via
  generate-github-image-markdown.sh. Use whenever a PR, issue, or doc needs an image. Trigger on:
  "add a screenshot to this PR", "embed image in issue", "attach screenshot", "add screenshot to
  docs".
---

# GitHub Screenshot Helper

## When to Use This Skill

Use this skill when:
- Adding screenshots to PR descriptions
- Including images in GitHub issues
- Documenting features with screenshots
- Creating visual documentation in markdown

## Setup

This skill wraps a local `generate-github-image-markdown.sh` script. Update the path below to match your own installation before using.

## Directory convention

When the image is being committed purely so it can render in an issue/PR body (not an existing app asset the user is pointing you at), commit it under a top-level `github-screenshots/<topic-or-issue>/` directory — e.g. `github-screenshots/hover-text-invisible/before-hover.png`. The name says what these files are for: throwaway evidence for a GitHub body, not app screenshots or fixtures, so they're easy to find and prune later without touching anything else in the repo. Don't reuse a generic `screenshots/` dir for this — that name doesn't self-document, and it collides with whatever ad-hoc convention a given repo might already have for actual app screenshots.

If the target repo already has an established convention for this (check with the user or look for precedent — e.g. `git log --diff-filter=A --name-only --all | grep -iE 'screenshot'`), follow that instead of introducing a second one.

## What This Skill Does

Runs your `generate-github-image-markdown.sh` script to:
- Generate proper raw.githubusercontent.com URLs
- Create markdown with alt text and captions
- Handle git repository detection automatically
- Include helpful comments with local paths

## Usage Flow

### Step 1: Gather Information

Ask the user for:
1. **Image path** (required) - relative or absolute
2. **Alt text** (optional) - defaults to "Screenshot"
3. **Caption** (optional) - italicized description below image

### Step 2: Run the Script

Execute:
```bash
~/tools/screenshots/generate-github-image-markdown.sh \
  "$IMAGE_PATH" \
  "$ALT_TEXT" \
  "$CAPTION"
```

**Permission pattern needed** (update path to match your setup):
```
Bash(~/tools/screenshots/generate-github-image-markdown.sh:*)
```

### Step 3: Present the Result

Show the generated markdown to the user:

```markdown
## Generated Screenshot Markdown

```markdown
![Alt Text](https://raw.githubusercontent.com/user/repo/branch/path/image.png)

*Caption text*

<!-- GitHub URL: https://raw.githubusercontent.com/... -->
<!-- Local path: ./github-screenshots/image.png -->
```
```

Then ask: "Should I insert this somewhere, or just copy it?"

### Step 4: Optional Insertion

If user wants it inserted:
- Ask where to insert (e.g., "in the PR description I'm writing")
- Use Edit tool to insert at appropriate location
- Confirm insertion complete

## Example Interaction

**User:** `/github-screenshot`

**Claude:**
```
I'll help you generate GitHub screenshot markdown.

What's the image path?
```

**User:** `./github-screenshots/dashboard-before.png`

**Claude:**
```
Alt text for the screenshot? (default: "Screenshot")
```

**User:** `Dashboard before refactor`

**Claude:**
```
Optional caption? (press enter to skip)
```

**User:** `Shows the original dashboard layout`

**Claude:** *Runs script and presents result*
```markdown
## Generated Screenshot Markdown

![Dashboard before refactor](https://raw.githubusercontent.com/user/repo/main/github-screenshots/dashboard-before.png)

*Shows the original dashboard layout*

<!-- GitHub URL: https://raw.githubusercontent.com/user/repo/main/github-screenshots/dashboard-before.png -->
<!-- Local path: ./github-screenshots/dashboard-before.png -->

Would you like me to insert this somewhere?
```

## Error Handling

### File Not Found
If image doesn't exist:
```
❌ Error: Image file not found at ./github-screenshots/missing.png

Please check the path and try again.
```

### Not in Git Repository
If script can't detect git repo:
```
⚠️ Warning: Couldn't generate GitHub URL (not in a git repository)

Generated markdown with relative path instead:
![Alt Text](./github-screenshots/image.png)

Note: This may not display correctly in GitHub
```

### Script Not Found
If the script is missing:
```
❌ Error: Screenshot script not found at expected location.

Please verify the script exists at the path configured in this skill,
or update the path in Step 2 to match your installation.
```

## Common Use Cases

### PR Description with Screenshot
```
User: "Add this screenshot to the PR description"
Claude: [runs skill, gets markdown, inserts into PR description being drafted]
```

### Multiple Screenshots
```
User: "Add 3 screenshots"
Claude: [runs skill 3 times, collecting all markdown, then inserts all at once]
```

### Quick Copy
```
User: "Just generate the markdown, I'll paste it myself"
Claude: [runs skill, presents markdown, doesn't insert anywhere]
```

## Integration with Your Workflow

This skill encodes the full screenshot workflow — you just invoke it instead of remembering the script path, argument order, and permission pattern every time.

## Notes

- This skill wraps a local script
- The script handles all the git complexity (remote detection, branch detection, path conversion)
- Permission pattern is encoded in the skill, so you don't need to remember it
- Works in any git repository, automatically detects repo details