@swarmclawai/swarmclaw 1.2.0 → 1.2.2

package/skills/openai-image-gen/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: openai-image-gen
+description: Generate images via OpenAI Images API (GPT Image, DALL-E 3, DALL-E 2). Supports batch generation with random prompt sampler and HTML gallery output. Use when asked to generate images with OpenAI and an OPENAI_API_KEY is available.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🎨",
+        "requires": { "bins": ["python3"], "env": ["OPENAI_API_KEY"] },
+        "primaryEnv": "OPENAI_API_KEY",
+        "install":
+          [
+            {
+              "id": "python-brew",
+              "kind": "brew",
+              "formula": "python",
+              "bins": ["python3"],
+              "label": "Install Python (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# OpenAI Image Gen
+
+Generate images via the OpenAI Images API with an HTML gallery viewer.
+
+## Run
+
+Note: Image generation can take longer than typical timeouts. Set a higher timeout when running via shell (e.g., 300 seconds).
+
+```bash
+python3 {baseDir}/scripts/gen.py
+```
+
+## Useful Flags
+
+```bash
+# GPT image models with various options
+python3 {baseDir}/scripts/gen.py --count 16 --model gpt-image-1
+python3 {baseDir}/scripts/gen.py --prompt "ultra-detailed studio photo of a lobster astronaut" --count 4
+python3 {baseDir}/scripts/gen.py --size 1536x1024 --quality high --out-dir ./out/images
+python3 {baseDir}/scripts/gen.py --model gpt-image-1.5 --background transparent --output-format webp
+
+# DALL-E 3 (note: count is automatically limited to 1)
+python3 {baseDir}/scripts/gen.py --model dall-e-3 --quality hd --size 1792x1024 --style vivid
+python3 {baseDir}/scripts/gen.py --model dall-e-3 --style natural --prompt "serene mountain landscape"
+
+# DALL-E 2
+python3 {baseDir}/scripts/gen.py --model dall-e-2 --size 512x512 --count 4
+```
+
+## Model-Specific Parameters
+
+### Size
+
+- **GPT image models** (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`): `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto`. Default: `1024x1024`
+- **dall-e-3**: `1024x1024`, `1792x1024`, or `1024x1792`. Default: `1024x1024`
+- **dall-e-2**: `256x256`, `512x512`, or `1024x1024`. Default: `1024x1024`
+
+### Quality
+
+- **GPT image models**: `auto`, `high`, `medium`, or `low`. Default: `high`
+- **dall-e-3**: `hd` or `standard`. Default: `standard`
+- **dall-e-2**: `standard` only
+
+### Other Parameters
+
+- **GPT image models** support `--background` (`transparent`, `opaque`, `auto`) and `--output-format` (`png`, `jpeg`, `webp`)
+- **dall-e-3** supports `--style` (`vivid` for hyper-real, `natural` for more natural looking)
+- **dall-e-3** only supports `n=1`; the script automatically limits count to 1
+
+## Output
+
+- Image files (`*.png`, `*.jpeg`, or `*.webp` depending on model and format)
+- `prompts.json` (prompt-to-file mapping)
+- `index.html` (thumbnail gallery — open in browser to review)

package/skills/openai-image-gen/scripts/gen.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+import argparse
+import base64
+import datetime as dt
+import json
+import os
+import random
+import re
+import sys
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from html import escape as html_escape
+from pathlib import Path
+
+
+def slugify(text: str) -> str:
+    text = text.lower().strip()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    text = re.sub(r"-{2,}", "-", text).strip("-")
+    return text or "image"
+
+
+def default_out_dir() -> Path:
+    now = dt.datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
+    preferred = Path.home() / "Projects" / "tmp"
+    base = preferred if preferred.is_dir() else Path("./tmp")
+    base.mkdir(parents=True, exist_ok=True)
+    return base / f"openai-image-gen-{now}"
+
+
+def pick_prompts(count: int) -> list[str]:
+    subjects = [
+        "a lobster astronaut",
+        "a brutalist lighthouse",
+        "a cozy reading nook",
+        "a cyberpunk noodle shop",
+        "a Vienna street at dusk",
+        "a minimalist product photo",
+        "a surreal underwater library",
+    ]
+    styles = [
+        "ultra-detailed studio photo",
+        "35mm film still",
+        "isometric illustration",
+        "editorial photography",
+        "soft watercolor",
+        "architectural render",
+        "high-contrast monochrome",
+    ]
+    lighting = [
+        "golden hour",
+        "overcast soft light",
+        "neon lighting",
+        "dramatic rim light",
+        "candlelight",
+        "foggy atmosphere",
+    ]
+    prompts: list[str] = []
+    for _ in range(count):
+        prompts.append(
+            f"{random.choice(styles)} of {random.choice(subjects)}, {random.choice(lighting)}"
+        )
+    return prompts
+
+
+def get_model_defaults(model: str) -> tuple[str, str]:
+    """Return (default_size, default_quality) for the given model."""
+    if model == "dall-e-2":
+        # quality will be ignored
+        return ("1024x1024", "standard")
+    elif model == "dall-e-3":
+        return ("1024x1024", "standard")
+    else:
+        # GPT image or future models
+        return ("1024x1024", "high")
+
+
+def normalize_optional_flag(
+    *,
+    model: str,
+    raw_value: str,
+    flag_name: str,
+    supported: Callable[[str], bool],
+    allowed: set[str],
+    allowed_text: str,
+    unsupported_message: str,
+    aliases: dict[str, str] | None = None,
+) -> str:
+    """Normalize a string flag, warn when unsupported, and reject invalid values."""
+    value = raw_value.strip().lower()
+    if not value:
+        return ""
+
+    if not supported(model):
+        print(unsupported_message.format(model=model), file=sys.stderr)
+        return ""
+
+    if aliases:
+        value = aliases.get(value, value)
+
+    if value not in allowed:
+        raise ValueError(
+            f"Invalid --{flag_name} '{raw_value}'. Allowed values: {allowed_text}."
+        )
+    return value
+
+
+def normalize_background(model: str, background: str) -> str:
+    """Validate --background for GPT image models."""
+    return normalize_optional_flag(
+        model=model,
+        raw_value=background,
+        flag_name="background",
+        supported=lambda candidate: candidate.startswith("gpt-image"),
+        allowed={"transparent", "opaque", "auto"},
+        allowed_text="transparent, opaque, auto",
+        unsupported_message=(
+            "Warning: --background is only supported for gpt-image models; "
+            "ignoring for '{model}'."
+        ),
+    )
+
+
+def normalize_style(model: str, style: str) -> str:
+    """Validate --style for dall-e-3."""
+    return normalize_optional_flag(
+        model=model,
+        raw_value=style,
+        flag_name="style",
+        supported=lambda candidate: candidate == "dall-e-3",
+        allowed={"vivid", "natural"},
+        allowed_text="vivid, natural",
+        unsupported_message=(
+            "Warning: --style is only supported for dall-e-3; ignoring for '{model}'."
+        ),
+    )
+
+
+def normalize_output_format(model: str, output_format: str) -> str:
+    """Normalize output format for GPT image models and validate allowed values."""
+    return normalize_optional_flag(
+        model=model,
+        raw_value=output_format,
+        flag_name="output-format",
+        supported=lambda candidate: candidate.startswith("gpt-image"),
+        allowed={"png", "jpeg", "webp"},
+        allowed_text="png, jpeg, webp",
+        unsupported_message=(
+            "Warning: --output-format is only supported for gpt-image models; "
+            "ignoring for '{model}'."
+        ),
+        aliases={"jpg": "jpeg"},
+    )
+
+
+def request_images(
+    api_key: str,
+    prompt: str,
+    model: str,
+    size: str,
+    quality: str,
+    background: str = "",
+    output_format: str = "",
+    style: str = "",
+) -> dict:
+    url = "https://api.openai.com/v1/images/generations"
+    args = {
+        "model": model,
+        "prompt": prompt,
+        "size": size,
+        "n": 1,
+    }
+
+    # Quality parameter - dall-e-2 doesn't accept this parameter
+    if model != "dall-e-2":
+        args["quality"] = quality
+
+    # Note: response_format no longer supported by OpenAI Images API
+    # dall-e models now return URLs by default
+
+    if model.startswith("gpt-image"):
+        if background:
+            args["background"] = background
+        if output_format:
+            args["output_format"] = output_format
+
+    if model == "dall-e-3" and style:
+        args["style"] = style
+
+    body = json.dumps(args).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        data=body,
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=300) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        payload = e.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"OpenAI Images API failed ({e.code}): {payload}") from e
+
+
+def write_gallery(out_dir: Path, items: list[dict]) -> None:
+    thumbs = "\n".join(
+        [
+            f"""
+<figure>
+  <a href="{html_escape(it["file"], quote=True)}"><img src="{html_escape(it["file"], quote=True)}" loading="lazy" /></a>
+  <figcaption>{html_escape(it["prompt"])}</figcaption>
+</figure>
+""".strip()
+            for it in items
+        ]
+    )
+    html = f"""<!doctype html>
+<meta charset="utf-8" />
+<title>openai-image-gen</title>
+<style>
+  :root {{ color-scheme: dark; }}
+  body {{ margin: 24px; font: 14px/1.4 ui-sans-serif, system-ui; background: #0b0f14; color: #e8edf2; }}
+  h1 {{ font-size: 18px; margin: 0 0 16px; }}
+  .grid {{ display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 16px; }}
+  figure {{ margin: 0; padding: 12px; border: 1px solid #1e2a36; border-radius: 14px; background: #0f1620; }}
+  img {{ width: 100%; height: auto; border-radius: 10px; display: block; }}
+  figcaption {{ margin-top: 10px; color: #b7c2cc; }}
+  code {{ color: #9cd1ff; }}
+</style>
+<h1>openai-image-gen</h1>
+<p>Output: <code>{html_escape(out_dir.as_posix())}</code></p>
+<div class="grid">
+{thumbs}
+</div>
+"""
+    (out_dir / "index.html").write_text(html, encoding="utf-8")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Generate images via OpenAI Images API.")
+    ap.add_argument("--prompt", help="Single prompt. If omitted, random prompts are generated.")
+    ap.add_argument("--count", type=int, default=8, help="How many images to generate.")
+    ap.add_argument("--model", default="gpt-image-1", help="Image model id.")
+    ap.add_argument("--size", default="", help="Image size (e.g. 1024x1024, 1536x1024). Defaults based on model if not specified.")
+    ap.add_argument("--quality", default="", help="Image quality (e.g. high, standard). Defaults based on model if not specified.")
+    ap.add_argument("--background", default="", help="Background transparency (GPT models only): transparent, opaque, or auto.")
+    ap.add_argument("--output-format", default="", help="Output format (GPT models only): png, jpeg, or webp.")
+    ap.add_argument("--style", default="", help="Image style (dall-e-3 only): vivid or natural.")
+    ap.add_argument("--out-dir", default="", help="Output directory (default: ./tmp/openai-image-gen-<ts>).")
+    args = ap.parse_args()
+
+    api_key = (os.environ.get("OPENAI_API_KEY") or "").strip()
+    if not api_key:
+        print("Missing OPENAI_API_KEY", file=sys.stderr)
+        return 2
+
+    # Apply model-specific defaults if not specified
+    default_size, default_quality = get_model_defaults(args.model)
+    size = args.size or default_size
+    quality = args.quality or default_quality
+
+    count = args.count
+    if args.model == "dall-e-3" and count > 1:
+        print(f"Warning: dall-e-3 only supports generating 1 image at a time. Reducing count from {count} to 1.", file=sys.stderr)
+        count = 1
+
+    out_dir = Path(args.out_dir).expanduser() if args.out_dir else default_out_dir()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    prompts = [args.prompt] * count if args.prompt else pick_prompts(count)
+
+    try:
+        normalized_background = normalize_background(args.model, args.background)
+        normalized_style = normalize_style(args.model, args.style)
+        normalized_output_format = normalize_output_format(args.model, args.output_format)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 2
+
+    # Determine file extension based on output format
+    if args.model.startswith("gpt-image") and normalized_output_format:
+        file_ext = normalized_output_format
+    else:
+        file_ext = "png"
+
+    items: list[dict] = []
+    for idx, prompt in enumerate(prompts, start=1):
+        print(f"[{idx}/{len(prompts)}] {prompt}")
+        res = request_images(
+            api_key,
+            prompt,
+            args.model,
+            size,
+            quality,
+            normalized_background,
+            normalized_output_format,
+            normalized_style,
+        )
+        data = res.get("data", [{}])[0]
+        image_b64 = data.get("b64_json")
+        image_url = data.get("url")
+        if not image_b64 and not image_url:
+            raise RuntimeError(f"Unexpected response: {json.dumps(res)[:400]}")
+
+        filename = f"{idx:03d}-{slugify(prompt)[:40]}.{file_ext}"
+        filepath = out_dir / filename
+        if image_b64:
+            filepath.write_bytes(base64.b64decode(image_b64))
+        else:
+            try:
+                urllib.request.urlretrieve(image_url, filepath)
+            except urllib.error.URLError as e:
+                raise RuntimeError(f"Failed to download image from {image_url}: {e}") from e
+
+        items.append({"prompt": prompt, "file": filename})
+
+    (out_dir / "prompts.json").write_text(json.dumps(items, indent=2), encoding="utf-8")
+    write_gallery(out_dir, items)
+    print(f"\nWrote: {(out_dir / 'index.html').as_posix()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/resourceful-problem-solving/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: resourceful-problem-solving
+description: Always-on guidance for solving tasks resourcefully. Teaches agents to escalate through skills, CLI tools, and custom scripts instead of refusing. Applies to any request where the agent lacks a dedicated tool.
+always: true
+---
+
+# Resourceful Problem Solving
+
+When asked to do something and no dedicated tool exists, follow this escalation pattern:
+
+## 1. Check Skills
+
+Use `use_skill` to search for a matching skill. Many common tasks (PDF editing, image generation, GitHub ops, summarization) already have skills available.
+
+## 2. Search for a CLI Tool
+
+If no skill matches, check whether a CLI tool exists:
+
+```bash
+which <tool>          # already installed?
+brew search <tool>    # macOS
+pip search <tool>     # Python ecosystem
+npm search <tool>     # Node ecosystem
+```
+
+If a suitable tool exists, install it and use it.
+
+## 3. Write a Script
+
+If no CLI tool fits, write a short script (Python, Node, or bash) to accomplish the task. Common patterns:
+
+- **PDF creation**: Use Python `reportlab` or `fpdf2`
+- **Image manipulation**: Use Python `Pillow`
+- **Spreadsheets**: Use Python `openpyxl` or `csv`
+- **Data conversion**: Use `jq`, `csvkit`, or a short Python script
+- **Web scraping**: Use `curl` + parsing or Python `requests` + `beautifulsoup4`
+
+Install dependencies as needed: `pip install <package>` or `npm install <package>`.
+
+## 4. Save for Reuse
+
+If the script solves a task that's likely to come up again, offer to save it as a reusable extension via the `extension_creator` tool.
+
+## Rules
+
+- Never refuse a task when shell tools are available. Attempt a code-based solution first.
+- Only report inability after genuinely trying and failing.
+- Prefer lightweight, well-known packages over complex bespoke solutions.
+- Always verify the output before reporting success.

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: skill-creator
+description: Create, edit, improve, or audit skills for SwarmClaw agents. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory. Triggers on phrases like "create a skill", "author a skill", "tidy up a skill", "improve this skill", "review the skill", "clean up the skill", "audit the skill".
+---
+
+# Skill Creator
+
+Guidance for creating effective skills that extend SwarmClaw agent capabilities.
+
+## About Skills
+
+Skills are modular, self-contained packages that provide specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized one equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows — multi-step procedures for specific domains
+2. Tool integrations — instructions for working with specific file formats or APIs
+3. Domain expertise — company-specific knowledge, schemas, business logic
+4. Bundled resources — scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a shared resource. Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+- **High freedom** (text instructions): Multiple valid approaches, context-dependent decisions
+- **Medium freedom** (pseudocode/parameterized scripts): Preferred pattern exists, some variation OK
+- **Low freedom** (specific scripts): Fragile operations, consistency critical, exact sequence required
+
+### Anatomy of a Skill
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name + description, required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/      — Executable code (Python/Bash/etc.)
+    ├── references/   — Documentation loaded into context as needed
+    └── assets/       — Files used in output (templates, icons, fonts)
+```
+
+#### Frontmatter
+
+- `name`: Skill name (hyphen-case, lowercase)
+- `description`: Primary triggering mechanism. Include what the skill does AND when to use it. All "when to use" info goes here — not in the body.
+
+#### Scripts (`scripts/`)
+
+Executable code for tasks that require deterministic reliability or are repeatedly rewritten. Token efficient and may be executed without loading into context.
+
+#### References (`references/`)
+
+Documentation loaded as needed to inform the agent's process. Keep only essential instructions in SKILL.md; move detailed reference material here.
+
+#### Assets (`assets/`)
+
+Files not loaded into context but used in output (templates, images, fonts). Separates output resources from documentation.
+
+### What NOT to Include
+
+- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, or other auxiliary docs
+- Setup/testing procedures or user-facing documentation
+- Information the agent already knows from general training
+
+## Skill Creation Process
+
+1. Understand the skill with concrete examples
+2. Plan reusable contents (scripts, references, assets)
+3. Initialize the skill
+4. Edit the skill (implement resources, write SKILL.md)
+5. Validate the skill
+6. Iterate based on real usage
+
+### Skill Naming
+
+- Lowercase letters, digits, and hyphens only (hyphen-case)
+- Under 64 characters
+- Prefer short, verb-led phrases describing the action
+- Name the skill folder exactly after the skill name
+
+### Step 1: Understanding with Concrete Examples
+
+Ask the user clarifying questions:
+
+- What functionality should the skill support?
+- Can you give examples of how it would be used?
+- What would a user say that should trigger this skill?
+
+### Step 2: Planning Reusable Contents
+
+Analyze each example to identify what scripts, references, and assets would be helpful:
+
+- **Repeated code** → `scripts/` (e.g., `scripts/rotate_pdf.py`)
+- **Boilerplate** → `assets/` (e.g., `assets/hello-world/` template)
+- **Domain knowledge** → `references/` (e.g., `references/schema.md`)
+
+### Step 3: Initializing the Skill
+
+Use the bundled init script to create the directory structure:
+
+```bash
+python3 {baseDir}/scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+python3 {baseDir}/scripts/init_skill.py my-skill --path skills
+python3 {baseDir}/scripts/init_skill.py my-skill --path skills --resources scripts,references
+```
+
+### Step 4: Edit the Skill
+
+Write instructions that would help another agent instance execute tasks effectively. Include information that is beneficial and non-obvious.
+
+**Writing guidelines:** Use imperative/infinitive form. Keep SKILL.md body under 500 lines.
+
+**Frontmatter description:** Include both what the skill does and specific triggers for when to use it. This is the primary mechanism for skill selection.
+
+### Step 5: Validate the Skill
+
+Run the validator to check structure and frontmatter:
+
+```bash
+python3 {baseDir}/scripts/quick_validate.py <path/to/skill-folder>
+```
+
+### Step 6: Iterate
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Update SKILL.md or bundled resources
+4. Test again
+
+## Progressive Disclosure
+
+Skills use a three-level loading system:
+
+1. **Metadata** (name + description) — always in context (~100 words)
+2. **SKILL.md body** — when skill triggers (<5k words)
+3. **Bundled resources** — as needed (unlimited, since scripts can be executed without reading)
+
+Keep SKILL.md lean. Move detailed information to reference files and describe clearly when to read them.