Skill: dishant0406/nano-img-cli (version 1.0.1)

--- name: nano-img-cli description: Drives the local nano-img Gemini image CLI for image generation, model selection, saved defaults, reference-image workflows, and output sizing or format conversion. Use when the user wants to generate images with nano-img or nano-image, inspect config or refs, set the default model or save directory, manage ~/.nano-img files, or get command-specific help for this CLI. metadata: author: nano-cli-img version: 0.1.0 --- # Nano Img CLI ## When To Use Use this skill when the task is specifically about the local `nano-img` or `nano-image` CLI in this repository or its home-directory defaults under `~/.nano-img`. Package naming note: - npm package: `nanobana` - installed commands: `nano-img`, `nano-image` Typical triggers: - "generate an image with nano-img" - "set the nano-img model" - "save images to a default folder" - "use the refs from ~/.nano-img/assets" - "show what nano-img supports" - "fix or inspect nano-img config" Do not use this skill for general Gemini API design discussions that are not tied to this CLI. ## Execution Mode Prefer the installed binaries when available: - `nano-img` - `nano-image` If you are working inside this repo and do not want to depend on a global link, use: - `npm run dev -- <command>` - `npm run nano-img -- <command>` ## Core Workflow 1. Start by checking the exact command surface instead of assuming flags. Use `nano-img help` for global help or `nano-img <command> --help` for command help. 2. If the task is generation, inspect saved defaults first when they matter. Run `nano-img config --json`. 3. If the task depends on a saved model or output directory, prefer the dedicated commands over editing config by hand: - `nano-img model ...` - `nano-img save-dir ...` 4. If the task depends on reusable prompts or style, use the home-directory files: - `~/.nano-img/INSTRUCTION.md` - `~/.nano-img/STYLE.md` - `~/.nano-image/STYLE.md` 5. If the task uses default reference images, inspect `~/.nano-img/assets` and verify with `nano-img refs --json`. 6. After changing behavior, validate with one concrete CLI command and capture the resulting output path or config state. ## Generate Images For generation details and command recipes, read `references/command-reference.md`. Key rules: - Use `generate` explicitly unless the user clearly wants the shorthand prompt form. - Respect saved defaults from `~/.nano-img/config.json`. - If the user passes `--save-to` or `--output`, that overrides the saved default output directory. - Width-only or height-only requests preserve aspect ratio during local resize. - Width plus height forces the final image to the exact requested dimensions. - Format defaults to `png`; `jpg`, `jpeg`, and `webp` are supported through local conversion. ## Configure Defaults For persistent settings and file layout, read `references/defaults-and-files.md`. Prefer command-driven config changes: - Save model: `nano-img model <name>` - Pick model interactively: `nano-img models` - Save default output dir: `nano-img save-dir --set "<path>"` - Clear saved output dir: `nano-img save-dir --clear-save-dir` Avoid editing `~/.nano-img/config.json` directly unless the user explicitly asks for a manual file edit. ## Troubleshooting Read `references/troubleshooting.md` when: - generation fails - models do not list - the picker or config looks wrong - output paths or refs are not being used ## Validation After making changes or guiding usage: - run one obvious command that should succeed - use `--json` when you need machine-readable confirmation - report the exact saved model, output directory, or generated file path when relevant

path: agents/openai.yaml
content: interface:
  display_name: "Nano Img CLI"
  short_description: "Operate the local Gemini image CLI and its defaults"
  default_prompt: "Use $nano-img-cli to generate or configure images with the local nano-img CLI."

policy:
  allow_implicit_invocation: true


path: references/command-reference.md
content: # Command Reference

Use this file when the task needs exact CLI invocations.

Package/install note:

- npm package name: `nanobana`
- installed binaries: `nano-img`, `nano-image`

## Global Discovery

Preferred:

- `nano-img help`
- `nano-img help generate`
- `nano-img generate --help`
- `nano-img models --help`
- `nano-img save-dir --help`

Repo-local equivalents:

- `npm run dev -- help`
- `npm run dev -- generate --help`

## Generate

Use for one-shot image creation:

```bash
nano-img generate "a minimal editorial thumbnail"
nano-img generate --save-to ./renders "a product poster"
nano-img generate -w 1600 -h 840 -f webp "a dark blog hero"
nano-img generate --ref ./extra.png --no-default-refs "a controlled studio shot"
```

Behavior:

- `-w` only: resize to requested width, preserve aspect ratio
- `-h` only: resize to requested height, preserve aspect ratio
- `-w` + `-h`: force exact output size
- `-f`: final output format, default `png`

## Models

Use for model discovery or saved model changes:

```bash
nano-img models
nano-img models --no-interactive
nano-img models --json
nano-img model
nano-img model gemini-3.1-flash-image-preview
nano-img model --clear-model
```

Notes:

- In a TTY, `nano-img models` opens an arrow-key picker.
- Enter saves the selected model.
- `q` or `Esc` cancels.

## Save Directory

Use for persistent output location:

```bash
nano-img save-dir
nano-img save-dir --set "~/nano-image"
nano-img save-dir /absolute/or/relative/path
nano-img save-dir --clear-save-dir
```

Generation precedence:

1. `--save-to` / `--output`
2. saved `outputDir` in `~/.nano-img/config.json`
3. current working directory

## Inspect Defaults

Use these before debugging:

```bash
nano-img config --json
nano-img refs --json
```

`config --json` is the fastest way to confirm:

- current model
- saved model
- saved output dir
- instruction/style paths
- detected default references


path: references/defaults-and-files.md
content: # Defaults And Files

Use this file when the task is about persistent defaults, reusable prompts, or local assets.

## Home Directory Layout

```text
~/.nano-img/
├── assets/
├── INSTRUCTION.md
├── STYLE.md
└── config.json
```

Fallback style path:

```text
~/.nano-image/STYLE.md
```

## What Lives Where

- `assets/`: default reference images used unless `--no-default-refs` is passed
- `INSTRUCTION.md`: persistent generation instructions
- `STYLE.md`: persistent style guidance
- `config.json`: saved model and saved output directory

## Supported Saved Config Keys

Current keys used by this CLI:

```json
{
  "model": "gemini-3.1-flash-image-preview",
  "outputDir": "/absolute/path"
}
```

## Preferred Ways To Change Defaults

Prefer commands over manual file edits:

- model: `nano-img model <name>`
- output dir: `nano-img save-dir --set "<path>"`

Only edit `INSTRUCTION.md`, `STYLE.md`, or `assets/` directly when the user wants to change reusable creative defaults.

## Useful Inspection Commands

```bash
nano-img config --json
nano-img refs --json
find ~/.nano-img -maxdepth 2 -type f | sort
```

## Path Handling

- `save-dir --set "~/nano-image"` expands `~` to the current user's home directory
- relative paths are resolved from the current working directory at the time the command is run
- saved `outputDir` is stored as an absolute path in config


path: references/troubleshooting.md
content: # Troubleshooting

Use this file only when the normal workflow fails.

## Models Do Not List

Checks:

1. Verify `NANO_IMAGE_API_KEY` is set.
2. Run `nano-img models --no-interactive`.
3. If still failing, inspect the API error message directly.

Common causes:

- missing API key
- quota or billing limits
- network or upstream Gemini API failures

## Generation Fails

Start with:

```bash
nano-img config --json
```

Then verify:

1. the selected model is valid
2. refs exist and are readable
3. instruction/style files exist if the task depends on them
4. the output directory is writable

Common failures:

- `RESOURCE_EXHAUSTED` or `429`: quota exhausted
- no image parts returned: upstream model response issue
- missing refs: bad file path or unsupported extension

## Picker Or Saved Defaults Behave Unexpectedly

Checks:

1. inspect `~/.nano-img/config.json`
2. run `nano-img model`
3. run `nano-img save-dir`
4. rerun with an explicit override to isolate precedence

Examples:

```bash
nano-img model gemini-2.5-flash-image
nano-img save-dir --set "~/nano-image"
nano-img generate --save-to ./tmp "test prompt"
```

## Size Or Format Confusion

Remember:

- Gemini native image generation supports preset image settings, not arbitrary pixel output
- the CLI applies exact resize and format conversion locally after generation
- `png` is the default final format

Use:

```bash
nano-img generate -w 1600 -h 840 -f webp "test prompt"
```

to verify the final file behavior explicitly.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)