@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/content/wechat-article-writer/templates/wechat-insight.md

@@ -0,0 +1,50 @@
+# WeChat article: 观察型（行业洞察 + 深度观点）
+
+## Use when
+
+作者看到了一个读者还没注意到的趋势、现象或政策影响，想告诉读者它意味着什么。目标是建立行业权威和长期读者，不卖课、不硬推产品。
+
+- 作者有一手踩坑经历和解决步骤 → **wechat-pitfall**。
+- 话题是两个选项的取舍 → **wechat-comparison**。
+
+## Tone
+
+可以用「我们」增加权威感；立场明确，但承认局限，不过度自信。B2B 读者接受稍长的文章（1200–1500 字）。
+
+## Inputs
+
+- 观察到的现象或数据点，以及出处。Material: ask once。没有出处的数据不写。
+- 作者的判断和预测。判断可以是观点，但要标明前提。
+- 读者的身份，用来落到「对你意味着什么」。
+- 品牌和 CTA：来自 WRITING.md。
+
+## Reasoning
+
+「我看到了一个别人没注意到的趋势，告诉你它意味着什么」：
+
+1. 用一个具体现象或数据点开头，让读者觉得「我也注意到了」。
+2. 从 2–3 个视角拆解：现象（1–2 句）→ 背后的原因 → 影响谁。不堆新闻，要给分析。
+3. 明确表态「我们认为……」，给出预测，并写出判断成立的前提和可能推翻它的条件。
+4. 落到读者的实际操作：「如果你是 X，现在应该关注 Y，可以先做 Z」。
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **标题** (Required): 观察 + 为什么 / 背后 / 意味着什么。示例：「越来越多跨境商家在换支付网关——背后发生了什么？」。
+2. **开头（约 200 字）** (Required): 一个具体现象或有出处的数据点。
+3. **现象拆解** (Required): 2–3 个视角，每个：现象 → 原因 → 影响谁。
+4. **我们的判断** (Required): 立场、预测、前提和不确定性。
+5. **对读者的意义** (Required): 按读者身份给出现在该做的事。
+6. **结尾** (Required): 金句表达判断或态度；CTA 按 WRITING.md，默认邀请留言讨论。
+
+## Done when
+
+- 开头的现象或数据有出处？
+- 每个视角都有分析，而不只是新闻罗列？
+- 判断明确，并写出了前提？
+- 读者知道自己接下来该关注或做什么？
+
+## Sources
+
+Rewritten from this skill's former `references/style-insight.md` into the template contract; improve per account with `distill-writing`.

package/skills/content/wechat-article-writer/templates/wechat-pitfall.md

@@ -0,0 +1,52 @@
+# WeChat article: 踩坑型（真人踩坑 + 工具化输出）
+
+## Use when
+
+读者在同一个痛点上普遍焦虑，作者或客户真实踩过这个坑，并且问题有可操作的解决路径。读者读完要能避开这个坑，并拿走一份可执行的清单。
+
+- 没有真实经历、只有观点 → **wechat-insight**。
+- 只需要照着做的步骤，不需要讲踩坑过程 → **wechat-howto**。
+- 坑的本质是两个概念搞混 → **wechat-comparison**。
+
+## Tone
+
+开头可以有情绪（B2B 克制：「压力很大」，不是「心态崩了」），分析部分回归理性，方案部分务实。
+
+## Inputs
+
+- 踩坑经历本身：谁、遇到什么、排查了多久、最后发现什么。Material: ask once。没有真实经历就换风格，不编故事。
+- 原因背后的案例和数据。只用作者提供的；没有就写定性描述，不写「我们拆了 50 个案例」这类数字。
+- 解决步骤和工具。缺失的步骤标记 `【待确认：…】`，不补造。
+- 品牌和 CTA：来自 WRITING.md；没有则用中性 CTA（留言、关注）。
+
+## Reasoning
+
+「我的痛苦 → 你的解决方案」：
+
+1. 用第一人称讲清楚遇到的问题和情绪点，让读者觉得「这说的就是我」。
+2. 拆出 3 个核心原因，每个先一句话结论，再解释，再说明为什么容易被忽略。
+3. 把经验转成按顺序的解决步骤，分情况给方案。
+4. 收敛成一份可勾选的清单，最后用一句金句点出踩坑的本质。
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **标题** (Required): 踩坑 + 数字 + 顿悟感；数字必须来自素材。示例：「选错支付网关，我们损失了 3 个月——问题出在这里」。
+2. **开头（约 200 字）** (Required): 第一人称叙事、情绪点、建立可信度。不要从定义或背景开始。
+3. **原因分析** (Required): 3 个原因，每个约 200 字：结论句 → 解释 + 来源中的案例或数据 → 为什么被忽略。
+4. **解决方案** (Required): 按顺序的具体步骤，附工具、方法或代码；多方案时分情况。
+5. **CheckList** (Required): 5–8 条，`- [ ] 检查/确认/避免 …`。
+6. **结尾金句 + CTA** (Required): 一句总结踩坑本质的金句；CTA 按 WRITING.md。
+
+## Done when
+
+- 开头 200 字里有第一人称经历，而不是定义或背景？
+- 每个原因都以一句结论开头？
+- 每个数字和案例都来自作者素材？
+- 解决步骤能照着做，清单能直接勾选？
+- 结尾是金句加 CTA？
+
+## Sources
+
+Rewritten from this skill's former `references/style-pitfall.md` into the template contract; improve per account with `distill-writing`.

package/skills/content/wechat-publisher/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/content/wechat-publisher/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: wechat-publisher
+description: "Publish articles to a WeChat Official Account (公众号) via API: push Markdown to the draft box (or auto-publish with --publish), convert Markdown to WeChat HTML, upload images to the media library. Requires AppID + AppSecret + whitelisted server IP on a 认证订阅号/服务号. Consumes wechat-article-writer's Markdown."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# WeChat Publisher (公众号发布)
+
+Publish articles to WeChat Official Account via the official API.
+
+**Full API reference:** `references/api.md` — read when debugging errors or needing endpoint details.
+
+**WeChat-safe layout reference:** `references/wechat-safe-template.html` — read when drafting or fixing article HTML that must survive WeChat rendering.
+
+## Prerequisites (check before starting)
+
+1. **AppID + AppSecret** — from WeChat MP Admin → 开发 → 基本配置
+2. **IP Whitelist** — server's IPv4 must be added in the same page
+3. **Account type** — must be 认证订阅号 or 认证服务号 (personal accounts lost API access in 2025-07)
+4. **Cover image** — JPEG/PNG, ≤64KB (WeChat `thumb` type limit)
+
+Get AppID/AppSecret from `~/.openclaw/openclaw.json` → `channels.weixin` if already configured.
+
+## Standard Workflow
+
+## WeChat-safe HTML rules (important)
+
+When generating or polishing article HTML for WeChat, treat WeChat as a constrained renderer, not a normal browser.
+
+Use these rules for layout-sensitive areas:
+
+- Prefer a **small tag set**: `div`, `img`, `h1/h2/h3`, `pre/code`, and a small amount of `br`
+- Avoid relying on native paragraph and list rendering for precise spacing
+- Do **not** use `ul/li` when spacing matters, WeChat often reflows list items with extra gap
+- Do **not** use multiple `p` blocks inside styled cards for step lists, WeChat often re-renders them as loose paragraphs
+- For **steps**, prefer one `div` with manual line breaks:
+  - `第一步...<br>第二步...`
+- For **bullet lists**, prefer manual bullets in a plain block:
+  - `• 要点 A<br>• 要点 B`
+- For **screenshots**, do not place white screenshots directly on page background
+  - Wrap screenshots in an outer container with white background, padding, light gray border, and rounded corners
+  - Example wrapper pattern:
+
+```html
+<div style="margin:10px 0;padding:6px;background:#fff;border:1px solid #e5e7eb;border-radius:12px;line-height:0;">
+  <img src="..." style="width:100%;height:auto;border-radius:8px;display:block;">
+</div>
+```
+
+- For WeChat article body HTML, omit the visible in-body title if the WeChat draft title is already set separately
+- Keep structure shallow, avoid unnecessary nested wrappers
+- After push, if spacing still looks too loose in the WeChat editor, the final fallback is:
+  - select all
+  - set **段后距 = 0** inside WeChat editor
+
+These rules are more reliable than micro-tuning margin values like `margin-bottom: 6px -> 4px`.
+
+
+### Step 1 — Convert Markdown to HTML (if input is .md)
+
+```bash
+python3 {skillDir}/scripts/md_to_wechat_html.py article.md --output article.html
+```
+
+If the article already contains inline-styled HTML, skip this step.
+
+### Step 1.5 — Normalize HTML for WeChat editor behavior
+
+When the issue is not visual spacing but a **caret-only blank line in the WeChat editor**, treat it as a **block-boundary problem**, not a copywriting problem.
+
+Default rule:
+
+- Use **flat `<div>` blocks for body paragraphs**.
+- Treat `<p>` as an **anti-pattern** for WeChat publishing in this skill.
+
+Why this rule exists:
+
+- In real Agentier testing, multiple versions with `p` still produced a phantom blank editable block before an emphasized sentence.
+- Switching the whole article body to **pure `div` blocks** fixed the issue immediately.
+- Practical conclusion: WeChat may treat `p` boundaries as separate editable paragraph units even when CSS spacing looks correct.
+
+Operating principle:
+
+- Default to **editor stability over semantic HTML richness**.
+- If WeChat editor behavior and semantic markup conflict, prefer the structure that renders and edits reliably in WeChat.
+
+Use these rules:
+
+- Keep the body **one level deep**. Do not nest block elements inside other block elements.
+- Use one natural paragraph per `<div>`.
+- For emphasis, use `<div><strong>...</strong></div>`.
+- Remove empty nodes between blocks: no empty `<p>`, no placeholder `&nbsp;`, no repeated `<br>`, no zero-width filler characters.
+- Minify inter-block whitespace before publish when debugging editor quirks.
+
+Recommended safe structure:
+
+```html
+<div>正文段 1</div><div>正文段 2</div><div><strong>强调句</strong></div><div>正文段 3</div>
+```
+
+Anti-patterns to avoid:
+
+- `<p>` for body paragraphs
+- `blockquote`
+- `ul` / `li`
+- nested `div` / `section` wrappers
+- empty paragraph tags
+- mixed paragraph systems (`p` + `div` in the same article body)
+
+### Step 2 — Publish to Draft Box
+
+```bash
+python3 {skillDir}/scripts/publish.py \
+  --appid <APPID> \
+  --appsecret <APPSECRET> \
+  --title "文章标题" \
+  --html article.html \
+  --thumb-image cover.jpg \
+  --author "作者名" \
+  --digest "摘要（最多120字）"
+```
+
+Output: `{ "ok": true, "draft_media_id": "xxx" }`
+
+The article now appears in the draft box. Open **微信公众号助手 App** on mobile → 草稿箱 → review → publish.
+
+### Step 3 (optional) — Auto-publish Live
+
+Add `--publish` flag to push live immediately (skips manual review):
+
+```bash
+python3 {skillDir}/scripts/publish.py ... --publish
+```
+
+Output: `{ "ok": true, "draft_media_id": "xxx", "publish_id": "yyy", "publish_status": {"status": "success"} }`
+
+⚠️ Only use `--publish` when Jonas explicitly approves skipping manual review.
+
+## Inline Image Handling
+
+If the article HTML contains local image paths (`<img src="./images/foo.png">`), upload them first:
+
+```python
+# Quick one-liner to get the WeChat CDN URL for an image
+import subprocess, json
+result = subprocess.run([
+    "python3", "-c",
+    """
+import requests, sys
+token = sys.argv[1]
+with open(sys.argv[2], 'rb') as f:
+    r = requests.post(f'https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token={token}', files={'media': f})
+print(r.json()['url'])
+""",
+    "<token>", "image.jpg"
+], capture_output=True, text=True)
+print(result.stdout.strip())
+```
+
+Then replace `src="./images/foo.png"` with the returned CDN URL in the HTML.
+
+## Error Quick-Reference
+
+| Error | Fix |
+|-------|-----|
+| `40164` IP not in whitelist | Add server IP in WeChat MP Admin |
+| `48001` API not authorized | Account not certified or permission missing |
+| `40007` invalid media_id | Cover image upload failed — retry upload |
+| `45009` rate limit | Wait for next day or reset quota in MP Admin |
+
+Full error codes: `references/api.md`

package/skills/content/wechat-publisher/references/api.md

@@ -0,0 +1,105 @@
+# WeChat Official Account API Reference
+
+## Authentication
+
+**Get access_token** (valid 2 hours; cached in `/tmp/wechat_access_token.json`)
+```
+GET https://api.weixin.qq.com/cgi-bin/token
+  ?grant_type=client_credential&appid=APPID&secret=APPSECRET
+→ { "access_token": "...", "expires_in": 7200 }
+```
+Daily limit: 2000 calls. Always cache; never call per-request.
+
+**IP Whitelist** — The calling server's IP must be added in:
+WeChat MP Admin → 开发 → 基本配置 → IP白名单
+
+---
+
+## Content Publishing Flow
+
+### Step 1: Upload cover image (permanent material)
+```
+POST https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=TOKEN&type=thumb
+  multipart/form-data: media=<file>
+→ { "media_id": "...", "url": "..." }
+```
+- Cover image: JPEG/PNG, **≤64 KB** for `thumb` type
+- Returns `media_id` for use in draft creation
+
+### Step 2: Upload inline images (article body)
+```
+POST https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=TOKEN
+  multipart/form-data: media=<file>
+→ { "url": "https://mmbiz.qpic.cn/..." }
+```
+- Any images in the article HTML body must be replaced with these CDN URLs
+- External image URLs will NOT render inside WeChat
+
+### Step 3: Create draft
+```
+POST https://api.weixin.qq.com/cgi-bin/draft/add?access_token=TOKEN
+{
+  "articles": [{
+    "title": "文章标题",
+    "author": "作者名",
+    "digest": "摘要（≤120字）",
+    "content": "<p>HTML正文</p>",
+    "thumb_media_id": "<from step 1>",
+    "need_open_comment": 0,
+    "only_fans_can_comment": 0
+  }]
+}
+→ { "media_id": "draft_media_id" }
+```
+Daily limit: 1000 drafts
+
+### Step 4 (optional): Publish draft live
+```
+POST https://api.weixin.qq.com/cgi-bin/freepublish/submit?access_token=TOKEN
+{ "media_id": "draft_media_id" }
+→ { "errcode": 0, "publish_id": "123456" }
+```
+Daily limit: 100 publishes
+
+### Step 5 (optional): Poll publish status
+```
+POST https://api.weixin.qq.com/cgi-bin/freepublish/get?access_token=TOKEN
+{ "publish_id": "123456" }
+→ { "publish_status": 0, "article_id": "..." }
+```
+`publish_status`: 0=成功, 1=发布中, 2=失败, 4=已删除
+
+---
+
+## Account Type Requirements
+
+| Feature | 个人未认证订阅号 | 认证订阅号 | 认证服务号 |
+|---------|--------------|----------|----------|
+| 草稿箱/发布 API | ❌ (2025-07 回收) | ✅ | ✅ |
+| 群发接口 | ❌ | ✅ | ✅ |
+| 模板消息 | ❌ | ❌ | ✅ |
+| 网页授权/支付 | ❌ | ❌ | ✅ |
+
+**Minimum requirement: 认证订阅号 (企业/组织主体)**
+
+---
+
+## HTML Content Requirements
+
+- All CSS must be **inline** — no `<style>` tags, no external CSS
+- No `<html>`, `<head>`, `<body>` wrapper (WeChat provides it)
+- Images: must be WeChat CDN URLs (upload first via `uploadimg`)
+- Font size: 14–16px recommended for mobile
+- Line height: 1.6–1.8 for readability
+
+---
+
+## Common Error Codes
+
+| errcode | Meaning | Fix |
+|---------|---------|-----|
+| 40001 | invalid access_token | Refresh token |
+| 40164 | IP not in whitelist | Add server IP to whitelist |
+| 45009 | API rate limit exceeded | Wait or reset quota |
+| 48001 | API not authorized | Account not certified or lacks permission |
+| 40007 | invalid media_id | Re-upload the media |

package/skills/content/wechat-publisher/references/layout-rules.md

@@ -0,0 +1,57 @@
+# WeChat-safe layout rules
+
+Use this reference when article HTML must survive WeChat draft/editor rendering.
+
+## Core rule
+
+Treat WeChat as a constrained renderer, not a normal browser.
+
+## Team rules
+
+1. Prefer a small tag set
+   - `div`
+   - `img`
+   - `h1/h2/h3`
+   - `pre/code`
+   - a small amount of `br`
+
+2. Do not rely on native list or paragraph spacing when layout matters
+   - avoid `ul/li`
+   - avoid multiple `p` blocks inside styled cards
+
+3. Build steps as one block
+   - use one `div`
+   - separate lines with `<br>`
+
+4. Build bullets manually
+   - use `•` in a plain `div`
+   - do not use native list markup for spacing-sensitive sections
+
+5. Always wrap white screenshots
+   - white background
+   - padding
+   - light gray border
+   - rounded corners
+
+6. Keep body HTML title-free
+   - the WeChat draft title is configured separately
+   - do not repeat the article title inside body HTML
+
+7. Keep section hierarchy readable
+   - section headings need visible top spacing
+   - subsection headings also need top spacing, but less than sections
+
+8. Use WeChat editor as final fallback
+   - if the draft still looks too loose, select all and set `段后距 = 0`
+
+## Most common failure patterns
+
+- margin micro-tweaks that do not survive WeChat rendering
+- `ul/li` producing unexpected extra space
+- card blocks made of many child paragraphs/divs becoming loose after push
+- white screenshots visually disappearing into page background
+
+## Recommended reference files
+
+- `wechat-safe-template.html` for reusable HTML skeleton
+- `api.md` for publishing/debugging details

package/skills/content/wechat-publisher/references/wechat-safe-template.html

@@ -0,0 +1,86 @@
+<section style="max-width:720px;margin:0 auto;padding:0;color:#2c2c2c;line-height:1.75;font-size:16px;">
+  <!-- Intro: do not repeat the article title here, WeChat draft title is set separately -->
+  <div style="margin:0 0 10px;">开头导语第一段，直接讲清楚这篇文章要解决什么问题。</div>
+  <div style="margin:0 0 12px;">开头导语第二段，补充使用场景、适合谁读，以及读完后能得到什么。</div>
+
+  <!-- Screenshot wrapper: use for white UI screenshots -->
+  <div style="margin:10px 0;padding:6px;background:#fff;border:1px solid #e5e7eb;border-radius:12px;line-height:0;">
+    <img src="https://example.com/hero.png" alt="示意图" style="width:100%;height:auto;border-radius:8px;display:block;">
+  </div>
+
+  <!-- Section -->
+  <h2 style="font-size:22px;line-height:1.45;margin:40px 0 12px;padding-left:10px;border-left:4px solid #07c160;color:#111;">开始前先确认</h2>
+  <div style="background:#f7faf7;border-radius:10px;padding:12px 14px;margin:0 0 10px;">
+    <strong>1.</strong> 前提条件 A<br>
+    <strong>2.</strong> 前提条件 B
+  </div>
+  <div style="margin:0 0 12px;">补一句解释，告诉读者顺序或范围。</div>
+
+  <!-- Section + subsection spacing -->
+  <h2 style="font-size:22px;line-height:1.45;margin:40px 0 12px;padding-left:10px;border-left:4px solid #07c160;color:#111;">安装与配置</h2>
+  <h3 style="font-size:18px;margin:24px 0 10px;color:#111;">1）先完成基础环境</h3>
+  <div style="margin:0 0 8px;">这里放一行解释性正文。</div>
+  <pre style="background:#f6f6f6;border-radius:10px;padding:12px 14px;overflow:auto;font-size:14px;line-height:1.6;margin:0 0 10px;"><code>command --help</code></pre>
+  <div style="margin:0 0 12px;">这里放一行解释性补充。</div>
+
+  <h3 style="font-size:18px;margin:24px 0 10px;color:#111;">2）再完成工具安装</h3>
+  <div style="margin:0 0 8px;">这里放安装说明。</div>
+
+  <!-- Steps: use one block + br, not multiple p/div children inside a card -->
+  <h2 style="font-size:22px;line-height:1.45;margin:40px 0 12px;padding-left:10px;border-left:4px solid #07c160;color:#111;">第一次上手</h2>
+  <div style="background:#fafafa;border-radius:10px;padding:12px 14px;margin:0 0 10px;">
+    <strong>第一步：</strong>做动作 A<br>
+    <strong>第二步：</strong>做动作 B<br>
+    <strong>第三步：</strong>做动作 C<br>
+    <strong>第四步：</strong>完成一个最小任务
+  </div>
+
+  <!-- Side-by-side phone screenshots if proportions match -->
+  <div style="display:flex;gap:12px;align-items:flex-start;justify-content:center;margin:10px 0;">
+    <div style="flex:0 0 48%;max-width:48%;padding:6px;background:#fff;border:1px solid #e5e7eb;border-radius:12px;line-height:0;box-sizing:border-box;">
+      <img src="https://example.com/phone-1.png" alt="手机截图 1" style="width:100%;height:auto;border-radius:8px;display:block;">
+    </div>
+    <div style="flex:0 0 48%;max-width:48%;padding:6px;background:#fff;border:1px solid #e5e7eb;border-radius:12px;line-height:0;box-sizing:border-box;">
+      <img src="https://example.com/phone-2.png" alt="手机截图 2" style="width:100%;height:auto;border-radius:8px;display:block;">
+    </div>
+  </div>
+
+  <!-- Bullets: use manual bullets, not ul/li -->
+  <div style="margin:0 0 8px;">完成后，你就可以：</div>
+  <div style="margin:0 0 10px;line-height:1.8;">
+    • 做事情 A<br>
+    • 做事情 B<br>
+    • 做事情 C
+  </div>
+
+  <h3 style="font-size:18px;margin:24px 0 10px;color:#111;">第一次建议跑这类任务</h3>
+  <div style="margin:0 0 10px;line-height:1.8;">
+    • 先让它总结项目是做什么的<br>
+    • 先让它找最值得看的几个文件<br>
+    • 先让它运行测试并回报结果
+  </div>
+
+  <!-- Single centered screenshot -->
+  <h2 style="font-size:22px;line-height:1.45;margin:40px 0 12px;padding-left:10px;border-left:4px solid #07c160;color:#111;">在手机上继续跟进</h2>
+  <div style="margin:0 0 8px;">当任务已经跑起来后，你可以在手机上继续跟进：</div>
+  <div style="margin:0 0 10px;line-height:1.8;">
+    • 查看进度<br>
+    • 补一句要求<br>
+    • 决定下一步
+  </div>
+  <div style="margin:10px 0;padding:6px;background:#fff;border:1px solid #e5e7eb;border-radius:12px;line-height:0;max-width:432px;margin-left:auto;margin-right:auto;">
+    <img src="https://example.com/mobile-task.png" alt="手机端截图" style="width:100%;height:auto;border-radius:8px;display:block;">
+  </div>
+  <div style="margin:6px 0 10px;text-align:center;color:#666;font-size:14px;">这里放一句简短图注。</div>
+
+  <!-- Closing card -->
+  <h2 style="font-size:22px;line-height:1.45;margin:40px 0 12px;padding-left:10px;border-left:4px solid #07c160;color:#111;">最后提醒</h2>
+  <div style="background:#fff8f0;border-radius:10px;padding:12px 14px;margin:0 0 10px;">
+    <strong>提醒一：</strong>一句提醒<br>
+    <strong>提醒二：</strong>一句提醒<br>
+    <strong>提醒三：</strong>一句提醒
+  </div>
+
+  <div style="margin:0 0 8px;"><strong>最后一句总结。</strong></div>
+  <div style="margin:0;">最后一句行动引导。</div>
+</section>

package/skills/content/wechat-publisher/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }