feat(creative): add offline background removal skill

[AyushSrivastava1818]

Description

Adds a new creative/bg_remover registry skill for offline background removal using rembg.

Refs #196

What this PR includes

• Adds the new creative/bg_remover skill bundle
• Supports Base64 image input and optional local input/output paths
• Returns transparent PNG output
• Includes manifest.yaml, card.json, instructions.md, and deterministic skill.py
• Adds offline unit tests with mocked rembg (no ONNX download in tests)
• Adds docs/skills/bg_remover.md
• Updates docs/skills/README.md
• Adds skills/creative/__init__.py
• Updates CHANGELOG.md

Type of Change

• New Skill — new registry bundle under skills/
• Skill Upgrade — changes to an existing skill under skills/
• Bug Fix — incorrect runtime or framework behavior
• Documentation — docs, README, CONTRIBUTING only
• Framework Feature — skillware/core/ loader, env, adapters
• CLI — skillware/cli.py, docs/usage/cli.md
• Examples — examples/*.py, agent loops, examples/README.md
• Packaging — PyPI wheel, pyproject.toml, MANIFEST.in
• RFC / meta — templates, labels, CI, or large design doc

Checklist (all PRs)

• Linked GitHub issue (Refs #196)
• Scope matches the issue — no unrelated refactors
• python -m black --check . and flake8 pass locally (or CI-equivalent subset)
• pytest skills/ and pytest tests/ pass locally when relevant
• CHANGELOG.md updated under [Unreleased]
• examples/README.md updated if applicable (not applicable)
• Ran pytest tests/test_registry_docs.py

New or updated skill

Bundle and metadata

• Skill at skills/creative/bg_remover/
• manifest.yaml includes required metadata
• card.json issuer matches manifest

Logic, cognition, tests

• Deterministic skill.py
• instructions.md explains usage
• test_skill.py covers execution and validation
• SkillLoader.load_skill("creative/bg_remover") succeeds

Documentation and catalog

• Added docs/skills/bg_remover.md
• Updated docs/skills/README.md
• Added provider-specific usage examples (if not implemented)

Constitution and safety (skills only)

• Processes still images only.
• Performs background removal locally using rembg.
• Does not require cloud credentials.
• Unit tests mock rembg to avoid downloading ONNX models.

Related Issues

Refs #196

[rosspeili]

Thanks @AyushSrivastava1818, solid start on the new skill. A few things to address before merge:

Blockers

• Rebase on current main (0.4.3) and fix CHANGELOG.md, the merge left duplicate/garbage lines; add one clean [Unreleased] Added entry for the skill.
• pytest skills/, top-level from rembg import remove fails in CI (rembg isn’t in [all]). Lazy-import inside execute() (or defer import until call time) and return MISSING_DEPENDENCY when deps aren’t installed; see how other heavy-deps skills handle this.
• docs/usage/agent_loops.md, add creative/bg_remover (catalog page is enough if no example script yet). Required by test_registry_docs.py.
• docs/skills/README.md, move Creative to its own section; right now it sits inside the Office block.
• CONTRIBUTING.md, add creative to the category table ([New Skill]: creative/bg_remover — local background removal with rembg #196 acceptance).

Skill / docs polish

• Wire model and alpha_matting through to rembg.remove() (they’re in the manifest but unused today).
• Expand docs/skills/bg_remover.md to match our catalog template: dependencies + first-run ONNX note, five-provider Usage Examples (skill_usage_template.md), and the local/cloud I/O recipe snippets from [New Skill]: creative/bg_remover — local background removal with rembg #196.
• Remove debug print in test_skill.py; consider tests for input_path / output_path.
• Propose [creative] extra in pyproject.toml (rembg, pillow, onnxruntime).

Happy to re-review once those are in. Nice work on the offline mock pattern, just need the import path CI-safe. <3

[AyushSrivastava1818]

Thanks for the detailed review! I've addressed the requested changes:

• Rebased on the latest main and cleaned up the CHANGELOG.md.
• Switched to a lazy rembg import with graceful MISSING_DEPENDENCY handling for environments where the dependency isn't installed.
• Updated the implementation to use new_session and pass the session to remove, while forwarding the alpha_matting option.
• Expanded docs/skills/bg_remover.md with dependencies, usage examples, input/output recipes, and first-run ONNX notes.
• Updated docs/usage/agent_loops.md to include creative/bg_remover.
• Moved the Creative category into its own section in docs/skills/README.md.
• Added the creative category to the skill table in CONTRIBUTING.md.
• Added a creative optional dependency group in pyproject.toml.
• Removed the debug print from the tests.
• Added unit tests for input_path and output_path.
• Updated the offline rembg mock to support the new session-based implementation.

Thanks again for the review! Looking forward to your feedback.

[rosspeili]

Thanks for the attention @AyushSrivastava1818, this is undeniably solid progress on the second pass.

A few items before merge:

Blockers

1. black / flake8, skill.py and test_skill.py need formatting (blank lines, trailing whitespace, fixture indentation, EOF newline). CI will fail as-is.
2. CHANGELOG.md, please rebase on current main and keep a single clean [Unreleased] Added line for creative/bg_remover. The merge re-introduced a duplicate ### Documentation block with [Feat]: CLI commands to set and repair skill directory paths (sub-issue of #16) #81 entries and left stray merge text in the file. I would suggest add changelog before commiting not while you work, as things might change by the time you merge, so rebase right before commit if needed, then write changelog, then commit.
3. docs/skills/bg_remover.md, [New Skill]: creative/bg_remover — local background removal with rembg #196 requires cloud I/O recipe snippets (GCS, S3, Azure Blob, Cloudflare R2), not just local/base64. Still missing. It can be basic snippets user can adjust to their cloud environments, just as templates, but the local is fine I believe as is.
4. Usage Examples, expand to our catalog standard (skill_usage_template.md): page header, Direct execute, full Gemini/Claude/OpenAI/DeepSeek/Ollama snippets with sample user message + execute on tool call, and SkillLoader.to_gemini_tool() (not bare to_gemini_tool()). Check latest updates to it and current state.

Should fix

• instructions.md, mention input_path/output_path, not base64-only.
• Consider lazy-importing Pillow too so MISSING_DEPENDENCY works when optional deps aren’t installed.
• Add a test for MISSING_DEPENDENCY when rembg isn’t available.

Happy to re-review once those are in, you’re very close, and I am eager to test this locally with several agents. 🚀

[AyushSrivastava1818]

Thanks again for the detailed review! I've addressed the remaining feedback:

• Lazy-imported rembg and Pillow with graceful MISSING_DEPENDENCY handling.
• Added a MISSING_DEPENDENCY unit test along with additional input/output path coverage.
• Expanded docs/skills/bg_remover.md to align with the catalog template, including integration notes, cloud I/O recipes, provider usage examples, and limitations.
• Updated instructions.md to document both Base64 and input_path/output_path workflows.
• Applied formatting fixes and reran the relevant checks.

Validation completed:

• python -m black --check skills/creative/bg_remover
• python -m flake8 skills/creative/bg_remover
• python -m pytest skills/creative/bg_remover/test_skill.py
• python -m pytest tests/test_registry_docs.py

Looking forward to your next review. Thanks!

[rosspeili]

Thanks @AyushSrivastava1818, third pass is real progress. Lazy Pillow/rembg, MISSING_DEPENDENCY test, cloud I/O recipes, instructions, and the Gemini loop all look good. Almost there.

Blockers before merge

1. Rebase on latest main and fix CHANGELOG, one [Unreleased] Added line for creative/bg_remover only. Drop the extra ### Documentation block that re-lists [Feat]: CLI commands to set and repair skill directory paths (sub-issue of #16) #81 entries (already on main).
2. black --check . (whole repo, not just the skill folder), test_skill.py still needs formatting, fix flake8 E302 blank lines too.
3. docs/skills/bg_remover.md, fix the broken install/bash fence in Integration Guide, move print(result) inside the Direct execute code block.

Optional polish

• Claude / OpenAI / DeepSeek examples are still comment-stubs vs the full Gemini loop, expand or label as “catalog snippets only” per other skill pages.

Once those are in I’m happy to merge, also doing a full test locally, and will use it as raw py, and with various models to see if instructions work well and intent parsing is smooth, no issues with directories, logic for fallbacks, etc. will keep you posted of my findings. 🚀

[rosspeili]

I tested creative/bg_remover locally on Python 3.13 with a real PNG (no LLM). Background removal works: transparent RGBA PNG written correctly. Nice work on the core skill.

Again, tighten before merge from above comment, then skill/docs polish.

---

| Catalog + instructions.md | Two-step cost: (1) pip install packages; (2) first execute() downloads the ONNX model (~176 MB for isnet-general-use) to the rembg cache (~/.u2net/ on Linux/macOS, %USERPROFILE%\.u2net\ on Windows). Later runs are offline and much faster. My first run was ~3 min mostly for download; processing itself was quick after that. |

Optional: add empty env_vars: in manifest (explicit “none required”) or a one-line note in catalog, not required if docs are clear.

---

Tighten instructions.md (agent-facing, most important)

The skill is a thin rembg wrapper; models rely on instructions to map user intent → tool args. Please add clear rules like:

When to call (expand triggers):

• “remove background”, “transparent background”, “cut out”, “isolate product/person”, “PNG with alpha”, “no background”, etc.

When not to call: video, batch folders, “edit in Photoshop cloud only”, etc. (you have this, keep it).

If input is missing, do not call the skill:

• User asked for bg removal but no image/path/base64 → ask for upload, file path, or attachment.
• Do not call the skill until input exists.

Input choice (one required: image OR input_path):

Scenario	Agent should use
User uploaded / pasted image in chat UI	image (base64). Agent or host app encodes bytes.
User gave a local path (“remove bg from D:\photos\cat.png”)	input_path (absolute path preferred on Windows).
User gave a URL (https://…/photo.jpg)	Skill does not fetch URLs (#196 scope). Agent downloads to a temp file first, then input_path.
S3 / GCS / Azure / R2	Agent/SDK downloads object → temp file → input_path; after skill runs, upload from output_path. Catalog recipes are templates — no cloud SDK in the skill.

If both image and input_path are sent: image wins (document this so agents don’t double-submit).

Output behavior:

Scenario	Agent should use
User wants a file on disk	Set output_path. Suggest {same_dir}/{stem}_no_bg.png unless user specifies a path. Do not overwrite the source file unless asked.
Chat / API only (no disk)	Omit output_path; use image_base64 from the result (always returned on success). Host saves or displays PNG.
User said “save next to the original”	Same directory, new name (e.g. 1223_no_bg.png).

Errors to handle in the agent loop:

• INVALID_INPUT → ask for image/path.
• MISSING_DEPENDENCY → tell user to pip install rembg pillow onnxruntime or skillware[creative].
• PROCESSING_FAILED → report error string; corrupt file / wrong format possible.

No Python intent-parser required for v1 — instructions + manifest descriptions are enough if they’re this explicit.

---

Catalog doc (docs/skills/bg_remover.md) — structure suggestions

1. Fix Integration Guide markdown (install block).
2. Add a “Dependencies & first run” subsection (pip + ONNX download + offline after cache).
3. Replace generic cloud JSON with short workflow bullets per provider, e.g.
   • S3: GetObject → /tmp/in.png → execute({input_path, output_path}) → PutObject from output_path.
     Same pattern for GCS/Azure/R2 (agent handles auth; skill stays local-only).
4. Add “Input scenarios” and “Output scenarios” tables (mirror instructions above) with copy-paste execute payloads.
5. Usage Examples: Gemini looks good. Expand Claude / OpenAI / DeepSeek to full tool-call + execute loops (or label “catalog snippets only” like pdf_form_filler.md).
6. Document error_code values in Output Schema (INVALID_INPUT, MISSING_DEPENDENCY, PROCESSING_FAILED).

Example — local file (tested):

result = skill.execute({
    "input_path": r"D:\photos\1223.png",
    "output_path": r"D:\photos\1223_no_bg.png",
})

Example — base64 only (chat handoff):

result = skill.execute({"image": "<base64>"})
# result["image_base64"] → decode and save or return to user

Example — URL (agent pre-step, not skill param):

1. Agent downloads https://example.com/product.jpg → /tmp/product.jpg
2. skill.execute({"input_path": "/tmp/product.jpg", "output_path": "/tmp/product_no_bg.png"})

Example — install deps:

pip install rembg pillow onnxruntime
# or: pip install "skillware[creative]"

Example — local execute payload:

{
  "input_path": "product.png",
  "output_path": "product_no_bg.png"
}

---

Manifest polish (small)

Consider updating parameter descriptions, e.g.:

• image: “Base64-encoded still image (preferred for chat/upload handoff).”
• input_path: “Absolute or relative path to a local still image file.”
• output_path: “Optional path to write PNG; if omitted, result is base64-only in image_base64.”

Add to outputs docs: error, error_code (already in manifest).

---

Anything else

• skillware paths / config ([Feat]: CLI config and three-tier skill path resolution (global + project) #246): not needed for this PR; docs can say skill paths are host/agent responsibility for now.
• No default output path in code is fine for v1 — document the {stem}_no_bg.png convention in instructions instead of auto-writing beside input.
• Live test note for reviewers: works with [creative] deps on py3.13; first run pulls ONNX model.

Once blockers + doc/instruction pass above are in, I’m happy to merge. The visual output from my test looked good. 🚀 Again, thanks for following through this, this is a robust and powerful implementation that will help agents to instantly remove bg from any image via NLP. <3

[rosspeili]

@AyushSrivastava1818 seems like the branch history needs a cleanup before we can re-review.

The timeline shows many commits from other authors (#207, #212, #218, #249, releases, etc.). Those are already on main, they were replayed during a rebase from a stale base, not new PR work. That makes Files changed look like ~100+ files when the actual delta vs current main should only be creative/bg_remover + docs (~15 files).

Please reset the PR branch onto current main and re-apply only the bg_remover commits (squash to 1–2 commits is fine), then git push --force-with-lease.

After that we should see a small, reviewable diff with no duplicate upstream history. Thanks.

[AyushSrivastava1818]

Hi @rosspeili, thanks again for the detailed review and guidance. I've rebased the branch onto the latest main, removed the unrelated upstream history, kept only the bg_remover commits, and resolved the remaining merge conflict. The PR should now be much smaller and focused on the intended changes.

Whenever you have time, I'd really appreciate another review. Thanks!

[rosspeili]

Thanks @AyushSrivastava1818, branch cleanup looks good (3 commits, focused diff). The core skill is solid, looks like some review fixes didn’t make it into the final commits after the reset. Please add the following so everything stays in sync for the new creative category:

CI / formatting

• python -m black --check . and flake8, skills/creative/bg_remover/test_skill.py still fails (E302 blank lines)
• pytest tests/test_registry_docs.py, currently fails: creative/bg_remover missing from docs/usage/agent_loops.md

Repo ripple effects (#196)

• docs/usage/agent_loops.md, add matrix row for creative/bg_remover (use (catalog page) where there’s no runnable script yet)
• CONTRIBUTING.md, add creative to the skill categories table
• pyproject.toml, add [creative] extra (rembg, pillow, onnxruntime) and include in [all]

CHANGELOG.md

• Keep one [Unreleased] Added line for creative/bg_remover only, drop the duplicate [Feat]: CI doc-drift guards — skill catalog and examples index parity #183 / [Docs]: Add doc-drift guards to TESTING Status and agent workflow cross-links #193 lines reintroduced by the merge

Docs

• docs/skills/bg_remover.md, fix broken install bash fence, move print(result) inside the Direct execute block, document error / error_code in Output Schema, align Claude/OpenAI/DeepSeek sections with catalog template (full loop or explicit “catalog snippets only” like pdf_form_filler.md)
• skills/creative/bg_remover/instructions.md, agent routing rules from review (when to call / not call, no input → ask first, URL → download then input_path, cloud → temp file workflow, output_path vs base64, error codes)

Verify before push

• python -m black --check .
• flake8
• pytest skills/ tests/

I think you already solved them previously, if not or some are missing, please append, do not force push or mess with old commits, just new commit in the same branch in your fork, once those are in, good to merge. <3