Skip to content

dnviti/artcraft-skills / skills/lightcraft-photos

lightcraft-photos

Verified

Organise photo libraries and develop raw/JPEG photos non-destructively in LightCraft (ArtCraft's Lightroom-class photo library and raw developer, via the `lightcraft` MCP server (mcp__lightcraft__*) or `lightcraft-cli`). Use whenever the user mentions LightCraft or the lightcraft MCP tools, or asks to import, cull, rate, flag, colour-label, keyword, caption or search a photo library or shoot; build albums, stacks or smart albums; develop raw files (DNG, CR2/CR3, ARW, NEF, RAF, RW2, ORF, PEF) or JPEGs (exposure, white balance, highlights/shadows, tone curve, colour grading, B&W, crop/straighten, masks, spot removal, presets, profiles, HDR/panorama merge); sync edits across a shoot; batch develop/export web or print sizes, contact sheets, print layouts. Covers the library-first non-destructive workflow, render-and-verify, export and the mandatory show-and-approve phase. Pixel-level retouching, layers and compositing belong to photocraft-images; vector art to vectorcraft-illustration.

LightCraft photos

LightCraft is an open-source (alpha), non-destructive photo library and raw developer: library (albums, folders, stacks, ratings, flags, labels, keywords, smart search), develop (light, colour, curves, grading, detail, optics, geometry, masks, spots), presets/profiles, merge (HDR, panorama), export (JPEG, PNG, TIFF, WebP, AVIF, JPEG XL, PSD flat, DNG, original + XMP), contact sheets, print layouts, slideshows. Edits are a list of settings stored in the library catalog; the original files are never rewritten. You drive it with the lightcraft MCP server (headless engine) or with lightcraft-cli from Bash. This skill says what to do, in what order, and how to hand the result to the user.

A shoot deserves its own look, not the feed's. Culling and organising are bookkeeping; the develop look is where you will drift to the preset average: one stock look pushed over every frame, milky blacks, a heavy vignette. A look that belongs to these photos comes from a reference outside photo apps, a limit on which controls you touch, virtual-copy alternatives the user chooses between, and a viewer who did not develop them. The photographer's own look or reference wins.

  • Develop control ids, mask/crop/export params, search filters: references/command-catalog.md
  • Recipes (cull a shoot, quick develop, batch web export, B&W, sky mask, sync edits): references/recipes.md

0. Ground rules for the tools

MCP tools (names as mcp__lightcraft__<tool>): helpers import, query_photos, select_photos, list_controls, get_develop, set_develop, apply_preset, crop, render_preview, render_photo, export, doc_inspect, and the generic list_commands (= command_list), run_command (= command_run), command_batch. Every command is also a tool cmd_<id with . as _> (~376 of them, e.g. cmd_photo_rate): ignore those, use run_command. All tools are deferred: load the schemas you need with ToolSearch (select:mcp__lightcraft__run_command,mcp__lightcraft__list_commands,... or query +lightcraft, max_results 30) before calling them.

  • Discover before guessing. list_commands {filter:"mask."} (or "keyword.", "album.", "export.") returns id, label, params doc, enabled/disabled_reason. Never call it unfiltered (376 commands). The params doc is authoritative; the installed build (0.15.x) can differ from docs.
  • Photos are integer ids. Most develop commands act on the active photo (select_photos {ids, active}); set_develop/crop/export with an explicit id make that photo active and replace the selection. get_develop, render_photo, render_preview don't change the selection.
  • Coordinates (crop rects, mask points, strokes) are normalised 0..1, origin top-left.
  • Edits are undoable (edit.undo/edit.redo, history.list); a slider burst is one step.
  • Failures come back as isError:true with a readable message; a failed command changes nothing. Params are strict: unknown or malformed values are errors (e.g. crop.aspect wants "16x9", not "16:9"; develop.treatment takes {bw:true}; a wrong key like treatment is ignored and can toggle instead, so read back with get_develop).
  • Long operations (export of many photos, merge, previews) block in headless mode: pass sensible batches, and check activity.list when a desktop app is attached.

1. Library, persistence and file access: check this first (critical)

Default registration: claude mcp add --scope user lightcraft -- /usr/bin/lightcraft-cli mcp (no --library). Findings from the installed build (0.15.0):

  • No --library means an in-memory session (library.info -> "persistent": false). Imports, ratings, keywords and develop settings vanish when the MCP server exits. Fine for a one-off "develop this photo and export it"; wrong for culling or organising work that must last.
  • Persistent work needs a library directory: lightcraft-cli run --library DIR ... (CLI route, below) or an MCP started with --library DIR. A library is a folder with catalog.snap, catalog.log (append-only edit log), prefs.json, thumbnails; it references the photo files in place (import mode:add, the default). The app's default library is ~/Pictures/LightCraft Library (seeded with demo photos on first launch). Never create or touch libraries the user did not ask for: ask where the library should live, or whether the user already has one (~/Pictures/LightCraft Library, or the last one the app opened). Tests and scratch work use a library in a temp dir.
  • A library can be open in one process only (lock file; the error says "already open in ..."). So an MCP session started with --library blocks the CLI and the desktop app on that library, and the other way round. To work with a library the app has open, the app must run with --control PORT and the MCP/CLI must connect with --connect 127.0.0.1:PORT (not how the MCP is registered by default, so use the CLI route, below, when the user wants the library seen in the app).
  • File access: unlike PhotoCraft there are no automation roots: any path the OS user can read or write works (imports, export path, dir). Writes outside what the user can write give an OS "Permission denied". export refuses to overwrite a catalogued original or its XMP sidecar. Relative paths resolve against the server's working directory: always pass absolute paths.
  • Headless runs write nothing in ~/.config or ~/.cache (verified); settings folders only come from the desktop app (LIGHTCRAFT_CONFIG_DIR relocates it).
  • XMP sidecars are the only thing written next to originals, and only if auto-write is on (library.xmpPreferences {autoWrite}, off by default in a fresh library) or on request (photo.saveMetadataToFile). Ask before writing sidecars into the user's photo folders.

CLI route (persistent, scriptable, releases the library lock after each call):

LIB=/abs/path/to/library
lightcraft-cli run --library "$LIB" --import /abs/shoot \
  library.selectAll photo.setMeta 'addKeywords=["trip","2026"]' \
  library.select 'ids=[3]' develop.set control=light.exposure value=0.4 preset.apply id=lc.cinematic amount=60 \
  app.export path=/abs/out/p3.jpg longEdge=1600 quality=85

Each word without = starts a command, key=value pairs follow (JSON when parseable, '{json}' as a whole param object). One JSON line per command; exit status non-zero on a failure (--keep-going continues). --script FILE takes JSON lines {"command":id,"params":{...}}. Selection state does not survive between runs: select inside the same run. One-off: lightcraft-cli render IN -o OUT --set light.exposure=0.5 --preset lc.teal-orange --size 2000 develops and exports a single file with no library at all (good for "just develop this raw").

2. Workflow

  1. Brief: what is the job (cull, organise, develop one hero image, batch for web/print), which folder, which library, what output size/format, what must not change. Ask only what you cannot infer.
  2. Safe start: originals are never modified by develop; still, never import with mode:move (it removes the originals after copying) or copy unless the user asked for that, and never photo.rename (renames files on disk) or photo.deletePermanently / library.emptyRecentlyDeleted without explicit consent. photo.delete only moves to Recently Deleted (reversible).
  3. Organise first (sections 3 and recipe 1), develop second (section 4), export last.
  4. Look options before syncing a creative develop (skip for corrective edits, library-only jobs or a given look): name a reference outside photo apps (a painter's palette, a faded postcard, the real light of that place at that hour) and 1-2 limits (tone curve and white balance only, no saturation slider; one grading hue; at most one mask). Develop 2-3 virtual copies of the hero (photo.virtualCopy) that differ in tone, colour and contrast, put them in an album, show and open it (section 7), then ask with the multiple-choice question tool (AskUserQuestion in Claude Code; else a numbered list), multi-select for blends. Never pick for the user. This rule covers creative directions, while technical options may carry a labelled recommendation. Inside a subagent, return the options (album, virtual copy ids, preview paths, brief) to the orchestrator, which asks the user. Sync only the chosen look.
  5. Verify loop after each meaningful step (section 5).
  6. Show and approve (section 7), then the final export (section 6).

Scale the work: "brighten this photo" is set_develop + a preview, not a library project.

3. Library know-how (organise, cull, find)

  • Import: import {paths} (folders are scanned recursively, duplicates skipped, sidecars read). Returns imported ids, duplicates, failed (a missing path is reported in failed, not as an error). Check query_photos after importing mixed raw+JPEG folders: each file is a photo.
  • Cull fast: query_photos to list (id, file, size, rating, flag, edited, keywords); look at candidates with render_preview {id, max_side:900, format:"jpeg"} (small and cheap); then photo.flag {flag:"pick"|"reject"|"none", ids}, photo.rate {rating:0..5, ids}, photo.label {label:"red|yellow|green|blue|purple|none", ids}. Pass ids explicitly (without it the selection is used and advance may move it). Rejects are flags, not deletions. library.findSimilar {id} groups near-duplicates; stack.auto {gap} stacks bursts by capture time (preview:true first).
  • Metadata: photo.setMeta {ids, title, caption, creator, copyright, location, city, country, gps, keywords | addKeywords | removeKeywords}; keyword hierarchy via keyword.* (keyword.create, keyword.rename, keyword.merge, keyword.suggest). Keep keywords specific (subject, place, event), lower-case or consistently cased.
  • Albums: album.create {name, folder:false, addSelected}, album.addPhotos {id, ids}, smart albums via album.createSmart + album.setRules (album.ruleFields lists fields).
  • Search/filter (query_photos {filter}, or library.filter, which changes the app view): {rating:3, ratingOp:"atLeast"|"exactly"|"atMost", flag:"pick", label, keyword, camera, lens, edited, kind, date, text}. Note minRating is not a filter key (silently ignored). text takes the field syntax: rating:>3 flag:pick iso:>800 camera:x2 date:2026-04 keyword:mountains person:"Jane Doe". limit/offset page the result (default 200).
  • Source/sort: library.source {kind:all|picks|recentlyAdded|album|libraryFolder|missing, id}, library.sort {key, ascending}. These change the view only.
  • Missing files: library.missing, photo.relink, library.findMissing; never assume a moved folder means lost edits (edits live in the catalog).

4. Develop know-how (non-destructive, order of operations)

Controls are ids from list_controls (ranges in the catalogue): light.exposure (EV, -5..5), light.contrast/highlights/shadows/whites/blacks (-100..100), wb.temp (Kelvin 2000..50000 for raw; relative for JPEG) and wb.tint, color.vibrance/saturation, effects.texture/clarity/dehaze, vignette.*, grain.*, detail.sharpen*/detail.nr*, optics.*, geometry.*, crop.angle, mixer.<band>.hue|sat|lum, bw.<band>, grading.<zone>.hue|sat|lum. Set several at once with set_develop {values:{...}}; deep-merge any partial settings JSON (as in get_develop) with set_develop {settings:{...}, label}; reset with develop.resetControl/develop.resetSection/ develop.reset.

Order of operations (matches how the pipeline reads best and avoids fighting yourself):

  1. Geometry first: crop {rect:[x0,y0,x1,y1], angle} or crop.aspect {aspect:"4x5"}, crop.autoStraighten, geometry.upright {mode} for architecture. Crop is just settings; reset with crop {reset:true}.
  2. Profile/camera look (develop.profile {id:"lc.vivid"}, amount profile.amount), then white balance (develop.wb {mode:"auto"|"asShot"|"daylight"|..., temp, tint}; neutralise casts before stylising).
  3. Tone: develop.auto is a starting point (it can over-push: it gave contrast 68 on a plain gradient), then exposure, highlights/shadows, whites/blacks. Recover blown highlights with negative light.highlights (edge-aware, no halos) rather than lowering exposure.
  4. Colour: vibrance before saturation (vibrance protects skin); targeted work with the 8-band mixer.*; looks with grading.* (shadows/midtones/highlights wheels) or a preset at a reduced amount (presets scale 0..200 %: apply_preset {preset:"lc.teal-orange", amount:60}).
  5. Local: masks (mask.add {kind:"linear|radial|brush|sky|subject|background|luminanceRange| colorRange"} then mask.adjust {id, values:{exposure,...}}; combine with mask.addComponent {op: add|subtract|intersect}, mask.invert; paint with mask.brushStroke {points,size,feather,erase}; Object/Describe kinds need an optional SAM 3 model that is not bundled: they fail without it, tell the user instead of retrying). Spots: spot.findDust, spot.add {mode:"remove|heal|clone|fill", points, size}; redeye.add.
  6. Effects and detail last: clarity/texture/dehaze sparingly, then sharpening and noise reduction judged at 100 % crops (render_preview is downscaled; sharpening at full size is only visible in an export), then vignette/grain as style.
  7. B&W: develop.treatment {bw:true} then bw.* mix (darken skies with bw.blue negative) and grading for toning.
  • Sync across a shoot: develop one hero photo, develop.copy {groups} / develop.paste {ids, groups} or develop.sync (to the selection). Keep WB/exposure per photo, sync the look. Exclude crop and masks unless they truly apply (default copy excludes crop, masks, spot removal).
  • Versions and virtual copies: version.create {name} snapshots settings; photo.virtualCopy gives an independent edit of the same file (e.g. colour + B&W) without duplicating pixels.
  • Default tells (preset-feed looks; use only when the brief asks): lc.teal-orange or any look preset at full amount; clarity, dehaze and shadows pushed together into grunge; masked skies more saturated than the light on the ground; lifted, milky blacks on every frame; a heavy dark vignette by default; vibrance pumped until skin goes orange; one colour kept on a black-and-white frame; develop.auto or one preset at 100 % across a shoot shot in different light. Every slider you move should trace back to the brief, the reference or a limit.
  • Honesty: cosmetic and dust/blemish work is fine; do not alter photos to fake evidence.

5. Verify loop (mandatory)

After each major step:

  1. Numbers: get_develop (confirm the values landed on the right photo: the active-photo mix-up is the most common error), doc_inspect / library.state (selection, active, filter, undo label), query_photos (rating/flag/keywords/edited).
  2. Look: render_preview {id, max_side:1400, format:"jpeg"} returns an image you can see (png default, max_side up to 4096); render_photo {id, size, path} also saves a file (path must not be a catalogued original). Check clipped highlights/blocked shadows, halos around masks, banding in skies, skin tones, colour casts, over-sharpening, noise, crop framing and horizon.
  3. Compare with the original: render once before editing (or beforeAfter.* in the app); fix with edit.undo, develop.resetControl, or by adjusting the value; repeat.
  4. Batch checks: after a batch develop/sync, preview at least the first, a mid and the most extreme photo (darkest/brightest), not only the hero.
  5. Before exporting: right photos selected, crop/rotation as intended, rating/flag filters not hiding photos from a dir export (export {ids} is explicit and safest).
  6. Second opinion on the look (creative develops of a hero or shoot, before section 7): a fresh subagent with a clean context, not a fork, gets only before/after previews of the hero and of 3-4 synced photos, the reference and limits, and the tells in section 4. As a photo editor who did not develop them, it says what looks like a stock preset, where the look fails on particular photos (skin, skies, shadows), and any artefact, ranked by severity with a one-line fix direction; no praise. Fix the serious items; tell the user which ones you leave and why. Inside a subagent, return the critique inputs (preview paths, brief, tells) to the orchestrator, which starts the reviewer.

6. Save and export

  • Edits are saved in the library (--library DIR; each command is persisted to the catalog log); in-memory sessions save nothing: export or write XMP before the session ends.
  • Export export {path | dir, ids, format, longEdge|shortEdge|width+height|percent|megapixels, quality, colorSpace, bitDepth, metadata, naming, conflict, ppi, preset} (same as app.export):
    • Web: jpeg quality 82-88, longEdge 1600-2400, colorSpace:"srgb", metadata:"copyright" or "allExceptCamera" to strip location; webp/avif for smaller files.
    • Print: tiff 16-bit (bitDepth:16), colorSpace:"adobeRgb"/"proPhoto", longEdge:0 (full size), ppi:300; soft proofing is not available, say so.
    • Archive/hand-off to other apps: format:"original" (copy + XMP sidecar with the edits), dng (raw as DNG with edits embedded), rendereddng (baked 16-bit float DNG), psd (flat).
    • Default size when none is given is long edge 3000; longEdge:0 is full resolution; dontEnlarge defaults to true. limitKb fits a JPEG under a size. Presets: export.presets (e.g. "JPEG (Small)" 2048 q85, "JPEG (Large)" full q92, "Original + Settings").
    • Batch: dir with naming:"{name}-web" (tokens {name} {seq:3} {date:%Y%m%d} {title} {camera} {rating}...), conflict:"unique" (default) | overwrite | skip. Result lists every file with size and dimensions: report absolute paths.
    • export.contactSheet {path, paper:"a4", columns, rows, captions} for a PDF proof sheet; print.set / print.layout.autoLayout / print.exportPdf for print layouts.
    • HDR-edited photos (develop.hdr): hdr:true for gain-map JPEG / PQ AVIF.
  • Descriptive names (milan-0412-web.jpg), a dedicated output folder, never into the originals' folder unless asked; a catalogued original is refused by design.
  • Merge: merge.hdr, merge.panorama, merge.hdrPanorama write a DNG next to the first source file (so a write into the user's photo folder: say so first).

7. Show and approve (mandatory final phase)

Every task ends here, after the verify loop and before final exports. The MCP/CLI session is headless, so the user cannot see the work until the real app opens the library it was saved in.

  1. Save to a library the app can open: the edits must live in a persistent library (the user's own library when they asked for the work to be done there, otherwise a project library at a descriptive path such as <project>/<job>-lightcraft-library). If you worked in an in-memory MCP session, replay the final state with the CLI route (lightcraft-cli run --library DIR --import ...) or export the result and say that edits themselves were not kept. Make sure no MCP session holds the library lock (an MCP started with --library DIR does until it exits), otherwise the app cannot open it. Also write flat previews/deliverable candidates if useful. Note the full absolute paths.
  2. Open LightCraft on it, detached (verified: /usr/bin/lightcraft, lightcraft [OPTIONS] [FILES/FOLDERS...]; desktop entry ai.storyteller.lightcraft): setsid lightcraft --library /abs/path/library >/dev/null 2>&1 & Passing photo files or folders imports them into the opened library (so never pass the user's originals with a different library than intended; with no --library the app opens its last or default library, ~/Pictures/LightCraft Library, creating it with demo photos if absent). Associated types (desktop entry): JPEG, PNG, TIFF, WebP, HEIC/HEIF, DNG and the Sony ARW, Canon CR2/CR3, Nikon NEF, Fuji RAF, Olympus ORF, Panasonic RW2/RW, Pentax PEF raw MIME types; there is no LightCraft-specific project file or MIME type, the library folder is the project. If the user already has LightCraft running, a second launch on the same library fails with the lock message: tell them the library is open there and, if edits were made by the CLI meanwhile, to reopen/refresh it. Do not leave extra app instances you started running beyond the task if the user did not ask for the app.
  3. Stop and ask. Give the full library path (and the photo ids / album to look at) and ask the user to accept or describe changes. No final export, delivery in other sizes, sidecar writing or cleanup before explicit acceptance. Silence or a vague reaction is not acceptance. Unless the user asked up front for the export to be produced straight away, the final export happens after acceptance.
  4. Loop on changes: apply them (CLI route against the library, with the app closed or via --control), redo the verify loop for what changed, reopen/refresh, ask again.
  5. Inside a subagent (cannot talk to the user): do steps 1 and 2, then return the library path, the photo ids / output paths, a short summary of what was done, and state clearly that user approval is pending. The orchestrator asks the user and relays changes; the final export waits for acceptance.

8. Top gotchas

  • No --library = in-memory: nothing persists. A library is open in one process at a time.
  • Never import, create libraries or write sidecars in the user's real photo folders / ~/Pictures without being asked. import mode:move deletes originals after copying; photo.rename renames files on disk; photo.deletePermanently and library.emptyRecentlyDeleted are irreversible.
  • Develop acts on the active photo; library.select/select_photos first, then verify with get_develop.
  • develop.auto and presets are starting points; judge the preview and back off.
  • Raw support is uneven (see the app's raw parity notes): some cameras fall back to a neutral matrix or embedded JPEG preview (previewOnly in query_photos); tell the user instead of promising raw quality.
  • Object/Describe masks, face detection/recognition and AI denoise need optional models that are not installed; do not trigger downloads (*.models.download, segment.model.download) without asking.
  • edit.undo undoes the last action of any kind (ratings, metadata, albums, crop, develop): check the undo label in doc_inspect before undoing.
  • photo.moveToFolder, folder.create, photo.duplicate, photo.rename and merges write to disk next to the originals: only on request.
  • Unknown param keys are ignored by some commands and errors in others: read values back.
  • Preview size caps at 4096; judge sharpening/noise from an export crop at 100 %.
  • Do not leave test libraries or exports around; never delete user photos or libraries.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall