DEV Community: Alex @Bickov

I gave my agent a skill so it stops asking where my files are

Alex @Bickov — Tue, 07 Jul 2026 07:24:03 +0000

Claude Code skills are easy to write. The hard part nobody documents: how does the skill know where your app's files live on someone else's machine?

I hit this building a skill for my Mac screenshot app. The skill needs to read the latest capture. On my machine that folder is one path. On yours it's wherever you set it in preferences. Hardcode it and the skill breaks for everyone but me.

Here is the pattern that fixed it, in three parts.

What a skill is, in one paragraph

A skill is a small markdown file in ~/.claude/skills/. It tells Claude how to handle a class of requests. When your prompt matches, Claude reads the instructions and follows them, so you stop re-explaining the rules every session. Mine is a single SKILL.md, about 80 lines. You can read the whole thing in a minute: bickov/slimsnap-skill.

The discovery problem

Integrations between a desktop app and a terminal agent usually fail one of two ways. You hardcode a path, and it breaks the moment the user moves the folder. Or you push config into the agent side, and every install becomes a manual setup step.

The fix is a config file at a known location that the app owns:

~/.slimsnap/config.json

The app writes its save folder there on every launch. The skill reads it on every invocation. Change the folder in the app's preferences and the skill picks it up on the next capture. Nothing to update on the agent side.

Cursor does the same shape with workspace settings. Raycast extensions do it with preferences. It's rare in the app-plus-agent space mostly because apps don't think about agent integration yet.

What the skill does with it

Three steps on every invocation:

Read ~/.slimsnap/config.json to find the captures folder
Pull the newest capture and parse it. The file is structured JSON, bounding boxes and OCR text and annotations, so Claude reads it directly instead of burning tokens re-interpreting an image
Treat the user's callout text as the intent. If the arrow points at a gray button and the note says "match the brand blue," that text becomes the instruction. No guessing

The capture format is open, MIT licensed: bickov/slimsnap-schema. If you want a skill for Aider or Codex CLI that consumes the same files, nothing is in your way.

Trigger phrasing, the part I got wrong first

[Alex writes this section: 3 or 4 sentences on what description phrasing failed to trigger the skill and what finally worked]

Try the pattern

If you're building any tool that an agent should act on: pick a config path under the user's home folder, have the app own it and write it on launch, have the skill read it fresh every time. That's the whole trick.

The working example end to end: SlimSnap (free Mac app) plus the skill:

git clone https://github.com/bickov/slimsnap-skill ~/.claude/skills/slimsnap

Capture something broken, drag an arrow at it, type what you want changed, then in Claude Code: fix this from my screenshot.

Longer write-up of why the handoff is JSON and what's in the format: on my blog.

Do programmers even feel like programmers anymore?

Alex @Bickov — Thu, 02 Jul 2026 07:19:22 +0000

Saw a post from an 8-year dev this week. He said any junior with an agent now matches his output, and he feels no pride left in it. It got huge, because a lot of people quietly feel the same.

I read it from the other side. I'm a designer, not an engineer. For years "can you build this" meant "find someone technical and pray they stay interested." Usually they didn't. AI took the thing that hurt that dev and handed it to me.

Same shift. Loss from one seat, freedom from another.

I'm shipping a Mac app solo right now, as someone who can't write a backend from scratch. Two years ago that was a joke.

So I'm curious about the makers here. If you build for a living, does it still feel like your craft, or like something else now? Loss or relief?

The longest prompt you'll ever write is a screenshot

Alex @Bickov — Mon, 29 Jun 2026 06:49:14 +0000

I pasted a screenshot into Claude Code last week and it changed the wrong button. Not a crash, not a bad idea. It just picked the wrong element on a busy screen and edited that one.

A screenshot carries a whole screen of intent. To you it is obvious which thing you meant. To the agent it is a flat image it re-reads every turn, and on a dense UI it guesses.

What fixed it for me was marking the one element and handing over a small structured reference instead of the raw image:

{
  "element": "Save button",
  "text": "Save",
  "position": { "x": 0.82, "y": 0.12 },
  "intent": "keep it disabled until the form is valid"
}

That JSON is about 700 tokens. The raw screenshot is around 1,500 on Sonnet and Haiku, up to 4,784 on Opus, and it gets billed again on every turn.

So the screenshot is the longest prompt you will ever write. The same screenshot, marked and structured, is one of the shortest.

I built a small free Mac tool around this idea (SlimSnap). The tool is not the point though. The point is the agent should not have to guess which element you meant. Mark it, and the guessing goes away.

Your AI agent is guessing which element you meant

Alex @Bickov — Thu, 18 Jun 2026 07:48:29 +0000

Coding agents are good at execution and bad at reading a flat image. Give one a screenshot of a busy UI and it has to infer, from pixels alone, which of six similar buttons you were pointing at. Half the time it picks wrong, you re-prompt, and you have burned a round trip plus a few thousand tokens on the image.

I started handing the agent a structured capture instead. Same screenshot, but the element I care about and what I want done with it are explicit:

json{
  "target": { "label": "Save draft", "region": [820, 140, 96, 32] },
  "intent": "disable until the form is valid",
  "note": "this is the secondary button, not the primary Save"
}

The agent no longer guesses. It acts on the element I named. And the payload is roughly 700 tokens versus the several thousand a raw screenshot costs, so longer sessions stay inside context.

Structure beats pixels when the next reader is a machine. The picture carries everything at once and signals nothing. A few fields carry the one thing that matters.

Curious whether anyone here has hit the same wall feeding screenshots to agents, and what you did about it.

Flag for voice pass

"good at execution and bad at reading a flat image" is a balanced parallel, the exact anti-AI pattern. Rephrase in your voice.
"The picture carries everything at once and signals nothing" reads clever/templated. Keep only if it is genuinely how you'd say it.
The closing question is a soft generic CTA. Replace with a sharper, real question if you have one.
Tags suggestion: #claude #ai #productivity #webdev (same as last republish).
The JSON is illustrative. Match it to SlimSnap's real schema field names before posting so it is accurate.

Why I feed my coding agent JSON instead of screenshots

Alex @Bickov — Tue, 16 Jun 2026 13:00:00 +0000

Claude Code can read images. So can Cursor. So can ChatGPT. I built SlimSnap anyway, and the reason is boring: the image is the wrong shape for the job.

Here is the boring version. The job is "show the agent what is on my screen and have it act." For that job a retina screenshot pasted into a coding session is somewhere between expensive and lossy, depending on how much you care about your token budget, your context window, and the agent acting on the right thing.

The token math

A screenshot pasted to Claude as a vision input is downscaled and billed at the API's per-image cap: about 1,568 tokens on Sonnet and Haiku (the models Claude Code uses by default), up to 4,784 tokens on Opus 4.7 and 4.8. Pasted to Codex CLI (which runs on OpenAI's GPT-4o), a typical 1440x900 screenshot in high detail mode runs about 1,105 tokens. Pasted to Gemini CLI on Gemini 2.5, the same image is about 1,548 tokens. The same screen, turned into a SlimSnap JSON document, runs about 700 tokens. That JSON contains the elements, their normalized bounding boxes, their extracted colors, and the OCR text for each.

About 55 percent fewer than Sonnet or Gemini, 37 percent fewer than Codex, up to 85 percent fewer than Opus, per turn. And the only representation with structured intent the agent can act on.

Representation	Per-turn tokens
Screenshot on Opus 4.7 / 4.8 (max billed)	~4,784
Screenshot on Sonnet / Haiku (max billed)	~1,568
Screenshot on Gemini 2.5	~1,548
Screenshot on Codex CLI / GPT-4o	~1,105
Same screen as SlimSnap JSON	~700

For a one-shot question that is a curiosity. For the way I actually use a terminal coding agent, which is a long iterative session where I show it the page state every few prompts, it stops being a curiosity. Twenty turns of screenshots on Sonnet burns about 31k tokens of vision before you've said anything. Twenty turns on Codex CLI is about 22k. On Opus 4.7+ it is about 96k. Twenty turns of SlimSnap JSON is 14k. On a 200k context window, that is the difference between finishing the refactor and getting compacted out mid-session.

If you are running an agent all day, the bill matters. If you are running it on a tough refactor, the context matters more.

Structure beats pixels

The token math is the part that wins HN comments. The part that actually matters to whether the agent is helpful is structure.

When you paste a screenshot, the agent has to look at pixels and infer everything: what is a button, what is text, what color is what, what label belongs to what input, where the user is pointing. It does this every turn, because raw pixels are not persistent reasoning state. If you ask a follow-up six prompts later, the agent goes back to the pixels. (Why it sees rather than reads: Claude doesn't OCR your screenshot, it interprets it.)

When you paste structured JSON, the agent reads facts. Element e4 is a button, bbox [0.34, 0.60, 0.32, 0.07] normalized, color #3B82F6, OCR text "Sign up". The next turn it does not re-interpret pixels, it references e4. The reasoning is grounded in the same primitives the next turn will use.

json{
  "schema_version": "1.0",
  "captured_at": "2026-05-19T18:17:46Z",
  "screen": { "title": "Create your account", "app": "Safari" },
  "image": { "width_px": 1440, "height_px": 900, "file": "signup.png" },
  "elements": [
    { "id": "e1", "type": "label", "value": "Create your account",
      "bbox": [0.34, 0.18, 0.32, 0.06] },
    { "id": "e2", "type": "input", "value": "Email",
      "bbox": [0.34, 0.34, 0.32, 0.07] },
    { "id": "e3", "type": "input", "value": "Password",
      "bbox": [0.34, 0.46, 0.32, 0.07] },
    { "id": "e4", "type": "button", "value": "Sign up",
      "bbox": [0.34, 0.60, 0.32, 0.07], "color": "#3B82F6" }
  ],
  "estimated_tokens": 712
}

Annotations carry the same property. A red rectangle in a PNG is a red rectangle. A red rectangle in SlimSnap JSON has an intent field, a target_ref pointing at the element it overlaps, and an optional callout string. The agent does not have to guess which input I am pointing at. The schema says: this arrow targets e4, intent is highlight, callout is "this one is misaligned."

Pasting the image and saying "fix the misaligned input" makes the agent guess which input. Pasting the JSON makes the agent act, because the guess is already collapsed.

Why I built a skill instead of a slash command

Once the capture is structured JSON, the rest is easy. SlimSnap writes a tiny config file at ~/.slimsnap/config.json on every startup and settings change. It contains the default save folder and the filename pattern. Nothing else.

json{
  "schema_version": "1.0",
  "default_save_folder": "/Users/alex/Documents/SlimSnap",
  "filename_pattern": "{title}-{timestamp}"
}

The Claude Code skill (free, MIT, separate repo at github.com/bickov/slimsnap-skill) reads that config, lists the save folder, loads the latest JSON file, and parses it into the agent's working context. There is no upload step. There is no slash command to remember. There is no "here is a screenshot." I press the global shortcut, annotate, hit Save, type "fix this" in Claude Code, and the agent already has the structured capture loaded.

I went with a skill instead of a CLI tool or a Claude Code plugin because skills auto-trigger. The user does not invoke them, the agent does, when the prompt looks like the skill's purpose. "What's in my latest SlimSnap capture?" triggers it. So does "fix the misaligned input from my last screenshot." The skill is invisible until it is useful.

This is the part I want to be obvious to anyone building on top of Claude Code: the contract between the desktop app and the agent is the config file, not a hardcoded path. The skill discovers the save folder. If you move your captures, the skill follows. If you build a different consumer (a CLI, a VS Code extension, a different agent), it reads the same config and works.

The open schema is the actual product

SlimSnap is a Mac app and it is free at launch. The thing that will outlast the app is the schema. It is published as a separate MIT repo at github.com/bickov/slimsnap-schema. JSON Schema 2020-12, two examples, a README that explains every field.

The reason this matters: the most common reaction to a new desktop tool from a one-person shop is "what if you disappear." If the schema is open and the consumer is a skill anyone can fork, the answer is "your captures still work, your skill still works, build a different annotator if you want." The data is not locked to the app.

I am not pretending this makes SlimSnap an open-source project. The desktop app is closed. The schema and the skill are open. That is the smallest set of things I can give away and still let people invest in the workflow without trusting me forever.

What this is not

It is not a Claude Code replacement. Claude Code still reads images fine. If you paste a screenshot once for a one-off question, do that. The case for converting to JSON is the case for a workflow: you do this many times a day, you want the agent to be cheap and precise, and you want a clean handoff between the capture and the agent.

It is also not for backend-only work. If you are refactoring a Go service you do not need to show Claude Code your screen. SlimSnap is sharpest for frontend, design-to-code, and bug-reproduction work, where you constantly need to point at something visual and have the agent reason about it.

If that is your loop, the tool, the skill, and the schema are at slimsnap.ai.