Content & Media Creation · prime-skills/runcomfy-agent-skills

flux-kontext

Name: flux-kontext
Author: prime-skills/runcomfy-agent-skills

Edit images with Flux 1 Kontext Pro (Black Forest Labs' precise local image-edit model) on RunComfy — bundled with the model's documented prompting patterns so the skill gets sharper output than naive prompting against the same model. Documents Flux Kontext's strengths (single-reference precise local edits, strong prompt control, consistent high-fidelity outputs), the schema (single image + prompt), and when to route to Nano Banana Edit / GPT Image 2 edit / Flux 2 Klein instead. Calls `runcomfy run blackforestlabs/flux-1-kontext/pro/edit` through the local RunComfy CLI. Triggers on "flux kontext", "flux-kontext", "flux 1 kontext", "kontext", "BFL kontext", or any explicit ask to edit with this model.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Implemented via a "zero-code + external CLI delegation" pattern: the flux-kontext/ directory contains only a single SKILL.md without any scripts; the sole action is directing the host agent to execute `runcomfy run blackforestlabs/flux-1-kontext/pro/edit` via Bash, packing the prompt and source image into JSON and passing it to the external CLI via `--input`. The incremental value of this skill lies not in code, but in solidifying the model schema, prompting methodologies, and routing boundaries into documentation that agents can directly follow.

flux-kontext/SKILL.md

The skill invokes `runcomfy run blackforestlabs/flux-1-kontext/pro/edit` with a JSON body matching the schema.

Verified via `git ls-tree HEAD` that flux-kontext/ contains only the SKILL.md entry (the repository root contains LICENSE, README.md, and 31 other skill directories). The CLI's internal behavior has no source code to verify within the repo—runcomfy-cli/SKILL.md in the same repo serves as its manual, representing a documentation restatement.

Capabilities are entirely delivered by the remote model: the CLI POSTs JSON to the RunComfy Model API, polls request status, and downloads artifacts from whitelisted `.runcomfy.net` / `.runcomfy.com` URLs into `--output-dir`; `Ctrl-C` cancels remote requests before exit.

flux-kontext/SKILL.md

The CLI POSTs to `https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontext/pro/edit`, polls the request, fetches the result, and downloads any `.runcomfy.net`/`.runcomfy.com` URL into `--output-dir`. `Ctrl-C` cancels the remote request before exit.

This section clearly defines the three-stage lifecycle of submit → poll → download, allowing the agent to understand artifact destination paths and interruption semantics (avoiding wasted GPU quota).

The input schema is intentionally minimal: containing only four fields—prompt (required), image (required, single publicly fetchable HTTPS URL), aspect_ratio, and seed—directly encoding the model's positioning for "single-reference local editing" into the input shape, while explicitly excluding multi-image/multi-reference needs.

flux-kontext/SKILL.md

| `image` | string | yes | — | Single source image URL (publicly fetchable HTTPS). |

The aspect_ratio line states `Pick from supported W:H options on the model page.`—the only field description among the five model skills that omits enumeration values (the other skills list all enums), as noted in the discrepancy item in verification.second_pass.

The core of the documentation focuses on prompting strategies rather than API parameters: requiring preservation-first (first state what remains unchanged, then specify modifications), single imperative instructions, and decomposing compound edits into successive multi-pass workflows.

flux-kontext/SKILL.md

**Preservation first.** Lead with `"Keep [identity / pose / framing / brand] unchanged."` Then the change. Models honor what's stated up front.

What is being accomplished here: translating vendor documentation experience into imperative rules and anti-pattern checklists, enabling agents to formulate proper prompts without deep model knowledge; the anti-pattern section simultaneously excludes "wrong model" patterns (multi-image fanout, requesting new compositions without a source image).

The routing table encodes "when not to use it" directly into the skill: multi-image batching → Nano Banana Edit, in-image multilingual/embedded text → GPT Image 2 edit, text-to-image from scratch without a source image → Flux 2 Klein; it also dictates unconditional routing to this skill if the user explicitly names it.

flux-kontext/SKILL.md

| Batch edits across 1–20 images | Nano Banana Edit |

The three named skill directories (nano-banana-edit, gpt-image-2, flux-2-klein) actually exist in the repo; the page concludes with 'If the user said "Flux Kontext" / "kontext" / "BFL Kontext" explicitly, route here regardless.'—explicit naming overrides intent classification, representing a unified routing protocol across the family.

Failure surfaces are defined using a sysexits-style exit code table, delegating retry decisions to the agent: 75 = retriable (timeout/429), 77 = unauthenticated or token rejected, 65 = input JSON/schema mismatch.

flux-kontext/SKILL.md

| 75 | retryable: timeout / 429 | | 77 | not signed in or token rejected |

The table also includes 0/64/69; the same table in runcomfy-cli/SKILL.md adds an entry for 130 (Ctrl-C interruption) and a "retry?" column, changes not yet synced to this skill's table.

Self-declared limitations: single source image ceiling, public documentation schema may be incomplete, compound prompts cause drift, multilingual embedded text should use an alternative model.

flux-kontext/SKILL.md

- **Single source image only.** For multi-image flows, use Nano Banana Edit (1–20).

Explicitly noting that "documentation might lag behind the actual API" ('schema fields beyond prompt + image + aspect_ratio + seed may exist') is one of the more candid design practices within this skill suite.

2Core Capabilities

01Single-reference precise local image editing (minimal schema: prompt + single image, optional seed/aspect_ratio)

02Preservation-first instruction framing: state Keep [identity/pose/framing/brand] unchanged before specifying edits

03Decomposing compound edits across passes to reduce drift (e.g., change background first, then attire, via single-instruction passes)

04Seed-reproducible variation series (comparing identical prompt variations using the same seed)

05Sibling model routing decision matrix (delegating batching, multilingual text, and scratch generation to respective models)

06Semantic exit codes and retry evaluation (avoiding treating 429/timeouts as fatal errors)

07Checklist of anti-patterns and constraints (multi-image fanout, passive voice, requesting new composition without source image are treated as errors)

3External Dependencies

Kind	Dependency / Endpoint
cli	runcomfy（RunComfy 官方 CLI）
package	@runcomfy/cli（npm 全局包）
package	npx skills（skills.sh 安装器）
api	RunComfy Model API（Flux 1 Kontext Pro /edit）
network	RunComfy 产物下载白名单
network	用户传入的源图 URL（由 RunComfy 服务器抓取，非本机）
network	RunComfy 站点/文档（文档引用，非运行时调用）
network	GitHub（技能源码链接）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: (Skill itself contains no scripts) Host agent executes out-of-repo CLI via Bash: `runcomfy run <vendor>/<model>/<endp
网络端点: Declare external network access: POST https://model-api.runcomfy.net/v1/models/blackforestlabs/flux-1-kontex
本地工作目录: File I/O and artifact generation: Generated artifacts are downloaded by the external CLI and written to `--output-dir` (documentation states aborts when single file > 2 GiB to prevent disk saturation)

Audit Notes: Based on the unified rating criteria (image-edit in the same repo was rated Amber): at runtime, it drives a third-party npm package/CLI `@runcomfy/cli`, which accesses user RunComfy credentials (~/.config/runcomfy/token.json or RUNCOMFY_TOKEN) on each call—triggering the tier for "invokes third-party CLI/remote packages and touches credentials/quota"; the execution surface (CLI internals, Model API, token reading, 2 GiB limit, 0600 permissions, absence of shell expansion, etc.) lies entirely outside the repo with no source code to verify within this pin, justifying Amber under "when in doubt, elevate to higher tier". Furthermore, asset egress occurs: source image URLs are fetched by RunComfy servers for inference, meaning confidentiality of unreleased assets/faces depends on a third-party cloud; each invocation is billed on a per-call basis. The skill itself consists purely of markdown without scripts, obfuscation, or hidden endpoints, thus avoiding the Red tier.

5Second-Pass Verification

[ok] skill 目录内容 = 仅 SKILL.md（无脚本/引用/模板） — git ls-tree HEAD 与 ls -a 双向核实：flux-kontext/ 下仅 SKILL.md；仓库根为 LICENSE + README.md + 31 个技能目录，无 plugins/、.claude/、scripts/。
[ok] 外部依赖条目逐个回查调用点 — runcomfy CLI 调用点 2 处（How to invoke 两个示例）、npm 安装 1 处（Prerequisites）、npx skills 1 处（安装行）、model-api 端点 1 处（How it works）、白名单与第三方 URL 抓取各 1 处（Security & Privacy）、文档/模型页/GitHub/skills.sh 链接多处——均实读命中。
[unlocatable] Security & Privacy 的技术断言可在本仓证实 — token.json 权限 0600、2 GiB 下载上限、CLI 不做 shell 展开、下载白名单、退出码语义，描述的都是仓外 @runcomfy/cli 的行为；仓库内既无 CLI 源码也无版本 pin 引用，只能作为文档自述引用，不能坐实。同仓 runcomfy-cli/SKILL.md 有同一套自述，属同源转述而非独立证据。
[discrepancy] 安装一行与 GitHub 链接指向旧仓 agentspace-so/runcomfy-skills — SKILL.md 写 `npx skills add agentspace-so/runcomfy-skills --skill flux-kontext -g` 与 github.com/agentspace-so/runcomfy-skills，而本仓储物 pin 在 prime-skills/runcomfy-agent-skills（README 也用 runcomfy-agent-skills）。gh api 核实：agentspace-so/runcomfy-skills 仍存在（5★、最后推送 2026-04-29、同样含 flux-kontext 等目录），是另一份较旧的仓；prime-skills/runcomfy-agent-skills 与 agentspace-so/runcomfy-agent-skills 返回相同 stats、full_name 均为 prime-skills/runcomfy-agent-skills（同一仓的新名）。结论：按文档安装可能装到旧版内容。
[discrepancy] aspect_ratio 未给枚举值（与同族其他技能不一致） — 本技能写 'Pick from supported W:H options on the model page.'——同仓 happyhorse-1-0/wan-2-7/seedance-v2/gpt-image-edit 都列全了枚举。属于文档详略不一致（未到『错误』程度，但 agent 无法据此校验取值）。
[ok] prompt 注入面 vs 文档自述 — 正文 'The CLI does NOT shell-expand the prompt' 与 'No shell injection surface from prompt content' 一致陈述；图像侧注入风险在 Limitations/Security 段有自认，未见淡化。
[ok] 被点名的兄弟技能目录是否真实存在 — nano-banana-edit/、gpt-image-2/、flux-2-klein/ 三个目录经 ls 与 git ls-tree 核实均存在，路由建议不是死链。
[ok] 无凭证/写入代码路径 — SKILL.md 中 RUNCOMFY_TOKEN 与 token.json 仅出现在 Prerequisites 第 3 条与 Security & Privacy 的 token storage 说明里，均是对 CLI 行为的转述；文件内无 write/save/append 指令指向本地路径，除 --output-dir 产物落地外无写入动作。

6Verdict & Scenarios

Solidifies the knowledge of "using the right model + writing the right prompt" into directly executable documentation for agents: the four schema fields, preservation-first framing, and anti-pattern checklists reside in the main text without relying on the agent's prior model knowledge.

Zero-code, zero-asset, single-file portability: the entire directory consists solely of a single SKILL.md without any script execution surface, allowing comprehensive inspection before use.

Routing boundaries embedded within the skill: clearly defines when tasks should switch to Nano Banana Edit, GPT Image 2 edit, or Flux 2 Klein, reducing wasted iterations from selecting the wrong model.

Complete failure semantics: sysexits-style exit code table enables agents to distinguish retriable errors (75) from re-login requirements (77), coupled with Ctrl-C remote task cancellation notes to control quota consumption.

Self-declared limitations (single source image, compound prompt drift, potentially incomplete public docs) avoid portraying the model as omnipotent.

Best for: Suitable for: Agent workflows with an existing single source image requiring precise local editing that "modifies one element while keeping the rest intact" (background swap, handheld object replacement, label text editing); suitable for using Flux Kontext Pro as a "fidelity baseline" model in paired comparisons (holding seed constant for variation analysis); also fits as an exemplar template for skill writing—featuring the complete five-part bundle of single file, schema + prompting rules + routing + exit codes + constraints. Prerequisite: the operator must have the runcomfy CLI installed and authenticated / configured with RUNCOMFY_TOKEN (CI scenarios).

Not for: Not suitable for: Multi-image batching or series-consistent output (use Nano Banana Edit instead, 1–20 images), in-image multilingual or long text editing (GPT Image 2 edit is superior), generation from scratch without a source image (use Flux 2 Klein t2i); not suitable for scenarios requiring "local inference / zero data egress"—all operations in this skill transit through the RunComfy cloud; not suitable for users expecting self-contained scripts, offline execution, or local model weight hosting; nor suitable for compliance environments requiring auditable execution code (execution surface is unpinned and outside the repository).

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload flux-kontext.tar.gz

sha256: 8c2a39b4f92f3d82…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit fca19ae084.