@julioventura/opensquad 0.1.17

package/skills/README.md

@@ -0,0 +1,84 @@
+# Opensquad Skill Catalog
+
+Browse available skills for your squads. Install any skill with:
+
+```bash
+npx opensquad install <skill-name>
+```
+
+## Available Skills
+
+| Skill | Type | Description | Env Vars | Install |
+| ----- | ---- | ----------- | -------- | ------- |
+| [apify](./apify/) | mcp | Web scraping and automation platform. Extract data from any website using pre-built Actors. | `APIFY_TOKEN` | `npx opensquad install apify` |
+| [canva](./canva/) | mcp | Create, search, autofill, and export designs from Canva. | _(none -- OAuth)_ | `npx opensquad install canva` |
+| [higgsfield](./higgsfield/) | mcp | Generate AI images and videos via Higgsfield. Text-to-image, image-to-video, cinematic scenes. | _(none -- OAuth)_ | `npx opensquad install higgsfield` |
+| [instagram-publisher](./instagram-publisher/) | script | Publish Instagram carousel posts from local JPG/JPEG/PNG images via the Graph API. | `INSTAGRAM_ACCESS_TOKEN`, `INSTAGRAM_USER_ID` | `npx opensquad install instagram-publisher` |
+| [youtube-publisher](./youtube-publisher/) | script | Publish simple YouTube videos from local JPG/JPEG/PNG image sequences by generating a 10-second-per-slide MP4 slideshow with the default repository soundtrack and uploading via the YouTube Data API. | `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`, `YOUTUBE_REFRESH_TOKEN`, `YOUTUBE_CHANNEL_ID` | `npx opensquad install youtube-publisher` |
+| [blotato](./blotato/) | mcp | Publish and schedule posts across Instagram, LinkedIn, Twitter/X, TikTok, YouTube, and more. | `BLOTATO_API_KEY` | `npx opensquad install blotato` |
+| [resend](./resend/) | mcp | Send emails through Resend — single send, batch, scheduling, attachments, and contact management. | `RESEND_API_KEY` | `npx opensquad install resend` |
+| [smtp-sender](./smtp-sender/) | script | Send HTML plus plain-text emails through a native SMTP connection using local brand-scoped credentials from `.env`. | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS` | `npx opensquad install smtp-sender` |
+| [imgbb-uploader](./imgbb-uploader/) | script | Upload local JPG/JPEG/PNG assets to imgBB and return public URLs for downstream HTML/email workflows. | `IMGBB_API_KEY` | `npx opensquad install imgbb-uploader` |
+| [image-fetcher](./image-fetcher/) | hybrid | Acquire visual assets via web search, live screenshots (Playwright), and user-provided files. | _(none)_ | `npx opensquad install image-fetcher` |
+| [image-creator](./image-creator/) | mcp | Render HTML/CSS into production-ready JPG or PNG images via Playwright. | _(none)_ | `npx opensquad install image-creator` |
+| [image-ai-generator](./image-ai-generator/) | script | Generate AI images via Openrouter API. Test mode (cheap) and production mode (high-quality). Supports reference images for brand consistency. | `OPENROUTER_API_KEY` | `npx opensquad install image-ai-generator` |
+| [pdf-extractor](./pdf-extractor/) | script | Download a PDF from a URL or read it from a local file, extract text content using Python's pypdf library, and output to a text file. | _(none)_ | `npx opensquad install pdf-extractor` |
+
+## Skill Types
+
+- **mcp** -- Connects to an external MCP server (stdio or HTTP transport)
+- **script** -- Runs a local script (Node.js, Python, etc.)
+- **hybrid** -- Combines MCP server access with local script capabilities
+
+## Directory Structure
+
+Each skill lives in its own folder with a `SKILL.md` file:
+
+```text
+skills/
+  apify/
+    SKILL.md
+  canva/
+    SKILL.md
+  instagram-publisher/
+    SKILL.md
+    scripts/
+      publish.js
+  youtube-publisher/
+    SKILL.md
+    scripts/
+      publish.js
+  blotato/
+    SKILL.md
+  resend/
+    SKILL.md
+  smtp-sender/
+    SKILL.md
+    scripts/
+      send.js
+  imgbb-uploader/
+    SKILL.md
+    scripts/
+      upload.js
+  image-fetcher/
+    SKILL.md
+  image-creator/
+    SKILL.md
+  image-ai-generator/
+    SKILL.md
+    scripts/
+      generate.py
+  pdf-extractor/
+    SKILL.md
+    scripts/
+      extract.py
+```
+
+The `SKILL.md` file contains YAML frontmatter (name, type, version, MCP/script config, env vars, categories) and a Markdown body with usage instructions and available operations.
+
+## Adding a New Skill
+
+1. Create a new folder under `skills/` with the skill ID as the name
+2. Add a `SKILL.md` file with valid YAML frontmatter and Markdown body
+3. If the skill includes scripts, place them in a `scripts/` subfolder
+4. Update this README to include the new skill in the catalog table

package/skills/apify/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: apify
+description: >
+  Web scraping and automation platform. Extract data from any website,
+  run pre-built scrapers (Actors), and automate web workflows using
+  thousands of ready-made tools from the Apify Store.
+description_pt-BR: >
+  Plataforma de web scraping e automação. Extraia dados de qualquer site,
+  execute scrapers prontos (Actors) e automatize fluxos de trabalho web
+  com milhares de ferramentas da Apify Store.
+description_es: >
+  Plataforma de web scraping y automatización. Extrae datos de cualquier sitio web,
+  ejecuta scrapers prediseñados (Actors) y automatiza flujos de trabajo web
+  con miles de herramientas de la Apify Store.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: apify
+  command: npx
+  args: ["-y", "@apify/actors-mcp-server@latest"]
+env:
+  - APIFY_TOKEN
+categories: [scraping, data, automation]
+---
+
+# Apify Web Scraper
+
+## When to use
+
+Use Apify when you need to extract data from websites, scrape social media profiles, run search engine queries, or automate web data collection workflows. Apify provides thousands of pre-built scrapers (called Actors) that handle common scraping tasks out of the box.
+
+## Instructions
+
+You have access to Apify tools for web scraping and data extraction.
+
+### Key capabilities
+
+- Use Apify Actors (pre-built scrapers) to extract data from websites
+- Popular Actors: web-scraper, instagram-scraper, google-search-scraper, youtube-scraper, twitter-scraper, tiktok-scraper
+- Each Actor has its own input schema -- check documentation before running
+
+### Best practices
+
+- Start with the simplest Actor that meets the need
+- Use `maxItems` to limit results and avoid excessive costs
+- Check Actor pricing before running (some have per-result costs)
+- Parse results and extract only the fields you need
+
+## Available operations
+
+- **Run Actor** -- Execute any Apify Actor with custom input parameters
+- **Web Scraping** -- Extract structured data from any website
+- **Social Media Scraping** -- Scrape profiles, posts, and engagement data from Instagram, YouTube, Twitter/X, TikTok
+- **Search Scraping** -- Run Google, Bing, or other search engine queries and collect results
+- **Data Export** -- Retrieve scraped datasets in JSON format

package/skills/blotato/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: blotato
+description: >
+  Social media publishing and scheduling platform.
+  Publish and schedule posts across Instagram, LinkedIn, Twitter/X,
+  TikTok, YouTube, and more. Upload media and monitor post status.
+description_pt-BR: >
+  Plataforma de publicação e agendamento em redes sociais.
+  Publique e agende posts no Instagram, LinkedIn, Twitter/X,
+  TikTok, YouTube e mais. Faça upload de mídia e monitore o status dos posts.
+description_es: >
+  Plataforma de publicación y programación en redes sociales.
+  Publica y programa posts en Instagram, LinkedIn, Twitter/X,
+  TikTok, YouTube y más. Sube contenido multimedia y monitorea el estado de los posts.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: blotato
+  transport: http
+  url: "https://mcp.blotato.com/mcp"
+  headers:
+    blotato-api-key: BLOTATO_API_KEY
+env:
+  - BLOTATO_API_KEY
+categories: [social-media, automation, publishing, scheduling]
+---
+
+# Blotato Publisher
+
+## When to use
+
+Use Blotato when you need to publish or schedule social media posts across multiple platforms from a single interface. Blotato supports Instagram, LinkedIn, Twitter/X, TikTok, YouTube, and more. It handles media uploads, post scheduling, and status monitoring.
+
+## Instructions
+
+You have access to Blotato for social media publishing.
+
+### Key workflow
+
+1. Use `blotato_list_accounts` to get account IDs and platforms
+2. If post includes images or videos, upload them with `blotato_upload_media` first and use the returned media IDs in `blotato_create_post`
+3. Use `blotato_create_post` to publish or schedule
+4. Use `blotato_get_post_status` to confirm success
+
+### Best practices
+
+- Always call `blotato_list_accounts` first to get valid account IDs
+- For scheduled posts, use ISO 8601 format for datetime
+- After posting, poll `blotato_get_post_status` until status is "published" or "scheduled"
+- If status is "failed", report the error details to the user
+
+### Requirements
+
+- Blotato account required (blotato.com)
+- API key must be configured (Blotato Settings > API section)
+
+## Available operations
+
+- **List Accounts** -- Retrieve connected social media accounts and their platform types
+- **Upload Media** -- Upload images and videos for use in posts
+- **Create Post** -- Publish or schedule a post to one or more platforms
+- **Get Post Status** -- Monitor publishing status (published, scheduled, failed)
+- **Multi-platform Publishing** -- Post the same content across Instagram, LinkedIn, Twitter/X, TikTok, YouTube simultaneously

package/skills/canva/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: canva
+description: >
+  Create, search, autofill, and export designs from Canva.
+  Enables agents to generate visual content, fill templates
+  with brand assets, and export in various formats.
+description_pt-BR: >
+  Crie, busque, preencha e exporte designs do Canva.
+  Permite que agentes gerem conteúdo visual, preencham templates
+  com assets da marca e exportem em diversos formatos.
+description_es: >
+  Crea, busca, completa y exporta diseños de Canva.
+  Permite que los agentes generen contenido visual, completen plantillas
+  con recursos de marca y exporten en diversos formatos.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: canva
+  transport: http
+  url: "https://mcp.canva.com/mcp"
+categories: [design, ui, assets, automation]
+---
+
+# Canva Connect
+
+## When to use
+
+Use Canva when you need to create, search, or export visual designs. This skill connects to the user's Canva account via OAuth and enables agents to generate presentations, social media posts, logos, and other visual content. It also supports autofilling templates with brand assets and exporting designs in various formats.
+
+## Instructions
+
+You have access to Canva through the Canva Connect MCP server.
+
+### Key capabilities
+
+- Create new designs (presentations, social posts, logos, etc.)
+- Autofill templates with content (text, images, brand elements)
+- Search existing designs in the user's Canva account
+- Export designs as PDF or image files
+
+### Best practices
+
+- Use templates when possible -- faster and more on-brand
+- When autofilling, match content to template placeholder names
+- Export in the format most useful for the pipeline (JPG for social, PDF for documents)
+- Respect the user's Canva plan limitations (some features require paid plans)
+
+### Requirements
+
+- User needs a Canva account (free or paid)
+- OAuth authorization is required on first use (browser popup)
+- Autofill templates require a Canva paid plan
+
+## Available operations
+
+- **Create Design** -- Generate new designs from scratch or templates
+- **Search Designs** -- Find existing designs in the user's Canva account
+- **Autofill Template** -- Fill template placeholders with text, images, and brand elements
+- **Export Design** -- Export designs as PDF, JPG, or other formats
+- **Browse Templates** -- Search Canva's template library for the right starting point

package/skills/higgsfield/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: higgsfield
+description: >
+  Generate images and videos using Higgsfield AI models via MCP.
+  Supports text-to-image, image-to-video, and cinematic scene generation.
+  Use for producing visual assets in content squads — covers still images
+  for posts, short animated clips for reels, and environment/location scenes.
+description_pt-BR: >
+  Gere imagens e vídeos usando modelos de IA da Higgsfield via MCP.
+  Suporta texto-para-imagem, imagem-para-vídeo e geração de cenas cinematográficas.
+  Use para produzir assets visuais em squads de conteúdo — imagens estáticas
+  para posts, clipes animados para reels, e cenas de ambiente/localização.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: higgsfield
+  transport: http
+  url: "https://mcp.higgsfield.ai/mcp"
+categories: [assets, images, video, ai, generation, media]
+---
+
+# Higgsfield AI
+
+## When to use
+
+Use this skill when a squad needs to generate **original visual assets** — images or short videos — using AI. Ideal for:
+
+- Social media posts that need a custom illustration or scene
+- Reels or carousels with animated visuals
+- Background environments, location scenes, or mood boards
+- Animating an existing reference image into a short video clip
+
+**Check before generating:** always verify if a suitable image already exists in the squad's `output/` folder or can be fetched via `image-fetcher`. Only generate when no existing asset works.
+
+---
+
+## Model Reference
+
+### Image Models
+
+| Model | Plan | Best for |
+|-------|------|----------|
+| `nano_banana_2` | Basic+ | **⭐ PREFERRED** — Top quality 4K, text overlays, diagrams, any scene. |
+| `z_image` | **Free** | Fast stylized text-to-image. Use only as fallback when `nano_banana_2` is unavailable. |
+| `soul_location` | Basic+ | Cinematic environments, landscapes, location backgrounds. |
+| `soul_cast` | Basic+ | Consistent character identity and portraits. |
+
+### Video Models
+
+| Model | Plan | Best for |
+|-------|------|----------|
+| `seedance_2_0` | **Plus+** | Reference-driven video. Animate an image. Best default. |
+| `kling3_0` | Plus+ | Multi-shot, audio sync, cinematic motion. |
+| `grok_video` | Basic+ | Text and image-to-video, versatile. |
+| `veo3` | Plus+ | Google Veo 3 — reliable cinematic wide range. |
+
+> **Plan check:** before calling a paid model, verify the user's Higgsfield plan. Use `get_cost: true` to preflight credit cost before generating.
+
+---
+
+## Instructions
+
+### Generating an image
+
+Use `generate_image` with the appropriate model and a descriptive prompt.
+
+```
+Model:  z_image (free) or soul_location (paid, landscapes)
+Aspect: 16:9 for social/horizontal, 9:16 for Stories/Reels
+```
+
+**Good prompt structure:**
+```
+[Subject] [action], [environment], [lighting], [camera angle], [style/mood]
+```
+
+Example:
+```
+A dentist smiling while talking to a patient, modern clinic, soft natural light, 
+eye-level shot, photorealistic, warm and welcoming mood
+```
+
+### Animating an image into video
+
+1. Generate or provide a reference image URL
+2. Call `generate_video` with `model: seedance_2_0`
+3. Pass the image as `medias: [{role: "start_image", value: "<url or job_id>"}]`
+4. Set `duration: 5` for social clips (5s is efficient and cost-effective)
+5. Set `resolution: "720p"` for standard output
+
+### Checking model availability and constraints
+
+When unsure which model to use or what parameters it accepts:
+```
+models_explore(action: "recommend", query: "<your use case>", type: "image"|"video")
+models_explore(action: "get", model_id: "<id>")
+```
+
+### Reviewing past generations
+
+```
+show_generations(type: "image"|"video", size: 10)
+```
+
+Use `job_display(ids: [...])` to re-display a specific generation result.
+
+---
+
+## Available operations
+
+- **`generate_image`** — Text-to-image generation. Pass `model`, `prompt`, `aspect_ratio`, `count` (1–4).
+- **`generate_video`** — Image-to-video or text-to-video. Pass `model`, `prompt`, `medias[]`, `duration`, `resolution`.
+- **`models_explore`** — Discover and compare models. Actions: `list`, `search`, `get`, `recommend`.
+- **`show_generations`** — Browse past completed generations.
+- **`job_display`** — Re-display specific generation results by job ID.
+- **`media_upload`** + **`media_confirm`** — Upload a local file for use as reference input.
+- **`show_medias`** — List previously uploaded media files.
+
+---
+
+## Best practices for content squads
+
+- **Default to `z_image`** for quick iterations and free-tier availability.
+- **Use `soul_location`** for editorial-quality environment scenes (requires Basic+ plan).
+- **5-second videos at 720p** are the sweet spot for social content — lower cost, fast delivery.
+- **Reuse job IDs**: after generating an image, pass its `id` directly as `medias[].value` in `generate_video` — no need to copy URLs.
+- **Prompt language**: write prompts in English for best results across all models.
+- **Genre parameter** (`seedance_2_0`): use `"epic"` for dramatic health/science content, `"drama"` for emotional narratives, `"auto"` for general use.
+
+---
+
+## Error handling
+
+| Error | Cause | Action |
+|-------|-------|--------|
+| `Requires basic plan or higher` | Model needs paid plan | Switch to `z_image` or prompt user to upgrade at https://higgsfield.ai/mcp-pricing |
+| `Out of credits` | Free tier exhausted | Prompt user to upgrade or use an alternative image skill |
+| `status: waiting / in_progress` | Generation queued | Call `job_display` again in ~30–60s. Video can take 2–5 min. |
+| `Invalid parameter` | Model doesn't support the param | Call `models_explore(action: "get", model_id: ...)` to check supported params |
+
+---
+
+## Requirements
+
+- Higgsfield account (free or paid) — sign up at https://higgsfield.ai
+- OAuth authorization handled automatically by VS Code MCP on first use
+- For video generation: **Plus plan** minimum (https://higgsfield.ai/mcp-pricing)

package/skills/image-ai-generator/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: image-ai-generator
+description: >
+  Generates images via Openrouter API using AI image models.
+  Supports two modes: test (cheap model for iteration) and production (high-quality model for final output).
+  Handles prompt construction, API calls, base64 decoding, and file saving.
+  Supports reference images (logos, mascots) for brand-consistent generation.
+description_pt-BR: >
+  Gera imagens via API do Openrouter usando modelos de IA.
+  Suporta dois modos: test (modelo barato para iteração) e production (modelo de alta qualidade para output final).
+  Cuida da construção de prompts, chamadas de API, decodificação base64 e salvamento de arquivos.
+  Suporta imagens de referência (logos, mascotes) para geração consistente com a marca.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/generate.py
+  runtime: python3
+  invoke: "python3 {skill_path}/scripts/generate.py --prompt \"{prompt}\" --output \"{output}\" --mode \"{mode}\""
+env:
+  - OPENROUTER_API_KEY
+categories: [assets, images, ai, generation]
+---
+
+# Image Generator
+
+## When to use
+
+Use the Image Generator when you need to create visual assets from text prompts. This skill calls the Openrouter API with AI image generation models and saves the resulting images locally.
+
+**IMPORTANT: Think twice before generating images.** Image generation costs money and takes time. Before generating:
+1. Check if a suitable image already exists in the squad's assets folder
+2. Check if a web search could find a free/open image that works
+3. Consider if the image is truly necessary for the content quality
+4. Only generate when no existing alternative is good enough
+5. **Generate only what you need** — never batch-generate "test variations". One image is enough to validate a concept.
+
+## Modes
+
+### Test mode (`--mode test`)
+- **Model:** `sourceful/riverflow-v2-fast`
+- **When to use:** During iteration, testing layouts, checking composition, reviewing concepts
+- **Cost:** ~R$0.01-0.02 per image (very low)
+- **Quality:** Good enough for layout validation, not for final output
+
+### Production mode (`--mode production`)
+- **Model:** `google/gemini-3.1-flash-image-preview`
+- **When to use:** Only when generating the final images that will be published or delivered
+- **Cost:** ~R$0.07-0.10 per image
+- **Quality:** High quality, suitable for social media and publishing
+
+**Default mode is `test`.** Only switch to `production` when the user has approved the layout/composition and you are generating the final deliverable images.
+
+## Instructions
+
+### Single image generation
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --prompt "A detailed description of the image to generate" \
+  --output "squads/{squad}/output/{run_id}/assets/image-name.jpg" \
+  --mode test
+```
+
+### With a reference image (logo, mascot, brand asset)
+
+Use `--reference` to send a local image to the model as visual context. The model will incorporate the referenced image (e.g., a logo or mascot) into the generated output.
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --prompt "A social media banner featuring the company logo prominently in the center" \
+  --output "squads/{squad}/output/{run_id}/assets/banner.jpg" \
+  --reference "squads/{squad}/assets/logo.jpg" \
+  --mode production
+```
+
+Supported reference formats: JPG, JPEG, WEBP, GIF.
+
+### Batch generation
+
+```bash
+python3 skills/image-generator/scripts/generate.py \
+  --batch "squads/{squad}/output/{run_id}/assets/batch.json" \
+  --mode production
+```
+
+The batch JSON file should contain:
+```json
+[
+  {"prompt": "Description of image 1", "output": "path/to/image1.jpg"},
+  {"prompt": "Description of image 2", "output": "path/to/image2.jpg"}
+]
+```
+
+Each item can optionally include a `"reference": "path/to/ref.jpg"` field.
+
+### Prompt guidelines
+
+- Be specific about composition, lighting, style, and mood
+- Specify aspect ratio or orientation when relevant (e.g., "portrait 3:4", "landscape 16:9")
+- Include "hyper realistic, 4K quality" for photographic styles
+- Include "clean composition" to avoid cluttered outputs
+- Avoid requesting text in images — AI models struggle with text rendering
+
+### Cost awareness
+
+- Each production image costs approximately R$0.07-0.10
+- Each test image costs approximately R$0.01-0.02
+- A typical carousel with 8 images costs ~R$0.60-0.80 in production mode
+- **Always use test mode first**, then regenerate only the approved concepts in production mode
+- When testing, generate **1 image only** — not 3, not 5, just 1
+
+## Available operations
+
+- **Single generation** — Generate one image from a text prompt
+- **Batch generation** — Generate multiple images from a JSON batch file
+- **Mode selection** — Choose between test (cheap) and production (high-quality) models
+- **Reference image** — Send a logo/mascot/brand asset as visual context for the generation
+
+## Error handling
+
+- If `OPENROUTER_API_KEY` is not set, the script exits with an error message. Set it in your `.env` file or environment.
+- If the API returns an error, the script prints the error code and body, then exits with code 1.
+- If no image is found in the API response, the script reports which model was used and exits with code 1.
+- For batch mode, partial failures are reported with a success count summary.