From d8e062e8502ec0fdde08c441c95d898e3a87fa80 Mon Sep 17 00:00:00 2001 From: Max <112043822+Maxaubert@users.noreply.github.com> Date: Fri, 9 Oct 2026 21:51:07 +0200 Subject: [PATCH] feat(skill): tiny cheat-sheet skill that triggers on casual requests SKILL.md is now a short map from what people say to the command to run, with a description listing everyday phrasings. Event, error-code and safety detail moved to reference.md, which agents read only when needed. Version 0.8.3. Closes #47 Co-Authored-By: Claude Opus 5.5 --- package-lock.json | 4 +- package.json | 2 +- resources/skill/filesmith/SKILL.md | 81 ++++++-------------------- resources/skill/filesmith/reference.md | 21 +++++++ 4 files changed, 43 insertions(+), 65 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5e06868..543c727 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "filesmith", - "version": "0.8.1", + "version": "0.8.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "filesmith", - "version": "0.8.1", + "version": "0.8.3", "hasInstallScript": true, "license": "MIT", "devDependencies": { diff --git a/package.json b/package.json index b4ad47c..4782a72 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "filesmith", - "version": "0.8.1", + "version": "0.8.3", "description": "A desktop file toolkit: convert, compress, resize, upscale, remove backgrounds, and PDF tools.", "author": "Max", "license": "MIT", diff --git a/resources/skill/filesmith/SKILL.md b/resources/skill/filesmith/SKILL.md index 0b45ebb..729ec93 100644 --- a/resources/skill/filesmith/SKILL.md +++ b/resources/skill/filesmith/SKILL.md @@ -1,75 +1,32 @@ --- name: filesmith -description: Use when the user asks to convert, compress, resize, upscale or remove the background of files, generate an image, or merge, split or extract from PDFs on this Windows machine - runs the local Filesmith CLI, never overwrites. +description: Use when the user wants to do something to files on this PC, even phrased casually ("compress this image", "shrink this video", "make this a webp", "convert to jpg/pdf/mp4", "resize to 1920", "upscale this", "remove the background", "make me an image of...", "merge/split these PDFs", "pull the text out of this PDF"). Runs the local Filesmith CLI; never overwrites originals. metadata: filesmith-version: {{VERSION}} --- -# Filesmith CLI +# Filesmith -Filesmith is installed on this machine. Its command line runs the app's own engine and bundled tools (ffmpeg, ImageMagick, mutool, 7-Zip, LibreOffice, Ghostscript, Real-ESRGAN), works offline except for the AI tools' one-time setup, and writes NEW files next to each source (or into `--out`). It never overwrites anything. +Local file toolkit on PATH as `filesmith` (full path if not found: `{{FILESMITH}}`). It writes NEW files next to each source, or into `--out `, and never overwrites. Run it from the Bash tool and always add `--json`. -## Run it +| User says | Run | +| ----------------------------- | ------------------------------------------------------ | +| compress / shrink / smaller | `filesmith compress "" --json` | +| convert / make it a X | `filesmith convert "" --to webp --json` | +| resize / smaller dimensions | `filesmith resize "" --width 1920 --json` | +| upscale / enlarge / sharpen | `filesmith upscale "" --factor 2 --json` | +| remove / cut out background | `filesmith removebg "" --json` | +| make / generate an image | `filesmith generate "" --json` | +| merge / split / text from PDF | `filesmith pdf merge\|split\|extract-text "" --json` | +| what can it do / is it set up | `filesmith formats --json`, `filesmith doctor --json` | -`filesmith` is on PATH. If the shell cannot find it (a session started before Filesmith was installed), use the full path: `{{FILESMITH}}`. - -```bash -filesmith convert "photo.heic" --to jpg --json -filesmith compress "talk.mp4" --codec h265 --scale 50 --json -filesmith resize "hero.png" --width 1920 --json -filesmith upscale "old.jpg" --factor 2 --json -filesmith removebg "product.jpg" --fill white --json -filesmith generate "a red kettle on a table" --count 2 --json -filesmith pdf merge "a.pdf" "b.pdf" --json # pages in argument order -filesmith pdf split "thesis.pdf" --pages 1-3,10 --json -filesmith formats --json # every --to value, option and model -filesmith doctor --json # what is installed, what is missing -``` - -Every command has `--help`. Every flag, event field and error code: [reference.md](reference.md). +Many files: pass several paths, a glob (`"*.png"`) or a folder (`--recursive` for subfolders). Add `--help` to any command for its options. ## Rules -- **Always pass `--json`** and read stdout one JSON object per line. Ignore stderr. -- **Dry run first** (`--dry-run`) for bulk work (more than a handful of files, globs, folders, `--recursive`) and for anything slow or large (upscale, generate, setup). Show the user the planned outputs, then run the same command without `--dry-run`. Planned names are predictions; report the real names from the `done` events. -- **Quote every path.** In cmd a `%` inside an argument can be expanded; use Git Bash or PowerShell for such names. -- **Never run `filesmith setup` without the user's go-ahead.** It downloads up to several GB. On `SETUP_REQUIRED`, show the user the `hint` command and what it would download (`filesmith setup --dry-run --json`), then ask. -- **Outputs never replace inputs.** Report `output` paths from `done` events; never guess names. For predictable names, write into an empty `--out` folder. -- **Exit 1**: report each `error` event's `input`, `message` and `hint`. **Exit 2**: nothing ran; fix the arguments (the message names the flag and its valid values) instead of retrying. -- **Never run `filesmith setup remove ...`** (it deletes installed AI tools) unless the user asked for exactly that, and never add `--permanent` without their explicit yes. -- **Run it from the Bash tool** (Git Bash). Windows PowerShell 5.1 garbles non-ASCII paths in captured output. -- **Avoid AI jobs** (`upscale --model pid` or `comfy:...`, `generate`) while the user runs one in the app: both load the GPU. Do not install or update Filesmith while a CLI job runs: the installer closes every `Filesmith.exe`, the CLI included. - -## Reading results - -| `event` | Meaning | -| -------------------- | ---------------------------------------------------------------------------------------- | -| `run` | first line: command, version, dryRun, input count, resolved options | -| `plan` | dry run only: predicted `output`; `ready: false` with `code`, `message`, `hint` | -| `start`, `progress` | a job began; `pct` 0-100 or null, `etaSec` | -| `done` | `input`, `output`, `outputKind` (`file` or `dir`), `inSize`, `outSize` or `files` | -| `skipped` | not run and not a failure (`SAME_FORMAT`: already that format) | -| `error` | `code`, `message`, `hint` (an exact command when one exists) | -| `warning` | a flag had no effect, or a value was clamped | -| `summary` | last line: `ok`, `failed`, `skipped`, `canceled`, `exitCode` | - -Exit codes: `0` all ok or skipped, `1` some failed, `2` bad arguments or a missing requirement (nothing ran), `130` canceled. - -While a job runs, its output name is an empty placeholder next to a `*.filesmith-part*` file or folder; only the `done` event's `output` is a result. - -| `code` | What to do | -| ----------------------- | --------------------------------------------------------------------------- | -| `SETUP_REQUIRED` | Tell the user the `hint` (`filesmith setup ...`); run it only after a yes | -| `GPU_UNSUPPORTED` | That model needs an NVIDIA GPU; offer `--model photo` (any GPU) | -| `TOOL_MISSING` | Run `filesmith doctor --json` and report the failing check | -| `RAR_MISSING` | CBR and RAR output need WinRAR; offer `cbz` or `zip` | -| `UNSUPPORTED_KIND` | That file cannot take this operation; `filesmith formats --json` lists what can | -| `NOT_FOUND`, `NO_MATCH` | Check the path or the pattern | -| `OUT_DIR_MISSING` | `--out` is a file, or could not be created | -| `PASSWORD` | The archive is password-protected; ask the user | -| `USAGE` | Fix the arguments from the message | -| `TOOL_FAILED` | Report the message; the file may be damaged | - -## When something is missing +- **Dry run** (`--dry-run`) first for bulk or slow jobs (upscale, generate); show the plan, then run. +- **Read results** from stdout, one JSON object per line: `done` has `input`, `output`, `inSize`, `outSize`; `error` has `message` and `hint`; the last line is `summary`. Report the real `output` paths. +- **Never run `filesmith setup ...` without asking.** On `SETUP_REQUIRED` show the user the `hint`; it downloads up to several GB. +- **Exit codes:** `0` ok, `1` some files failed (report each error), `2` bad arguments, nothing ran (fix them, do not retry blindly). -Run `filesmith doctor --json`. Every check that is not `ok` has a `fix`: a command (ask first if it is `filesmith setup ...`) or an instruction for the user. +Every flag, event, error code and safety rule: [reference.md](reference.md). diff --git a/resources/skill/filesmith/reference.md b/resources/skill/filesmith/reference.md index 55fce4a..3497874 100644 --- a/resources/skill/filesmith/reference.md +++ b/resources/skill/filesmith/reference.md @@ -92,6 +92,27 @@ Every line: `v` (1), `event`, `ts` (ISO time). Paths are absolute, sizes in byte `USAGE`, `NOT_FOUND`, `NO_MATCH`, `UNSUPPORTED_KIND`, `SAME_FORMAT`, `OUT_DIR_MISSING`, `TOOL_MISSING`, `SETUP_REQUIRED`, `GPU_UNSUPPORTED`, `RAR_MISSING`, `PASSWORD`, `TOOL_FAILED`, `CANCELED`, `INTERNAL`. +| `code` | What to do | +| ----------------------- | ------------------------------------------------------------------------------- | +| `SETUP_REQUIRED` | Tell the user the `hint` (`filesmith setup ...`); run it only after a yes | +| `GPU_UNSUPPORTED` | That model needs an NVIDIA GPU; offer `--model photo` (any GPU) | +| `TOOL_MISSING` | Run `filesmith doctor --json` and report the failing check | +| `RAR_MISSING` | CBR and RAR output need WinRAR; offer `cbz` or `zip` | +| `UNSUPPORTED_KIND` | That file cannot take this operation; `filesmith formats --json` lists what can | +| `NOT_FOUND`, `NO_MATCH` | Check the path or the pattern | +| `OUT_DIR_MISSING` | `--out` is a file, or could not be created | +| `PASSWORD` | The archive is password-protected; ask the user | +| `USAGE` | Fix the arguments from the message | +| `TOOL_FAILED` | Report the message; the file may be damaged | + +## Safety rules (full list) + +- Dry run first (`--dry-run`) for bulk work and for anything slow or large (upscale, generate, setup); show the planned outputs, then run without it. Report the real names from `done` events. +- Quote every path. In cmd a `%` inside an argument can be expanded; prefer Git Bash. +- `filesmith setup ...` downloads up to several GB: ask first. Never run `filesmith setup remove ...` or `--permanent` unless the user asked for exactly that. +- Exit 1: report each `error` event's `input`, `message` and `hint`. Exit 2: nothing ran; fix the arguments instead of retrying. +- Avoid GPU jobs (`upscale` with pid or comfy models, `generate`) while the user runs one in the app. Do not install or update Filesmith while a CLI job runs. + ## Exit codes `0` all ok or skipped; `1` some failed (or doctor found a failure, or setup failed); `2` usage error or a requirement that fails for every input, nothing ran; `130` canceled.