
bns-dev
The brasas & nube development plugin. Ships the image-generator skill (Gemini Nano Banana Pro image generation) and the repo-modernization-auditor skill (audit and modernize aging repos to be clean, current, safe, and agent-friendly); home for dev tooling as it emerges.
- version
- 0.2.0
- GitHub stars
- 5
Install
/plugin install bns-dev@bns-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add chekos/bns-marketplace.
Contents
Discovered from sourceSkills 2
Image Generator
This skill generates and edits images using Google's Gemini Nano Banana Pro model (gemini-3-pro-image-preview).
IMPORTANT: Setup Required
Before using this skill, the user must set the GEMINI_API_KEY environment variable:
- Get a free API key from Google AI Studio
- Export the key in your shell profile (
~/.zshrc,~/.bashrc, etc.):export GEMINI_API_KEY="your_api_key_here" - Restart your terminal or run
source ~/.zshrc(or~/.bashrc)
The skill will not work without this configuration.
Pre-flight Check
Before making any API call, verify the key is set:
if [ -z "$GEMINI_API_KEY" ]; then
echo "ERROR: GEMINI_API_KEY is not set. Please export it in your shell profile."
exit 1
fi
If the key is missing, stop and tell the user to set it using the instructions above.
Configuration
Model: gemini-3-pro-image-preview
API Key: Read from the GEMINI_API_KEY environment variable
Iterating on User-Provided Images
When the user provides a path to an image they want to edit or iterate on, use this workflow:
Step 1: Read and encode the image to base64
# Get the image path from user
IMG_PATH="/path/to/user/image.png"
# Detect mime type
if [[ "$IMG_PATH" == *.png ]]; then
MIME_TYPE="image/png"
elif [[ "$IMG_PATH" == *.jpg ]] || [[ "$IMG_PATH" == *.jpeg ]]; then
MIME_TYPE="image/jpeg"
elif [[ "$IMG_PATH" == *.webp ]]; then
MIME_TYPE="image/webp"
else
MIME_TYPE="image/png"
fi
# Encode to base64 (works on both macOS and Linux)
if [[ "$(uname)" == "Darwin" ]]; then
IMG_BASE64=$(base64 -i "$IMG_PATH")
else
IMG_BASE64=$(base64 -w0 "$IMG_PATH")
fi
Step 2: Send image with edit prompt (File-Based Approach)
IMPORTANT: Always use a file-based approach for the request body. Base64-encoded images are too large for command-line arguments and will cause "argument list too long" errors.
# User's edit request
EDIT_PROMPT="Add a santa hat to the person in this image"
# Write request to a JSON file (avoids command line length limits)
cat > /tmp/gemini_request.json << JSONEOF
{
"contents": [{
"parts": [
{"text": "$EDIT_PROMPT"},
{
"inline_data": {
"mime_type": "$MIME_TYPE",
"data": "$IMG_BASE64"
}
}
]
}],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"]
}
}
JSONEOF
# Call the API using the file
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/gemini_request.json > /tmp/gemini_response.json
Step 3: Extract and save the edited image
# Extract image from response and save
python3 -c "
import json
import base64
with open('/tmp/gemini_response.json') as f:
data = json.load(f)
for part in data['candidates'][0]['content']['parts']:
if 'inlineData' in part:
img_data = part['inlineData']['data']
mime = part['inlineData']['mimeType']
ext = 'png' if 'png' in mime else 'jpg'
with open('edited_image.' + ext, 'wb') as out:
out.write(base64.b64decode(img_data))
print(f'Saved: edited_image.{ext}')
elif 'text' in part:
print(part['text'])
"
Complete Example (File-Based)
For iterating on images, always use file-based requests:
# Variables
IMG_PATH="/path/to/image.png"
EDIT_PROMPT="Make the background a sunset beach"
OUTPUT_PATH="edited_output.png"
# Detect mime type and encode
MIME_TYPE=$([[ "$IMG_PATH" == *.png ]] && echo "image/png" || echo "image/jpeg")
IMG_BASE64=$(base64 -i "$IMG_PATH" 2>/dev/null || base64 -w0 "$IMG_PATH")
# Write request to file (required - base64 images are too large for command line)
cat > /tmp/gemini_request.json << JSONEOF
{
"contents": [{
"parts": [
{"text": "$EDIT_PROMPT"},
{"inline_data": {"mime_type": "$MIME_TYPE", "data": "$IMG_BASE64"}}
]
}],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"]
}
}
JSONEOF
# Call API and extract image
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/gemini_request.json > /tmp/gemini_response.json
# Save the output image
python3 -c "
import json, base64
with open('/tmp/gemini_response.json') as f:
data = json.load(f)
for part in data.get('candidates', [{}])[0].get('content', {}).get('parts', []):
if 'inlineData' in part:
with open('$OUTPUT_PATH', 'wb') as f:
f.write(base64.b64decode(part['inlineData']['data']))
print('Saved: $OUTPUT_PATH')
"
Multi-Image Input (Combine/Compose)
To combine elements from multiple images (also uses file-based approach):
IMG1_PATH="/path/to/image1.png"
IMG2_PATH="/path/to/image2.png"
PROMPT="Put the dress from the first image on the person in the second image"
IMG1_BASE64=$(base64 -i "$IMG1_PATH" 2>/dev/null || base64 -w0 "$IMG1_PATH")
IMG2_BASE64=$(base64 -i "$IMG2_PATH" 2>/dev/null || base64 -w0 "$IMG2_PATH")
# Write request to file
cat > /tmp/gemini_request.json << JSONEOF
{
"contents": [{
"parts": [
{"text": "$PROMPT"},
{"inline_data": {"mime_type": "image/png", "data": "$IMG1_BASE64"}},
{"inline_data": {"mime_type": "image/png", "data": "$IMG2_BASE64"}}
]
}],
"generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}
JSONEOF
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @/tmp/gemini_request.json > /tmp/gemini_response.json
Capabilities
Text-to-Image Generation
- Generate high-quality images from text descriptions
- Support for photorealistic, stylized, and artistic outputs
- Accurate text rendering in images (logos, infographics, diagrams)
Image Editing
- Add or remove elements from images
- Inpainting with semantic masking (edit specific parts)
- Style transfer (apply artistic styles to photos)
- Multi-image composition (combine elements from multiple images)
Advanced Features
- High Resolution: 1K, 2K, or 4K output
- Aspect Ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
- Google Search Grounding: Generate images based on real-time data
- Multi-turn Editing: Iteratively refine images through conversation
- Up to 14 Reference Images: Combine multiple inputs for complex compositions
API Usage
Basic Text-to-Image (Python)
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=["Your prompt here"],
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
image_config=types.ImageConfig(
aspect_ratio="16:9", # Optional
image_size="2K" # Optional: "1K", "2K", "4K"
)
)
)
for part in response.parts:
if part.text is not None:
print(part.text)
elif part.inline_data is not None:
image = part.as_image()
image.save("generated_image.png")
Basic Text-to-Image (JavaScript)
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
model: "gemini-3-pro-image-preview",
contents: "Your prompt here",
config: {
responseModalities: ['TEXT', 'IMAGE'],
imageConfig: {
aspectRatio: "16:9",
imageSize: "2K"
}
}
});
for (const part of response.candidates[0].content.parts) {
if (part.text) {
console.log(part.text);
} else if (part.inlineData) {
const buffer = Buffer.from(part.inlineData.data, "base64");
fs.writeFileSync("generated_image.png", buffer);
}
}
REST API (curl)
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [{"text": "Your prompt here"}]
}],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
}
}
}' | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' | base64 --decode > output.png
Image Editing (with input image)
from google import genai
from google.genai import types
from PIL import Image
client = genai.Client()
input_image = Image.open('input.png')
prompt = "Add a wizard hat to the cat in this image"
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=[prompt, input_image],
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE']
)
)
for part in response.parts:
if part.inline_data is not None:
image = part.as_image()
image.save("edited_image.png")
Multi-Image Composition
from google import genai
from google.genai import types
from PIL import Image
client = genai.Client()
image1 = Image.open('dress.png')
image2 = Image.open('model.png')
prompt = "Put the dress from the first image on the model from the second image"
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=[image1, image2, prompt],
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
image_config=types.ImageConfig(
aspect_ratio="3:4",
image_size="2K"
)
)
)
With Google Search Grounding
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents="Visualize the current weather forecast for San Francisco",
config=types.GenerateContentConfig(
response_modalities=['TEXT', 'IMAGE'],
image_config=types.ImageConfig(aspect_ratio="16:9"),
tools=[{"google_search": {}}]
)
)
Prompting Best Practices
1. Be Descriptive, Not Keyword-Based
Instead of: cat, wizard hat, cute
Write: A fluffy orange cat wearing a small knitted wizard hat, sitting on a wooden floor with soft natural lighting from a window
2. Specify Style and Mood
- Photography terms: "shot with 85mm lens", "soft bokeh background", "golden hour lighting"
- Artistic styles: "in the style of Van Gogh", "minimalist illustration", "photorealistic"
- Mood: "warm and cozy atmosphere", "dramatic noir lighting"
3. For Text in Images
Be explicit about:
- The exact text to render
- Font style (descriptively): "clean, bold, sans-serif font"
- Placement and size
4. For Editing
- Describe what to change and what to preserve
- Use "keep everything else unchanged"
- Reference specific elements clearly
5. For Product/Commercial Images
Mention:
- Lighting setup: "three-point softbox lighting"
- Background: "clean white studio background"
- Camera angle: "slightly elevated 45-degree shot"
Resolution and Aspect Ratio Reference
| Aspect Ratio | 1K Resolution | 2K Resolution | 4K Resolution |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 16:9 | 1376x768 | 2752x1536 | 5504x3072 |
| 9:16 | 768x1376 | 1536x2752 | 3072x5504 |
| 3:2 | 1264x848 | 2528x1696 | 5056x3392 |
| 2:3 | 848x1264 | 1696x2528 | 3392x5056 |
Common Use Cases
Logo Creation
Create a modern, minimalist logo for a coffee shop called 'The Daily Grind'.
The text should be in a clean, bold, sans-serif font.
Black and white color scheme. Put the logo in a circle.
Product Photography
A high-resolution, studio-lit product photograph of a minimalist ceramic
coffee mug in matte black on a polished concrete surface. Three-point
softbox lighting with soft, diffused highlights. Slightly elevated
45-degree camera angle. Sharp focus on steam rising from the coffee.
Style Transfer
Transform this photograph of a city street at night into Vincent van Gogh's
'Starry Night' style. Preserve the composition but render with swirling,
impasto brushstrokes and deep blues with bright yellows.
Infographic
Create a vibrant infographic explaining photosynthesis as a recipe.
Show "ingredients" (sunlight, water, CO2) and "finished dish" (sugar/energy).
Style like a colorful kids' cookbook, suitable for 4th graders.
Error Handling
Common issues:
- No image returned: Check that
response_modalitiesincludes'IMAGE' - Safety filters: Some prompts may be blocked; try rephrasing
- Rate limits: Implement exponential backoff for retries
- Large images: For 4K, ensure sufficient timeout settings
Dependencies
To use the Python SDK:
pip install google-genai pillow
For JavaScript:
npm install @google/genai
Important Notes
- All generated images include a SynthID watermark
- The model uses a "thinking" process for complex prompts
- For best text rendering, generate text first, then request image with that text
- Images are not stored by the API - save outputs locally
Repo Modernization Auditor
Turn an aging repo into a trustworthy working surface for future agents and humans. The core job: establish the current truth of the repository, identify stale or misleading context, then make or propose reviewable improvements that reduce confusion without hiding real risk.
The most common intent behind this skill is: "This repo was built quickly a while ago. The ideas may still be good, but the code and docs may be stale. Audit it, clean it up, and make it easier for agents to work in."
Operating Principles
These shape every phase — internalize them before starting:
- Code is evidence; docs are clues. The codebase, lockfile, scripts, tests, build output, git state, and runtime behavior are stronger evidence than docs. Docs, roadmaps, devlogs, todos, and agent instructions must be reconciled with current reality, not trusted.
- Git history is the archive. Prefer deletion or consolidation when old context would mislead future agents. But preserve durable decisions, operational footguns, current architecture, and knowledge that prevents repeated mistakes.
- Small safe slices over broad rewrites. Avoid rewrites for style alone. Favor changes that make future changes safer and easier.
- Never print secret values. If env files exist, report key names and configuration shape only.
- Protect user work. Run
git statusbefore any edit and never revert or sweep up unrelated dirty files. - Verify with repo-native commands. When checks fail, distinguish product regressions from stale tests, obsolete mocks, or tooling drift — they call for different fixes.
- Check currency against current docs. When evaluating framework or library best practices, use WebSearch/WebFetch on official documentation if there is any chance guidance has changed since your training data.
Workflow
Start by creating a TodoWrite plan with the phases below so the user can see progress. Adjust scope to the repo size — a small script repo doesn't need the full treatment.
Phase 1: Orientation
Before editing anything, build a factual map. Run independent lookups in parallel:
- Read top-level guidance:
CLAUDE.md,AGENTS.md,README.md,CONTRIBUTING.md, package manifests, CI config, docs indexes. - Map the file tree with Glob and Grep. Notice generated artifacts, local-only directories, duplicated configs, old roadmaps, large docs folders, and tracked agent-specific files.
- Check git state:
git status,git log --oneline -20, recent branch activity. Identify untracked or dirty files before touching anything. - Identify the stack, product purpose, core workflows, data stores, auth model, deployment target, and verification commands.
- Run the lowest-risk baseline checks the repo itself advertises — install status, lint, typecheck, tests, build. Record pass/fail; do not sink time into fixing yet.
Spawn parallel Explore subagents where it helps — one per area (docs inventory, dependency state, test/build health, security surfaces) — and synthesize their findings rather than reading everything yourself. You're the judge of when the repo is small enough to just read directly.
If the user explicitly said "before doing anything, report back," stop after this phase and deliver the orientation, baseline, risks, and a recommended first cleanup slice.
Phase 2: Truth Reconciliation
Compare claims against implementation. Label every finding with one of three states:
current— matches the implementation; should remain.stale— no longer matches the product or workflow; delete or rewrite.aspirational— useful future direction; mark clearly as roadmap or move out of the working path.
Common drift zones to check (Grep is your friend here — search for feature names mentioned in docs and verify the code exists):
- Product docs listing planned features as completed.
- "Offline mode," "self-hosted," "privacy-first," "AI," "export," "sync," or "agent-native" claims that may not match code.
- Stale TODO directories, historical devlogs, generated audit reports, old specs, previous review artifacts.
- Agent instructions (CLAUDE.md, old slash commands,
.cursorrules, etc.) referencing obsolete tools, retired workflows, or incompatible permission assumptions. - Compatibility facades and "legacy" paths no current caller needs.
- Setup docs with old env var names, dead commands, or non-working flows.
Phase 3: Audit Areas
Audit broadly enough to find the real risks, then prioritize. Read references/audit-areas.md for the detailed per-area checklists covering:
- Agent readiness — one concise source of truth for future agents
- Build, test, and CI — do the advertised gates actually work
- Security and privacy — verify against code, never against security docs
- Architecture and simplicity — fewer code paths beats another abstraction
- Data and operations — migrations, schema drift, operational footguns
- UX and product quality — does the UI match the current product promise
- Repo hygiene — tracked files that should only exist in git history
Use a workflow to run the audit (the Workflow tool, where available): one finder agent per audit area, each given its checklist section from the reference file, then adversarially verify the P0/P1 findings before reporting them — a finding that survives a skeptic agent trying to refute it is worth far more than a plausible guess. Scale the fan-out to the repo; the workflow script is yours to shape. If the Workflow tool isn't available, fall back to parallel Task subagents (one per area) and merge their findings yourself.
Treat destructive database or production operations as high-risk: surface them, but require explicit user direction before acting.
Phase 4: Prioritized Report
Report findings before changing code, unless the user already asked you to implement. Use this structure:
**Repo Orientation**
- What this repo is today; current stack and core workflows.
- Main verification commands.
**Health Baseline**
- Checks run with pass/fail results and notable warnings.
- Dirty/untracked git state.
**Highest-Risk Findings**
- P0/P1 issues first, with file:line references and evidence.
- Impact and recommended action for each.
**Stale Context**
- Docs, todos, generated reports, old agent instructions, or specs likely to mislead.
- Mark each: delete, rewrite, keep, or confirm-with-user.
**First Cleanup Slice**
- A small reviewable set of changes, why it comes first, and the verification plan.
For larger audits, group recommendations into: delete/archive stale context, fix broken gates, security hardening, simplify architecture, refresh current docs, defer/confirm product direction.
Phase 5: Implementation
When the user approves (or asked for implementation up front):
- Start with the smallest high-confidence slice; track each slice in TodoWrite.
- Delete stale docs and dead support files only after verifying (Grep for references) they are not current inputs.
- Update CLAUDE.md / agent guidance so future agents know the current commands, product truth, and operational footguns.
- Fix broken quality gates before broad refactors.
- Add or update tests where behavior risk changes.
- Run the relevant checks after each slice — not just at the end.
- Keep changes easy to review: don't mix cleanup, behavior changes, dependency upgrades, and docs rewrites in one batch unless the user asked for a single sweep.
Deletion Heuristics
Good deletion candidates:
- Completed todo files outside any active tracking system.
- Historical devlogs duplicated across locations with no current decision value.
- Old specs for features that don't exist and aren't current roadmap.
- Generated reports whose conclusions were implemented or went stale.
- Tool-specific agent commands that no longer run in the current agent environment.
- Local build outputs, temp files, downloaded media, generated caches.
- Duplicate config files where only one is used.
Do not delete without stronger evidence:
- ADRs capturing current or superseded architectural choices.
- Migration files, schema history, data repair scripts.
- Operational notes about known deployment, database, auth, or migration footguns.
- User-facing docs for features that currently work.
- Tests that fail because code regressed — fix or replace them instead.
Final Handoff
End with a concise report: what changed or was found, what checks passed or failed, what stale context was removed or still needs confirmation, and what remains as the next safest slice. If no edits were made, say so clearly and provide the reusable plan the user asked for.
Sponsors
Details
- Marketplace
- chekos/bns-marketplace
- Source
- bns-dev
- Author
- chekos
- Category
- Community