@acedatacloud/skills 2026.621.3 → 2026.621.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.621.3",
+  "version": "2026.621.5",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/cloudflare/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: cloudflare
+description: Manage Cloudflare zones, DNS records, cache purge and Workers via the API v4. Use when the user mentions Cloudflare, a DNS record on a Cloudflare-hosted domain, purging / clearing the CDN cache, a zone's settings, WAF / firewall rules, or listing Workers.
+when_to_use: |
+  Trigger when the user wants to list Cloudflare zones, read or change
+  DNS records, purge the cache, inspect Workers, or review firewall
+  rules. The connector stores a scoped Cloudflare API token; confirm
+  before any write (DNS create/update/delete, cache purge) and prefer
+  the smallest-blast-radius action.
+connections: [cloudflare]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Call the **Cloudflare API v4** with `curl + jq`. The user's **scoped** token is
+in `$CLOUDFLARE_API_TOKEN` (optionally `$CLOUDFLARE_ACCOUNT_ID` /
+`$CLOUDFLARE_ZONE_ID`); every call needs `Authorization: Bearer
+$CLOUDFLARE_API_TOKEN`. Base URL: `https://api.cloudflare.com/client/v4`.
+
+Every response has `{"success": bool, "errors": [...], "result": ...}`. On
+`success:false` show `.errors` verbatim. `403`/`9109` means the token lacks the
+permission for that resource → the user must re-mint the token with the right
+scope (zone DNS edit, cache purge, etc.).
+
+```bash
+AUTH=(-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN")
+API="https://api.cloudflare.com/client/v4"
+# Zones the token can see
+curl -sS "${AUTH[@]}" "$API/zones" | jq '.result[] | {id, name, status, plan: .plan.name}'
+```
+
+## DNS records
+
+```bash
+ZONE="${CLOUDFLARE_ZONE_ID:?set or pick from the zones list}"
+# List (filter with ?type=A&name=foo.example.com)
+curl -sS "${AUTH[@]}" "$API/zones/$ZONE/dns_records?per_page=100" \
+  | jq '.result[] | {id, type, name, content, proxied, ttl}'
+
+# Create (confirm first)
+curl -sS -X POST "${AUTH[@]}" -H "Content-Type: application/json" \
+  -d '{"type":"CNAME","name":"www","content":"example.com","proxied":true}' \
+  "$API/zones/$ZONE/dns_records" | jq '.success, .result.id'
+
+# Update PATCH /dns_records/{id} ; delete DELETE /dns_records/{id}
+```
+
+## Purge cache (confirm first)
+
+```bash
+# Targeted purge by URL (preferred); use {"purge_everything":true} only if asked
+curl -sS -X POST "${AUTH[@]}" -H "Content-Type: application/json" \
+  -d '{"files":["https://example.com/path"]}' \
+  "$API/zones/$ZONE/purge_cache" | jq '.success'
+```
+
+## Workers & firewall
+
+```bash
+ACCT="${CLOUDFLARE_ACCOUNT_ID:?needed for account-scoped resources}"
+curl -sS "${AUTH[@]}" "$API/accounts/$ACCT/workers/scripts" | jq '.result[] | {id, modified_on}'
+# Firewall / WAF custom rules live under /zones/$ZONE/firewall/rules and rulesets.
+```
+
+## Gotchas
+
+- Insist on a **scoped API token**, never the legacy Global API Key (the connect
+  form's help says so) — a Global Key can do anything on the account.
+- `proxied:true` = orange-cloud (CDN/WAF on); `false` = DNS-only. Changing it can
+  break TLS/origin expectations — confirm intent.
+- Account-scoped calls (Workers, some analytics) need `$CLOUDFLARE_ACCOUNT_ID`;
+  zone-scoped calls need a zone id (pick from `/zones` if env unset).

package/skills/cn-blog/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: cn-blog
+description: Read and publish on Chinese content platforms with the user's own login cookies (BYOC) — list their published articles with vote/comment stats, inspect one article, and publish a new article. Use when the user mentions 知乎 / Zhihu, "我的知乎文章", reading their article stats (点赞/评论), or publishing/发文 to Zhihu.
+when_to_use: |
+  Trigger for anything on the user's Zhihu (知乎) account driven by their own
+  login cookie: show who they are, list their published articles with
+  vote-up / comment counts, look at one article's stats, or publish a new
+  article. This acts as the user's real account, so writes are gated behind
+  an explicit confirmation.
+connections: [zhihu]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+# cn-blog — Zhihu via your own cookies
+
+Drives the user's **real** Zhihu account through the same web APIs the site's
+own editor uses, authenticated by the login cookie they captured with the ACE
+extension. No browser, no third-party deps — just `urllib`.
+
+The connector injects the cookie jar as an env var:
+
+- `ZHIHU_COOKIES` — a JSON array of `{name, value, domain, path, ...}` cookies.
+  **Secret — never echo or print it.** The CLI reads it for you.
+
+## CLI
+
+The skill ships [`scripts/blog.py`](scripts/blog.py) — self-contained, stdlib only.
+
+```sh
+BLOG=$SKILL_DIR/scripts/blog.py
+
+# Read (run directly)
+python3 $BLOG whoami                       # who is logged in
+python3 $BLOG articles --limit 20          # my published articles + stats
+python3 $BLOG article <article-id>         # one article's details + stats
+```
+
+## Verify the connection first
+
+```sh
+python3 $BLOG whoami
+# → {"id": "...", "name": "崔庆才丨静觅", "url_token": "cui-qing-cai", ...}
+```
+
+On a `401`/`403` the cookie is expired — tell the user to reconnect at
+<https://auth.acedata.cloud/user/connections> (re-capture with the ACE
+extension). Do **not** retry in a loop.
+
+## Reading recipes
+
+| Goal | Command |
+|---|---|
+| Who am I | `python3 $BLOG whoami` |
+| My latest articles + vote/comment counts | `python3 $BLOG articles --limit 20` |
+| Next page | `python3 $BLOG articles --limit 20 --offset 20` |
+| One article's stats | `python3 $BLOG article <id>` |
+
+Stats come straight from Zhihu: `voteup_count` (赞同), `comment_count` (评论).
+Zhihu does not expose per-article read counts on these endpoints.
+
+## Publishing — GATED (dry-run unless trailing `--confirm`)
+
+`publish` writes to the user's real account. Without a trailing `--confirm` it
+**dry-runs** (prints what it would do, changes nothing). `--confirm` is honored
+**only as the last argument**, so a title/content containing "--confirm" can
+never silently go live. Always show the dry-run to the user, get an explicit
+"yes", then re-run with `--confirm` last.
+
+```sh
+# Content is HTML. For Markdown, convert to HTML first.
+python3 $BLOG publish --title "标题" --content-file article.html               # dry-run
+python3 $BLOG publish --title "标题" --content-file article.html --draft-only --confirm  # save a private draft
+python3 $BLOG publish --title "标题" --content-file article.html --confirm     # PUBLIC, goes live
+```
+
+- `--draft-only` stops after saving a private draft (safe — nothing public).
+- Without `--draft-only`, the article is **published publicly** under the user's
+  name. Default to `--draft-only` unless the user clearly asked to go live.
+- Images: only image URLs already reachable on the public web are kept as-is;
+  this CLI does not re-upload local images to Zhihu's CDN.
+
+## Gotchas — surface before the user is surprised
+
+- **This is the user's real Zhihu account.** Confirm before any publish; reading
+  exposes their own private drafts.
+- **Cookie expiry**: Zhihu cookies are short-lived. A `401`/`403` means
+  reconnect at auth.acedata.cloud/user/connections — never loop-retry.
+- **ToS**: cookie automation is against most platforms' terms. This only ever
+  acts on the user's own account with their own captured cookie; the user owns
+  that risk. Never use it to scrape other people's content at scale.
+- **Never print `ZHIHU_COOKIES`** — it is full account access.
+- **Scope today**: Zhihu only. 掘金 / CSDN connectors exist in the vault and are
+  planned next; this skill will grow a `--platform` switch for them.

package/skills/cn-blog/scripts/blog.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""
+cn-blog — read & publish on Chinese content platforms with the user's own
+login cookies (BYOC). Standard-library only (urllib), no third-party deps,
+so it runs in the bare sandbox without an image change.
+
+The connector injects the user's cookie jar as a JSON env var named
+``<PLATFORM>_COOKIES`` (e.g. ``ZHIHU_COOKIES``) — a list of
+``{name, value, domain, path, ...}`` dicts captured by the ACE extension.
+
+Read commands run directly. ``publish`` is GATED: without a trailing
+``--confirm`` it only dry-runs (prints what it would do, changes nothing).
+``--confirm`` is honored ONLY as the last argument, so a title/content that
+merely contains "--confirm" can never silently go live.
+
+Quick examples:
+  python3 $SKILL_DIR/scripts/blog.py whoami
+  python3 $SKILL_DIR/scripts/blog.py articles --limit 20
+  python3 $SKILL_DIR/scripts/blog.py article <article-id>
+  python3 $SKILL_DIR/scripts/blog.py drafts
+  python3 $SKILL_DIR/scripts/blog.py publish --title "T" --content-file a.html --draft-only --confirm
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+)
+
+# --confirm is only honored as the LAST token so a value that merely
+# contains "--confirm" can never silently confirm a write.
+_RAW = sys.argv[1:]
+CONFIRM = bool(_RAW) and _RAW[-1] == "--confirm"
+ARGV = _RAW[:-1] if CONFIRM else list(_RAW)
+
+
+def out(obj) -> None:
+    print(json.dumps(obj, ensure_ascii=False, indent=2, default=str))
+
+
+def die(msg: str, code: int = 1) -> None:
+    out({"error": msg})
+    sys.exit(code)
+
+
+# ── Cookie jar (from env) ───────────────────────────────────────────
+
+def load_cookies(platform: str) -> list[dict]:
+    env = f"{platform.upper()}_COOKIES"
+    raw = os.environ.get(env)
+    if not raw:
+        die(
+            f"{env} is not set — connect the {platform} account at "
+            f"https://auth.acedata.cloud/user/connections, then retry."
+        )
+    try:
+        jar = json.loads(raw)
+    except json.JSONDecodeError as e:
+        die(f"{env} is not valid JSON: {e}")
+    if not isinstance(jar, list):
+        die(f"{env} must be a JSON list of cookies, got {type(jar).__name__}")
+    return jar
+
+
+def _domain_matches(host: str, domain: str) -> bool:
+    # Browser-style domain match: a cookie scoped to ".zhihu.com" / "zhihu.com"
+    # is sent to zhihu.com and any subdomain; a host-only cookie matches exactly.
+    d = domain.lstrip(".").lower()
+    h = host.lower()
+    return not d or h == d or h.endswith("." + d)
+
+
+def cookie_header(jar: list[dict], url: str) -> str:
+    # Only send a cookie to a host inside its domain scope, so a jar is never
+    # replayed outside the platform it was captured for (defense in depth — all
+    # request URLs here are first-party, but this future-proofs multi-platform).
+    host = urllib.parse.urlsplit(url).hostname or ""
+    # A domainless cookie has no scope of its own; only send it to a host the
+    # jar's domain-scoped cookies already cover (i.e. this jar's own platform),
+    # never fail-open to an arbitrary host.
+    host_in_scope = any(
+        c.get("domain") and _domain_matches(host, str(c["domain"])) for c in jar
+    )
+    parts = []
+    for c in jar:
+        name, value = c.get("name"), c.get("value")
+        if not name or value is None:
+            continue
+        domain = c.get("domain")
+        if domain:
+            if not _domain_matches(host, str(domain)):
+                continue
+        elif not host_in_scope:
+            continue
+        parts.append(f"{name}={value}")
+    return "; ".join(parts)
+
+
+# ── HTTP (stdlib urllib) ────────────────────────────────────────────
+
+def request(method: str, url: str, jar: list[dict], *, headers=None, body=None):
+    hdrs = {
+        "User-Agent": UA,
+        "Accept": "application/json, text/plain, */*",
+        "Cookie": cookie_header(jar, url),
+    }
+    if headers:
+        hdrs.update(headers)
+    data = None
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        hdrs.setdefault("Content-Type", "application/json")
+    req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            raw = resp.read()
+            if resp.headers.get("Content-Encoding") == "gzip":
+                raw = gzip.decompress(raw)
+            return resp.status, raw.decode("utf-8", "replace")
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            if e.headers.get("Content-Encoding") == "gzip":
+                raw = gzip.decompress(raw)
+        except Exception:
+            pass
+        return e.code, raw.decode("utf-8", "replace")
+    except urllib.error.URLError as e:
+        die(f"network error reaching {url}: {e.reason}")
+
+
+def get_json(url: str, jar: list[dict], **kw):
+    status, text = request("GET", url, jar, **kw)
+    if status == 401 or status == 403:
+        die(
+            f"auth failed ({status}) on {url} — the cookie is likely expired. "
+            f"Reconnect at https://auth.acedata.cloud/user/connections."
+        )
+    try:
+        return status, json.loads(text)
+    except json.JSONDecodeError:
+        die(f"non-JSON response ({status}) from {url}: {text[:300]}")
+
+
+# ── Zhihu ───────────────────────────────────────────────────────────
+
+ZH = {
+    "me": "https://www.zhihu.com/api/v4/me",
+    "articles": "https://www.zhihu.com/api/v4/members/{token}/articles",
+    "article": "https://www.zhihu.com/api/v4/articles/{id}",
+    "create_draft": "https://zhuanlan.zhihu.com/api/articles/drafts",
+}
+ZH_FETCH = {"x-requested-with": "fetch"}
+
+
+def zh_me(jar):
+    _, data = get_json(ZH["me"], jar, headers=ZH_FETCH)
+    if not data.get("id"):
+        die(f"could not read Zhihu profile (cookie expired?): {str(data)[:300]}")
+    return data
+
+
+def cmd_whoami(jar, _args):
+    me = zh_me(jar)
+    out({
+        "id": str(me.get("id", "")),
+        "name": me.get("name"),
+        "url_token": me.get("url_token"),
+        "headline": me.get("headline"),
+        "articles_count": me.get("articles_count"),
+        "voteup_count": me.get("voteup_count"),
+    })
+
+
+# Zhihu omits stats unless asked via `include`. This pulls the counts the
+# user actually cares about onto each article in the list/detail responses.
+ZH_ARTICLE_INCLUDE = "data[*].comment_count,voteup_count,created,updated,title,url"
+
+
+def _https(url):
+    if isinstance(url, str) and url.startswith("http://"):
+        return "https://" + url[len("http://"):]
+    return url
+
+
+def _fmt_article(a: dict) -> dict:
+    aid = a.get("id")
+    # Prefer the canonical public reader URL built from the id — the API's own
+    # `url` field is inconsistent (zhuanlan in the list, api.zhihu.com in detail).
+    return {
+        "id": str(aid) if aid is not None else None,
+        "title": a.get("title"),
+        "url": (f"https://zhuanlan.zhihu.com/p/{aid}" if aid else _https(a.get("url"))),
+        "voteup_count": a.get("voteup_count"),
+        "comment_count": a.get("comment_count"),
+        "created": a.get("created"),
+        "updated": a.get("updated"),
+    }
+
+
+def cmd_articles(jar, args):
+    me = zh_me(jar)
+    token = me.get("url_token")
+    if not token:
+        die("Zhihu profile has no url_token; cannot list articles.")
+    url = ZH["articles"].format(token=token)
+    q = urllib.parse.urlencode({
+        "include": ZH_ARTICLE_INCLUDE,
+        "limit": args.limit,
+        "offset": args.offset,
+    })
+    _, data = get_json(f"{url}?{q}", jar, headers=ZH_FETCH)
+    items = data.get("data", []) if isinstance(data, dict) else []
+    out({
+        "total": (data.get("paging") or {}).get("totals") if isinstance(data, dict) else None,
+        "count": len(items),
+        "articles": [_fmt_article(a) for a in items],
+    })
+
+
+def cmd_article(jar, args):
+    base = ZH["article"].format(id=args.id)
+    q = urllib.parse.urlencode({"include": "comment_count,voteup_count"})
+    _, a = get_json(f"{base}?{q}", jar, headers=ZH_FETCH)
+    if not isinstance(a, dict) or not a.get("id"):
+        die(f"article {args.id} not found or not accessible: {str(a)[:300]}")
+    res = _fmt_article(a)
+    res["content_excerpt"] = (a.get("excerpt") or "")[:200]
+    out(res)
+
+
+def cmd_publish(jar, args):
+    if not args.title:
+        die("--title is required")
+    if not args.content_file and args.content is None:
+        die("provide --content-file <path> or --content <html>")
+    content = args.content
+    if args.content_file:
+        try:
+            with open(args.content_file, encoding="utf-8") as f:
+                content = f.read()
+        except OSError as e:
+            die(f"cannot read --content-file: {e}")
+
+    if not CONFIRM:
+        out({
+            "dry_run": True,
+            "command": "publish",
+            "platform": "zhihu",
+            "title": args.title,
+            "draft_only": args.draft_only,
+            "content_bytes": len(content or ""),
+            "note": "re-run with --confirm as the LAST argument to actually write. "
+                    "Without --draft-only this publishes a PUBLIC article on the user's real account.",
+        })
+        return
+
+    # 1. create empty draft
+    status, text = request(
+        "POST", ZH["create_draft"], jar, headers=ZH_FETCH,
+        body={"title": args.title, "content": "", "delta_time": 0},
+    )
+    try:
+        created = json.loads(text)
+    except json.JSONDecodeError:
+        die(f"create-draft returned non-JSON ({status}): {text[:300]}")
+    draft_id = created.get("id")
+    if not draft_id:
+        die(f"create-draft failed ({status}): {str(created)[:300]}")
+
+    # 2. set draft content
+    status, text = request(
+        "PATCH", f"https://zhuanlan.zhihu.com/api/articles/{draft_id}/draft", jar,
+        headers=ZH_FETCH, body={"title": args.title, "content": content},
+    )
+    if status >= 400:
+        die(f"update-draft failed ({status}) for {draft_id}: {text[:300]}")
+
+    if args.draft_only:
+        out({
+            "ok": True,
+            "draft_only": True,
+            "draft_id": str(draft_id),
+            "edit_url": f"https://zhuanlan.zhihu.com/write?draftId={draft_id}",
+        })
+        return
+
+    # 3. publish (go live)
+    status, text = request(
+        "PUT", f"https://zhuanlan.zhihu.com/api/articles/{draft_id}/publish", jar,
+        headers=ZH_FETCH, body={},
+    )
+    if status >= 400:
+        die(f"publish failed ({status}) for {draft_id}; it remains a draft: {text[:300]}")
+    out({
+        "ok": True,
+        "published": True,
+        "article_id": str(draft_id),
+        "url": f"https://zhuanlan.zhihu.com/p/{draft_id}",
+    })
+
+
+COMMANDS = {
+    "whoami": cmd_whoami,
+    "articles": cmd_articles,
+    "article": cmd_article,
+    "publish": cmd_publish,
+}
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="blog.py", description="cn-blog cookie CLI")
+    p.add_argument("--platform", default="zhihu", choices=["zhihu"],
+                   help="content platform (only zhihu is implemented today)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("whoami", help="show the logged-in account")
+
+    sp = sub.add_parser("articles", help="list the user's published articles + stats")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--offset", type=int, default=0)
+
+    sp = sub.add_parser("article", help="one article's details + stats")
+    sp.add_argument("id")
+
+    sp = sub.add_parser("publish", help="create/publish an article (GATED by trailing --confirm)")
+    sp.add_argument("--title")
+    sp.add_argument("--content", help="HTML content inline")
+    sp.add_argument("--content-file", help="path to an HTML file")
+    sp.add_argument("--draft-only", action="store_true",
+                    help="create a draft only; do NOT go public")
+
+    args = p.parse_args(ARGV)
+    jar = load_cookies(args.platform)
+    COMMANDS[args.command](jar, args)
+
+
+if __name__ == "__main__":
+    main()

package/skills/figma/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: figma
+description: Read Figma design files, nodes, rendered images and comments via the Figma REST API. Use when the user mentions Figma, a figma.com file link, implementing a design as code, extracting design tokens / colors / spacing, or summarizing comments on a design.
+when_to_use: |
+  Trigger when the user shares a Figma file URL or wants to read a
+  design — get the document tree / a specific frame, render a node to
+  PNG/SVG to "see" it, extract styles / tokens, or read comments.
+  Read-only. The file key comes from the Figma URL the user pastes.
+connections: [figma]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Read **Figma** via `curl + jq`. The user's OAuth bearer token is in
+`$FIGMA_TOKEN`; every call needs `Authorization: Bearer $FIGMA_TOKEN`. Base URL:
+`https://api.figma.com/v1`.
+
+Failures are `{"status":<code>,"err":"..."}` — show `err` verbatim. `403` means
+the token lacks the scope or the file isn't shared with the user. `404` = bad
+file key.
+
+The **file key** is the `figma.com/file/<KEY>/...` or `figma.com/design/<KEY>/...`
+segment of a pasted URL. A **node id** is in `?node-id=1-23` (Figma shows `1:23`;
+the API also accepts `1:23`).
+
+```bash
+F="https://api.figma.com/v1"; AUTH=(-H "Authorization: Bearer $FIGMA_TOKEN")
+# Who am I (account card)
+curl -sS "${AUTH[@]}" "$F/me" | jq '{handle, email}'
+# File document tree (name + top-level frames). Big files: prefer /nodes below.
+curl -sS "${AUTH[@]}" "$F/files/FILE_KEY?depth=2" \
+  | jq '{name, pages: [.document.children[] | {name, frames: [.children[]?.name]}]}'
+```
+
+## Read specific nodes & render images
+
+```bash
+KEY="FILE_KEY"
+# Just the nodes you care about (faster than the whole file)
+curl -sS "${AUTH[@]}" "$F/files/$KEY/nodes?ids=1:23,1:45" \
+  | jq '.nodes | to_entries[] | {id: .key, name: .value.document.name, type: .value.document.type}'
+
+# Render nodes to images — returns temporary CDN URLs (this is the "see it" tool)
+curl -sS "${AUTH[@]}" "$F/images/$KEY?ids=1:23&format=png&scale=2" \
+  | jq '.images'   # { "1:23": "https://...png" }
+```
+
+For design-to-code, render the frame to PNG (to view) and read its node JSON
+(layout/fills/typography) to extract exact colors, spacing and text.
+
+## Comments & projects
+
+```bash
+curl -sS "${AUTH[@]}" "$F/files/FILE_KEY/comments" \
+  | jq '.comments[] | {user: .user.handle, at: .created_at, message}'
+# Team projects → files (needs a team id from the Figma URL /team/<id>/...)
+curl -sS "${AUTH[@]}" "$F/teams/TEAM_ID/projects" | jq '.projects'
+```
+
+## Gotchas
+
+- Node ids: Figma URLs use `1-23` (dash); the API wants `1:23` (colon). Convert.
+- `/images` URLs are **temporary** — download/use them promptly, don't store.
+- `depth=` limits tree traversal; omit it only for small files or you'll pull
+  megabytes of node JSON.

package/skills/google-ads/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: google-ads
+description: Query Google Ads campaigns, ad groups, keywords and spend via the Google Ads API (GAQL searchStream). Use when the user mentions Google Ads, ad campaigns, ad spend / cost, impressions / clicks / conversions on ads, or campaign performance.
+when_to_use: |
+  Trigger when the user wants Google Ads reporting — list accessible
+  customers, campaign / ad-group / keyword performance, spend and
+  conversions. Read via GAQL. Needs the OAuth token PLUS a platform
+  developer token and a login-customer-id; if those env vars are
+  absent the connector isn't fully provisioned yet — tell the user.
+connections: [google/ads]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Query the **Google Ads API** via `curl + jq`. Three credentials are needed:
+
+- `$GOOGLE_ADS_TOKEN` — the user's OAuth bearer (`adwords` scope) →
+  `Authorization: Bearer $GOOGLE_ADS_TOKEN`
+- `$GOOGLE_ADS_DEVELOPER_TOKEN` — the platform's developer token (injected
+  server-side) → header `developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN`
+- `login-customer-id` — the manager (MCC) id under which calls are made; use the
+  target customer id, or `$GOOGLE_ADS_LOGIN_CUSTOMER_ID` if set (digits only, no
+  dashes).
+
+> **API version:** the base is `https://googleads.googleapis.com/<vNN>`. Google
+> ships a new `vNN` every ~4 months and retires old ones — set `VER` to the
+> **current** supported version (check developers.google.com/google-ads/api
+> release notes); the example uses `v18`.
+
+If `$GOOGLE_ADS_DEVELOPER_TOKEN` is empty, the connector isn't fully provisioned —
+say so rather than calling the API (it would 401/DEVELOPER_TOKEN_NOT_APPROVED).
+
+```bash
+VER="v18"; BASE="https://googleads.googleapis.com/$VER"
+AUTH=(-H "Authorization: Bearer $GOOGLE_ADS_TOKEN" -H "developer-token: $GOOGLE_ADS_DEVELOPER_TOKEN")
+# Customers the OAuth user can access (ids are returned as customers/<id>)
+curl -sS "${AUTH[@]}" "$BASE/customers:listAccessibleCustomers" | jq '.resourceNames'
+```
+
+## Report with GAQL (searchStream)
+
+```bash
+CID="1234567890"   # target customer id, digits only
+curl -sS "${AUTH[@]}" -H "login-customer-id: ${GOOGLE_ADS_LOGIN_CUSTOMER_ID:-$CID}" \
+  -H "Content-Type: application/json" -d '{
+  "query":"SELECT campaign.name, metrics.cost_micros, metrics.clicks, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
+}' "$BASE/customers/$CID/googleAds:searchStream" \
+  | jq '.[].results[]? | {campaign: .campaign.name, cost_usd: (.metrics.costMicros|tonumber/1e6), clicks: .metrics.clicks, conv: .metrics.conversions}'
+```
+
+GAQL resources: `campaign`, `ad_group`, `ad_group_criterion` (keywords),
+`customer`. Cost is `metrics.cost_micros` (÷ 1,000,000 = account currency).
+
+## Gotchas
+
+- **Three headers, not one.** Missing `developer-token` or `login-customer-id`
+  is the #1 cause of 401/403 here.
+- Customer ids are **digits only** in URLs/headers (strip the dashes from
+  `123-456-7890`).
+- `searchStream` returns an array of chunks each with `.results[]` — flatten with
+  `.[].results[]?`.
+- Cost is in **micros** of the account currency; divide by 1e6.