Build a Shortcut with a contract

Let’s build a shortcut with a real contract. It accepts image files, converts them to JPEG, and saves copies in a test folder. Same idea as the shell script from module one, in a different tool.

Open Shortcuts, create a new shortcut, and wire it like this:

receives: Images (from Quick Actions and the share sheet)
if there is no input: Stop and Respond ("no images received")
actions:
  1. Convert Image   -> to JPEG
  2. Save File       -> to ~/Pictures/prepared/, "Ask Where to Save" off
  3. Stop and Output -> the saved files

The three actions are the work. The two lines above them are the contract, and both live in the input header at the top of the editor.

Accept only what you handle

Set the accepted input type to images only. Everything else gets rejected at the door, instead of failing halfway through the actions.

This is the Shortcuts version of the if [[ ! -f "$1" ]] check from the shell script. Same idea, different place.

Decide what happens with no input

Stop and Respond is the honest choice for automation. It fails loudly instead of opening a file picker.

A shortcut that quietly waits for a human defeats the point. When a script calls it, nobody is there to pick a file. The shortcut just sits there.

Return something

Finish with Stop and Output so another process can receive the result. Without it the shortcut still works when you click it. But it returns nothing useful to a caller. In the next lesson we call it from the terminal, and that only works because of this action.

Test it

Use disposable images first. Keep the originals and choose a destination that cannot overwrite them.

Run it with one image. Then run it with the same image again. The second run tells you whether your Save File settings duplicate, overwrite, or rename on collision. You want to know that now, not after it happens to a real file.

Verify each run two ways. The destination folder contains the JPEG copies you expected. And the output preview at the bottom of the editor shows the files the shortcut returned.

If the destination is somewhere protected, the first run also triggers a permission prompt. Approve it once, on purpose.

Name it last

Rename the shortcut only after it passes the same input twice. The name is part of the interface. Scripts will call it by that exact string, so renaming it later breaks everything built on top.

I pick names that describe the output, like “Prepare Screenshot”. Six months from now, shortcuts list should still tell me what each one does.