@julioventura/opensquad 0.1.17

package/skills/opensquad-skill-creator/scripts/run_eval.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Run trigger evaluation for a skill description.
+
+Tests whether a skill's description causes Claude to trigger (read the skill)
+for a set of queries. Outputs results as JSON.
+"""
+
+import argparse
+import json
+import os
+import select
+import subprocess
+import sys
+import time
+import uuid
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+from scripts.utils import parse_skill_md
+
+
+def find_project_root() -> Path:
+    """Find the project root by walking up from cwd looking for .claude/.
+
+    Mimics how Claude Code discovers its project root, so the command file
+    we create ends up where claude -p will look for it.
+    """
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        if (parent / ".claude").is_dir():
+            return parent
+    return current
+
+
+def run_single_query(
+    query: str,
+    skill_name: str,
+    skill_description: str,
+    timeout: int,
+    project_root: str,
+    model: str | None = None,
+) -> bool:
+    """Run a single query and return whether the skill was triggered.
+
+    Creates a command file in .claude/commands/ so it appears in Claude's
+    available_skills list, then runs `claude -p` with the raw query.
+    Uses --include-partial-messages to detect triggering early from
+    stream events (content_block_start) rather than waiting for the
+    full assistant message, which only arrives after tool execution.
+    """
+    unique_id = uuid.uuid4().hex[:8]
+    clean_name = f"{skill_name}-skill-{unique_id}"
+    project_commands_dir = Path(project_root) / ".claude" / "commands"
+    command_file = project_commands_dir / f"{clean_name}.md"
+
+    try:
+        project_commands_dir.mkdir(parents=True, exist_ok=True)
+        # Use YAML block scalar to avoid breaking on quotes in description
+        indented_desc = "\n  ".join(skill_description.split("\n"))
+        command_content = (
+            f"---\n"
+            f"description: |\n"
+            f"  {indented_desc}\n"
+            f"---\n\n"
+            f"# {skill_name}\n\n"
+            f"This skill handles: {skill_description}\n"
+        )
+        command_file.write_text(command_content)
+
+        cmd = [
+            "claude",
+            "-p", query,
+            "--output-format", "stream-json",
+            "--verbose",
+            "--include-partial-messages",
+        ]
+        if model:
+            cmd.extend(["--model", model])
+
+        # Remove CLAUDECODE env var to allow nesting claude -p inside a
+        # Claude Code session. The guard is for interactive terminal conflicts;
+        # programmatic subprocess usage is safe.
+        env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
+
+        process = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            cwd=project_root,
+            env=env,
+        )
+
+        triggered = False
+        start_time = time.time()
+        buffer = ""
+        # Track state for stream event detection
+        pending_tool_name = None
+        accumulated_json = ""
+
+        try:
+            while time.time() - start_time < timeout:
+                if process.poll() is not None:
+                    remaining = process.stdout.read()
+                    if remaining:
+                        buffer += remaining.decode("utf-8", errors="replace")
+                    break
+
+                ready, _, _ = select.select([process.stdout], [], [], 1.0)
+                if not ready:
+                    continue
+
+                chunk = os.read(process.stdout.fileno(), 8192)
+                if not chunk:
+                    break
+                buffer += chunk.decode("utf-8", errors="replace")
+
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    line = line.strip()
+                    if not line:
+                        continue
+
+                    try:
+                        event = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+
+                    # Early detection via stream events
+                    if event.get("type") == "stream_event":
+                        se = event.get("event", {})
+                        se_type = se.get("type", "")
+
+                        if se_type == "content_block_start":
+                            cb = se.get("content_block", {})
+                            if cb.get("type") == "tool_use":
+                                tool_name = cb.get("name", "")
+                                if tool_name in ("Skill", "Read"):
+                                    pending_tool_name = tool_name
+                                    accumulated_json = ""
+                                else:
+                                    return False
+
+                        elif se_type == "content_block_delta" and pending_tool_name:
+                            delta = se.get("delta", {})
+                            if delta.get("type") == "input_json_delta":
+                                accumulated_json += delta.get("partial_json", "")
+                                if clean_name in accumulated_json:
+                                    return True
+
+                        elif se_type in ("content_block_stop", "message_stop"):
+                            if pending_tool_name:
+                                return clean_name in accumulated_json
+                            if se_type == "message_stop":
+                                return False
+
+                    # Fallback: full assistant message
+                    elif event.get("type") == "assistant":
+                        message = event.get("message", {})
+                        for content_item in message.get("content", []):
+                            if content_item.get("type") != "tool_use":
+                                continue
+                            tool_name = content_item.get("name", "")
+                            tool_input = content_item.get("input", {})
+                            if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
+                                triggered = True
+                            elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
+                                triggered = True
+                            return triggered
+
+                    elif event.get("type") == "result":
+                        return triggered
+        finally:
+            # Clean up process on any exit path (return, exception, timeout)
+            if process.poll() is None:
+                process.kill()
+                process.wait()
+
+        return triggered
+    finally:
+        if command_file.exists():
+            command_file.unlink()
+
+
+def run_eval(
+    eval_set: list[dict],
+    skill_name: str,
+    description: str,
+    num_workers: int,
+    timeout: int,
+    project_root: Path,
+    runs_per_query: int = 1,
+    trigger_threshold: float = 0.5,
+    model: str | None = None,
+) -> dict:
+    """Run the full eval set and return results."""
+    results = []
+
+    with ProcessPoolExecutor(max_workers=num_workers) as executor:
+        future_to_info = {}
+        for item in eval_set:
+            for run_idx in range(runs_per_query):
+                future = executor.submit(
+                    run_single_query,
+                    item["query"],
+                    skill_name,
+                    description,
+                    timeout,
+                    str(project_root),
+                    model,
+                )
+                future_to_info[future] = (item, run_idx)
+
+        query_triggers: dict[str, list[bool]] = {}
+        query_items: dict[str, dict] = {}
+        for future in as_completed(future_to_info):
+            item, _ = future_to_info[future]
+            query = item["query"]
+            query_items[query] = item
+            if query not in query_triggers:
+                query_triggers[query] = []
+            try:
+                query_triggers[query].append(future.result())
+            except Exception as e:
+                print(f"Warning: query failed: {e}", file=sys.stderr)
+                query_triggers[query].append(False)
+
+    for query, triggers in query_triggers.items():
+        item = query_items[query]
+        trigger_rate = sum(triggers) / len(triggers)
+        should_trigger = item["should_trigger"]
+        if should_trigger:
+            did_pass = trigger_rate >= trigger_threshold
+        else:
+            did_pass = trigger_rate < trigger_threshold
+        results.append({
+            "query": query,
+            "should_trigger": should_trigger,
+            "trigger_rate": trigger_rate,
+            "triggers": sum(triggers),
+            "runs": len(triggers),
+            "pass": did_pass,
+        })
+
+    passed = sum(1 for r in results if r["pass"])
+    total = len(results)
+
+    return {
+        "skill_name": skill_name,
+        "description": description,
+        "results": results,
+        "summary": {
+            "total": total,
+            "passed": passed,
+            "failed": total - passed,
+        },
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
+    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
+    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
+    parser.add_argument("--description", default=None, help="Override description to test")
+    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
+    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
+    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
+    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
+    parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
+    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
+    args = parser.parse_args()
+
+    eval_set = json.loads(Path(args.eval_set).read_text())
+    skill_path = Path(args.skill_path)
+
+    if not (skill_path / "SKILL.md").exists():
+        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
+        sys.exit(1)
+
+    name, original_description, content = parse_skill_md(skill_path)
+    description = args.description or original_description
+    project_root = find_project_root()
+
+    if args.verbose:
+        print(f"Evaluating: {description}", file=sys.stderr)
+
+    output = run_eval(
+        eval_set=eval_set,
+        skill_name=name,
+        description=description,
+        num_workers=args.num_workers,
+        timeout=args.timeout,
+        project_root=project_root,
+        runs_per_query=args.runs_per_query,
+        trigger_threshold=args.trigger_threshold,
+        model=args.model,
+    )
+
+    if args.verbose:
+        summary = output["summary"]
+        print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr)
+        for r in output["results"]:
+            status = "PASS" if r["pass"] else "FAIL"
+            rate_str = f"{r['triggers']}/{r['runs']}"
+            print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr)
+
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/opensquad-skill-creator/scripts/utils.py

@@ -0,0 +1,47 @@
+"""Shared utilities for skill-creator scripts."""
+
+from pathlib import Path
+
+
+
+def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
+    """Parse a SKILL.md file, returning (name, description, full_content)."""
+    content = (skill_path / "SKILL.md").read_text()
+    lines = content.split("\n")
+
+    if lines[0].strip() != "---":
+        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
+
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
+
+    name = ""
+    description = ""
+    frontmatter_lines = lines[1:end_idx]
+    i = 0
+    while i < len(frontmatter_lines):
+        line = frontmatter_lines[i]
+        if line.startswith("name:"):
+            name = line[len("name:"):].strip().strip('"').strip("'")
+        elif line.startswith("description:"):
+            value = line[len("description:"):].strip()
+            # Handle YAML multiline indicators (>, |, >-, |-)
+            if value in (">", "|", ">-", "|-"):
+                continuation_lines: list[str] = []
+                i += 1
+                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
+                    continuation_lines.append(frontmatter_lines[i].strip())
+                    i += 1
+                description = " ".join(continuation_lines)
+                continue
+            else:
+                description = value.strip('"').strip("'")
+        i += 1
+
+    return name, description, content

package/skills/pdf-extractor/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pdf-extractor
+description: >
+  Downloads a PDF from a URL or reads it from a local file, extracts the text using Python's pypdf library, and outputs it to a text file.
+  Useful for analyzing research papers, articles, reports, and other document assets in PDF format.
+description_pt-BR: >
+  Baixa um PDF a partir de uma URL ou o lê de um arquivo local, extrai o texto usando a biblioteca pypdf do Python e o salva em um arquivo de texto.
+  Útil para analisar artigos científicos, relatórios, contratos e outros documentos em formato PDF.
+description_es: >
+  Descarga un PDF de una URL o lo lee de un archivo local, extrae el texto usando la biblioteca pypdf de Python y lo guarda en un archivo de texto.
+  Útil para analizar artículos científicos, informes, contratos y otros documentos en formato PDF.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/extract.py
+  runtime: python
+  dependencies:
+    - pypdf
+  invoke: "python {skill_path}/scripts/extract.py --source \"{source}\" --output \"{output}\""
+categories: [scraping, data, text, documents]
+---
+
+# PDF Extractor
+
+## When to use
+
+Use the PDF Extractor skill when you need to extract and analyze text from a PDF file. The PDF file can be located online (a web URL starting with `http://` or `https://`) or stored locally in your workspace.
+
+## Instructions
+
+### Single PDF Text Extraction
+
+Run the script by providing the PDF path (local or remote URL) and the desired output text file path:
+
+```bash
+python skills/pdf-extractor/scripts/extract.py \
+  --source "https://example.com/document.pdf" \
+  --output "squads/{squad}/output/{run_id}/document-text.txt"
+```
+
+For a local PDF:
+
+```bash
+python skills/pdf-extractor/scripts/extract.py \
+  --source "squads/{squad}/reference/article.pdf" \
+  --output "squads/{squad}/output/{run_id}/article-text.txt"
+```
+
+## Available operations
+
+- **Web PDF Extraction** -- Download a PDF from any public URL and extract its text
+- **Local PDF Extraction** -- Extract text from any PDF stored in the local file system
+- **Clean Formatting** -- Strip excess spacing, control characters, and output clean plaintext
+
+## Error handling
+
+- If the URL is inaccessible or invalid, the script will exit with an error. Verify that the URL is public and does not require authentication.

package/skills/pdf-extractor/scripts/extract.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+import sys
+import os
+import argparse
+import urllib.request
+import tempfile
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract text from a PDF file (local or web URL).")
+    parser.add_argument("--source", required=True, help="Path or URL to the PDF file.")
+    parser.add_argument("--output", required=True, help="Path to write the extracted text.")
+    args = parser.parse_args()
+
+    # Verify pypdf installation
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        print("[ERROR] The 'pypdf' library is not installed. Please run: pip install pypdf", file=sys.stderr)
+        sys.exit(1)
+
+    source = args.source
+    output_path = args.output
+    temp_file_path = None
+
+    try:
+        # Check if source is a URL
+        if source.lower().startswith(("http://", "https://")):
+            print(f"[INFO] Downloading PDF from: {source}...")
+            # Use urllib with a standard User-Agent header to avoid 403 Forbidden blocks
+            req = urllib.request.Request(
+                source, 
+                headers={'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'}
+            )
+            with urllib.request.urlopen(req) as response:
+                with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp_file:
+                    tmp_file.write(response.read())
+                    temp_file_path = tmp_file.name
+            pdf_path = temp_file_path
+        else:
+            pdf_path = source
+            if not os.path.exists(pdf_path):
+                raise FileNotFoundError(f"Local PDF file not found: {pdf_path}")
+
+        print(f"[INFO] Extracting text from: {pdf_path}...")
+        reader = PdfReader(pdf_path)
+        num_pages = len(reader.pages)
+        print(f"[INFO] Found {num_pages} pages.")
+
+        extracted_text = []
+        for i, page in enumerate(reader.pages):
+            text = page.extract_text()
+            if text:
+                extracted_text.append(f"--- PAGE {i + 1} ---\n{text}\n")
+            else:
+                extracted_text.append(f"--- PAGE {i + 1} ---\n[No text extracted from this page]\n")
+
+        full_text = "\n".join(extracted_text)
+
+        # Ensure output directory exists
+        output_dir = os.path.dirname(os.path.abspath(output_path))
+        if output_dir:
+            os.makedirs(output_dir, exist_ok=True)
+
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(full_text)
+
+        print(f"[SUCCESS] Extraction complete! Character count: {len(full_text)}")
+        print(f"[SUCCESS] Saved to: {output_path}")
+
+    except Exception as e:
+        print(f"[ERROR] Error extracting PDF: {e}", file=sys.stderr)
+        sys.exit(1)
+    finally:
+        # Clean up temporary file
+        if temp_file_path and os.path.exists(temp_file_path):
+            try:
+                os.remove(temp_file_path)
+            except Exception:
+                pass
+
+if __name__ == "__main__":
+    main()

package/skills/resend/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: resend
+description: >
+  Send emails through Resend's official MCP server.
+  Supports single send, batch send, HTML and plain text bodies,
+  attachments, CC/BCC, scheduling, and contact management.
+description_pt-BR: >
+  Envie emails pelo servidor MCP oficial da Resend.
+  Suporta envio individual, envio em lote, corpo HTML e texto puro,
+  anexos, CC/BCC, agendamento e gerenciamento de contatos.
+description_es: >
+  Enviar correos electrónicos a través del servidor MCP oficial de Resend.
+  Soporta envío individual, envío por lotes, cuerpo HTML y texto plano,
+  adjuntos, CC/BCC, programación y gestión de contactos.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: resend
+  command: npx
+  args: ["-y", "resend-mcp"]
+  transport: stdio
+env:
+  - RESEND_API_KEY
+categories: [email, automation, communication]
+---
+
+# Resend — Email Skill
+
+## When to use
+
+Use this skill when a squad needs to send emails — welcome messages, notifications,
+reports, newsletters, or any transactional/marketing email. Resend handles delivery
+so the squad only needs to compose the content and call the MCP tools.
+
+## Instructions
+
+### Sending a single email
+
+1. Prepare **from**, **to**, **subject**, and **body** (HTML or plain text).
+2. Call the Resend MCP `send_email` tool.
+3. Check the response for a successful `id` — that confirms the email was queued.
+
+### Sending a batch
+
+1. Build an array of email objects (same fields as single send).
+2. Call the Resend MCP `batch_send_emails` tool.
+3. Each item in the response will have its own `id` or error.
+
+### Attachments
+
+Pass attachments as an array with `filename`, `path` (local file), `url`, or `content` (base64).
+
+### Scheduling
+
+Include a `scheduled_at` field (ISO 8601 datetime) to schedule future delivery.
+
+## Best practices
+
+- Validate **from** against a verified domain before sending — Resend rejects unverified senders.
+- Keep subject lines under 80 characters for better deliverability.
+- For batch sends, group by shared content to reduce payload size.
+- Always check the response for errors and surface them to the user rather than silently failing.
+- When composing HTML emails, keep the markup simple — most email clients ignore complex CSS.
+
+## Available operations
+
+- **Send Email** — Single email with HTML/text body, attachments, CC/BCC, reply-to
+- **Batch Send** — Multiple emails in one call
+- **Schedule Email** — Queue an email for future delivery
+- **List/Get Emails** — Check delivery status of sent emails
+- **Cancel Email** — Cancel a scheduled email before it sends
+- **Manage Contacts** — Create, list, update, and remove contacts from audiences
+- **Manage Domains** — Add and verify sender domains
+
+## Setup
+
+1. Create a free account at [resend.com](https://resend.com)
+2. Generate an API key (starts with `re_`)
+3. Add a verified sender domain (or use Resend's shared `onboarding@resend.dev` for testing)
+4. Set `RESEND_API_KEY` in your `.env` file

package/skills/run-dashboard/README.md

@@ -0,0 +1,93 @@
+# Run Dashboard Skill
+
+This skill generates a `DASHBOARD-RUN` HTML snapshot for a completed run and a sibling JSON snapshot used by the refresh button.
+
+## Files produced
+
+- `run-dashboard.html` — standalone editable HTML with inline CSS and JavaScript
+- `run-dashboard.data.json` — structured snapshot with checklist, links, artifacts, errors, and metrics
+
+The HTML branding should read `DASHBOARD-RUN`.
+
+## Static website publish
+
+When a site has an Apache/Nginx folder such as `/run-dashboard/`, you can publish the current snapshot there with:
+
+```bash
+node --env-file=.env skills/run-dashboard/scripts/generate.js \
+  --workspace-root . \
+  --run-dir squads/musicplay-club/output/2026-05-19-020010 \
+  --publish-static
+```
+
+Prefer a concrete run folder for dashboard generation. When another tool needs versioned artifacts, pass `.../output/<run-id>/v1`; the dashboard generator should still point to `.../output/<run-id>`.
+
+With `dashboard.static_publish.publish_dir_env` configured in the squad `channel-config.yaml`, the command writes:
+
+- `index.html` as the latest public snapshot
+- `<run-id>.html` as the archived snapshot
+- `youtube.html` as the latest OG share/redirect page for the published YouTube run link (when present)
+- `<run-id>-youtube.html` as the archived OG share/redirect page for that run
+- copied supporting files under `assets/latest/` and `assets/<run-id>/`
+
+The published page is static and can be opened directly by visitors without the local `serve.js` helper.
+
+If the squad config uses `transport: ftp`, the same command uploads the snapshot to the remote server instead of writing only to a local folder.
+
+Operational preflight for static publish:
+
+- `dashboard.static_publish.publish_dir_env` must resolve to a real target directory or remote folder
+- when transport is `ftp` or `both`, the env keys referenced by `dashboard.static_publish.ftp.host_env`, `port_env`, `user_env`, and `pass_env` must be present before finalization
+
+If these env vars are missing, treat the failure as configuration drift in the squad/channel setup, not as a defect in the dashboard HTML generator.
+
+## Live refresh server
+
+For a real metric refresh from inside the HTML, serve the run folder with the local dashboard server:
+
+```bash
+node skills/run-dashboard/scripts/serve.js --run-dir squads/your-squad/output/2026-05-19-020010 --workspace-root .
+```
+
+Then open `http://127.0.0.1:4319/run-dashboard.html`.
+
+In this mode, the `Refresh Data` button regenerates `run-dashboard.data.json` on demand before re-rendering the page.
+
+## Data sources
+
+The generator reads the run folder and, when present, uses:
+
+- `state.json`
+- `publish-result.md`
+- `editorial-plan.md`
+- `research-brief.md`
+- `content-package.md`
+- `images.md`
+- `review.md`
+- `publish-config.md`
+- squad `pipeline/data/channel-config.yaml`
+
+## Metrics currently attempted
+
+- Instagram: post ID, like count, and the first available primary reach/view metric
+- Facebook: post ID, reactions, comments, shares when the Page token can be resolved
+- YouTube: video ID, views, likes, comments, and publish date when OAuth credentials are available
+
+When credentials or API permissions are missing, the dashboard keeps the operational snapshot and shows `N/A` instead of failing.
+
+## Visual preview support
+
+When the run folder contains rendered slides in `images/` and a YouTube thumbnail in `thumbs/`, the dashboard shows a preview grid with:
+
+- slide images linked to their editable `.html` sources when available
+- thumbnail preview linked to the published YouTube URL when available
+
+## Supabase naming convention
+
+Supabase is optional. If future persistence is added for dashboard snapshots, templates, or profile data, all Opensquad-managed tables must use the `squad_` prefix.
+
+Examples:
+
+- `squad_profiles`
+- `squad_run_reports`
+- `squad_dashboard_templates`