Deploy agent-card demo

Dockerfile

@@ -0,0 +1,19 @@
+FROM node:22-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY claw ./claw
+COPY public ./public
+COPY skills ./skills
+COPY src ./src
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=7860
+
+EXPOSE 7860
+
+CMD ["node", "src/server.js"]

README.md

@@ -1,10 +1,29 @@
 ---
 title: Agent Card
-emoji: ⚡
-colorFrom: red
-colorTo: blue
+emoji: 🤗
+colorFrom: yellow
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
+short_description: Hugging Face-style agent card demo for local coding agents.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Agent Card
+
+Prototype demo for an agent-card page inspired by the Hugging Face Hub model-card layout.
+
+## What it shows
+
+- `claw/AGENTS.md` rendered as the main agent card
+- skills discovered from local `SKILL.md` files
+- a `Use this agent` flow with:
+  - inference engine install/run snippets
+  - agent-specific config snippets
+- a `Use skills` flow that saves selected skills locally in the browser
+
+## Runtime notes
+
+- This Space runs the demo server from `src/server.js`.
+- The default reference model is `unsloth/gemma-4-26B-A4B-it-GGUF:Q4_K_M`.
+- The app reads the bundled `claw/` and `skills/` directories shipped in the Space image.

claw/AGENTS.md

@@ -0,0 +1,212 @@
+# AGENTS.md - Your Workspace
+
+This folder is home. Treat it that way.
+
+## First Run
+
+If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it. You won't need it again.
+
+## Every Session
+
+Before doing anything else:
+
+1. Read `SOUL.md` — this is who you are
+2. Read `USER.md` — this is who you're helping
+3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
+4. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`
+
+Don't ask permission. Just do it.
+
+## Memory
+
+You wake up fresh each session. These files are your continuity:
+
+- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened
+- **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory
+
+Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
+
+### 🧠 MEMORY.md - Your Long-Term Memory
+
+- **ONLY load in main session** (direct chats with your human)
+- **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
+- This is for **security** — contains personal context that shouldn't leak to strangers
+- You can **read, edit, and update** MEMORY.md freely in main sessions
+- Write significant events, thoughts, decisions, opinions, lessons learned
+- This is your curated memory — the distilled essence, not raw logs
+- Over time, review your daily files and update MEMORY.md with what's worth keeping
+
+### 📝 Write It Down - No "Mental Notes"!
+
+- **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
+- "Mental notes" don't survive session restarts. Files do.
+- When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file
+- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant skill
+- When you make a mistake → document it so future-you doesn't repeat it
+- **Text > Brain** 📝
+
+## Safety
+
+- Don't exfiltrate private data. Ever.
+- Don't run destructive commands without asking.
+- `trash` > `rm` (recoverable beats gone forever)
+- When in doubt, ask.
+
+## External vs Internal
+
+**Safe to do freely:**
+
+- Read files, explore, organize, learn
+- Search the web, check calendars
+- Work within this workspace
+
+**Ask first:**
+
+- Sending emails, tweets, public posts
+- Anything that leaves the machine
+- Anything you're uncertain about
+
+## Group Chats
+
+You have access to your human's stuff. That doesn't mean you _share_ their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
+
+### 💬 Know When to Speak!
+
+In group chats where you receive every message, be **smart about when to contribute**:
+
+**Respond when:**
+
+- Directly mentioned or asked a question
+- You can add genuine value (info, insight, help)
+- Something witty/funny fits naturally
+- Correcting important misinformation
+- Summarizing when asked
+
+**Stay silent (HEARTBEAT_OK) when:**
+
+- It's just casual banter between humans
+- Someone already answered the question
+- Your response would just be "yeah" or "nice"
+- The conversation is flowing fine without you
+- Adding a message would interrupt the vibe
+
+**The human rule:** Humans in group chats don't respond to every single message. Neither should you. Quality > quantity. If you wouldn't send it in a real group chat with friends, don't send it.
+
+**Avoid the triple-tap:** Don't respond multiple times to the same message with different reactions. One thoughtful response beats three fragments.
+
+Participate, don't dominate.
+
+### 😊 React Like a Human!
+
+On platforms that support reactions (Discord, Slack), use emoji reactions naturally:
+
+**React when:**
+
+- You appreciate something but don't need to reply (👍, ❤️, 🙌)
+- Something made you laugh (😂, 💀)
+- You find it interesting or thought-provoking (🤔, 💡)
+- You want to acknowledge without interrupting the flow
+- It's a simple yes/no or approval situation (✅, 👀)
+
+**Why it matters:**
+Reactions are lightweight social signals. Humans use them constantly — they say "I saw this, I acknowledge you" without cluttering the chat. You should too.
+
+**Don't overdo it:** One reaction per message max. Pick the one that fits best.
+
+## Tools
+
+Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
+
+**🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
+
+**📝 Platform Formatting:**
+
+- **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
+- **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
+- **WhatsApp:** No headers — use **bold** or CAPS for emphasis
+
+## 💓 Heartbeats - Be Proactive!
+
+When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
+
+Default heartbeat prompt:
+`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
+
+You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small to limit token burn.
+
+### Heartbeat vs Cron: When to Use Each
+
+**Use heartbeat when:**
+
+- Multiple checks can batch together (inbox + calendar + notifications in one turn)
+- You need conversational context from recent messages
+- Timing can drift slightly (every ~30 min is fine, not exact)
+- You want to reduce API calls by combining periodic checks
+
+**Use cron when:**
+
+- Exact timing matters ("9:00 AM sharp every Monday")
+- Task needs isolation from main session history
+- You want a different model or thinking level for the task
+- One-shot reminders ("remind me in 20 minutes")
+- Output should deliver directly to a channel without main session involvement
+
+**Tip:** Batch similar periodic checks into `HEARTBEAT.md` instead of creating multiple cron jobs. Use cron for precise schedules and standalone tasks.
+
+**Things to check (rotate through these, 2-4 times per day):**
+
+- **Emails** - Any urgent unread messages?
+- **Calendar** - Upcoming events in next 24-48h?
+- **Mentions** - Twitter/social notifications?
+- **Weather** - Relevant if your human might go out?
+
+**Track your checks** in `memory/heartbeat-state.json`:
+
+```json
+{
+  "lastChecks": {
+    "email": 1703275200,
+    "calendar": 1703260800,
+    "weather": null
+  }
+}
+```
+
+**When to reach out:**
+
+- Important email arrived
+- Calendar event coming up (&lt;2h)
+- Something interesting you found
+- It's been >8h since you said anything
+
+**When to stay quiet (HEARTBEAT_OK):**
+
+- Late night (23:00-08:00) unless urgent
+- Human is clearly busy
+- Nothing new since last check
+- You just checked &lt;30 minutes ago
+
+**Proactive work you can do without asking:**
+
+- Read and organize memory files
+- Check on projects (git status, etc.)
+- Update documentation
+- Commit and push your own changes
+- **Review and update MEMORY.md** (see below)
+
+### 🔄 Memory Maintenance (During Heartbeats)
+
+Periodically (every few days), use a heartbeat to:
+
+1. Read through recent `memory/YYYY-MM-DD.md` files
+2. Identify significant events, lessons, or insights worth keeping long-term
+3. Update `MEMORY.md` with distilled learnings
+4. Remove outdated info from MEMORY.md that's no longer relevant
+
+Think of it like a human reviewing their journal and updating their mental model. Daily files are raw notes; MEMORY.md is curated wisdom.
+
+The goal: Be helpful without being annoying. Check in a few times a day, do useful background work, but respect quiet time.
+
+## Make It Yours
+
+This is a starting point. Add your own conventions, style, and rules as you figure out what works.

package-lock.json

@@ -0,0 +1,37 @@
+{
+  "name": "hf-launch",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "hf-launch",
+      "version": "0.1.0",
+      "dependencies": {
+        "@huggingface/tasks": "^0.20.13",
+        "marked": "^16.0.0"
+      },
+      "bin": {
+        "hf-launch": "src/cli.js"
+      }
+    },
+    "node_modules/@huggingface/tasks": {
+      "version": "0.20.13",
+      "resolved": "https://registry.npmjs.org/@huggingface/tasks/-/tasks-0.20.13.tgz",
+      "integrity": "sha512-DrP7L8q6UMFJhRsstL5ELO/sxTL3UBZBY+JBKVUaJuORZ1AWtrUrML4hljm8zMuGHpRw9tw7BP2dbzp/+tuOAA==",
+      "license": "MIT"
+    },
+    "node_modules/marked": {
+      "version": "16.4.2",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-16.4.2.tgz",
+      "integrity": "sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==",
+      "license": "MIT",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 20"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "hf-launch",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Prototype CLI for turning Hugging Face local-app metadata into agent onboarding artifacts.",
+  "bin": {
+    "hf-launch": "./src/cli.js"
+  },
+  "scripts": {
+    "demo": "node src/server.js",
+    "space:stage": "node scripts/stage-space.mjs",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@huggingface/tasks": "^0.20.13",
+    "marked": "^16.0.0"
+  }
+}

public/app.js

@@ -0,0 +1,765 @@
+const SKILLS_STORAGE_KEY = "hf-launch.demo.saved-skills";
+
+const state = {
+  payload: null,
+  selectedRuntimeKey: null,
+  selectedAgentKey: null,
+  selectedRuntimeExampleKey: null,
+  selectedSkillPath: null,
+  savedSkillPaths: loadSavedSkillPaths(),
+  lastSkillsSaveMessage: ""
+};
+
+const elements = {
+  agentTitle: document.getElementById("agent-title"),
+  agentTitleInline: document.getElementById("agent-title-inline"),
+  agentSummary: document.getElementById("agent-summary"),
+  useAgentButton: document.getElementById("use-agent-button"),
+  cardTitle: document.getElementById("card-title"),
+  cardPathLabel: document.getElementById("card-path-label"),
+  cardPathPill: document.getElementById("card-path-pill"),
+  agentCard: document.getElementById("agent-card"),
+  modelName: document.getElementById("model-name"),
+  modelMeta: document.getElementById("model-meta"),
+  useSkillsButton: document.getElementById("use-skills-button"),
+  skillsTableBody: document.getElementById("skills-table-body"),
+  runtimeModal: document.getElementById("runtime-modal"),
+  closeModalButton: document.getElementById("close-modal-button"),
+  runtimeTabs: document.getElementById("runtime-tabs"),
+  agentTabs: document.getElementById("agent-tabs"),
+  runtimeMeta: document.getElementById("runtime-meta"),
+  runtimeExampleGroup: document.getElementById("runtime-example-group"),
+  runtimeExampleTabs: document.getElementById("runtime-example-tabs"),
+  runtimePanel: document.getElementById("runtime-panel"),
+  skillModal: document.getElementById("skill-modal"),
+  closeSkillModalButton: document.getElementById("close-skill-modal-button"),
+  skillModalTitle: document.getElementById("skill-modal-title"),
+  skillSummary: document.getElementById("skill-summary"),
+  skillMeta: document.getElementById("skill-meta"),
+  skillPathPill: document.getElementById("skill-path-pill"),
+  skillCardBody: document.getElementById("skill-card-body"),
+  useSkillsModal: document.getElementById("use-skills-modal"),
+  closeUseSkillsModalButton: document.getElementById("close-use-skills-modal-button"),
+  skillsPicker: document.getElementById("skills-picker"),
+  saveSkillsButton: document.getElementById("save-skills-button"),
+  skillsSaveStatus: document.getElementById("skills-save-status"),
+  codeCardTemplate: document.getElementById("code-card-template")
+};
+
+function loadSavedSkillPaths() {
+  try {
+    const rawValue = window.localStorage.getItem(SKILLS_STORAGE_KEY);
+    const parsed = rawValue ? JSON.parse(rawValue) : [];
+    return Array.isArray(parsed) ? parsed.filter((value) => typeof value === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function persistSavedSkillPaths(paths) {
+  try {
+    window.localStorage.setItem(SKILLS_STORAGE_KEY, JSON.stringify(paths));
+  } catch {
+    // Ignore storage failures in the prototype.
+  }
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function humanize(value) {
+  return String(value)
+    .replace(/_/g, " ")
+    .replace(/-/g, " ")
+    .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+
+function relativeFromRoot(absolutePath) {
+  if (!state.payload) {
+    return absolutePath;
+  }
+
+  const normalizedRoot = `${state.payload.workspaceRoot.replace(/\\/g, "/")}/`;
+  const normalizedPath = absolutePath.replace(/\\/g, "/");
+  return normalizedPath.startsWith(normalizedRoot) ? normalizedPath.slice(normalizedRoot.length) : normalizedPath;
+}
+
+function setExternalLinkBehavior(container) {
+  for (const link of container.querySelectorAll("a[href]")) {
+    if (link.getAttribute("href")?.startsWith("http")) {
+      link.target = "_blank";
+      link.rel = "noreferrer";
+    }
+  }
+}
+
+function copyText(button, text) {
+  navigator.clipboard.writeText(text).then(() => {
+    const originalLabel = button.textContent;
+    button.textContent = "Copied";
+    button.classList.add("is-copied");
+
+    window.setTimeout(() => {
+      button.textContent = originalLabel;
+      button.classList.remove("is-copied");
+    }, 1200);
+  });
+}
+
+function attachCopyButton(button, text) {
+  button.addEventListener("click", () => {
+    copyText(button, text);
+  });
+}
+
+function decorateCodeBlocks(container) {
+  for (const pre of container.querySelectorAll("pre")) {
+    if (pre.querySelector(".copy-button")) {
+      continue;
+    }
+
+    const button = document.createElement("button");
+    button.className = "copy-button pre-copy-button";
+    button.type = "button";
+    button.textContent = "Copy";
+    pre.appendChild(button);
+    attachCopyButton(button, pre.innerText.replace(/\nCopy$/, "").trimEnd());
+  }
+}
+
+function renderMetaList(items) {
+  return items
+    .map(
+      (item) => `
+        <div class="meta-row">
+          <dt>${escapeHtml(item.label)}</dt>
+          <dd>${item.value}</dd>
+        </div>
+      `
+    )
+    .join("");
+}
+
+function runtimeExampleKey(example) {
+  return example.title;
+}
+
+function labelRuntimeExample(example) {
+  const normalizedTitle = example.title.toLowerCase();
+  if (normalizedTitle.includes("winget") || normalizedTitle.includes("windows")) {
+    return "Windows";
+  }
+  if (normalizedTitle.includes("brew")) {
+    return "macOS";
+  }
+  if (normalizedTitle.includes("pip")) {
+    return "pip";
+  }
+  if (normalizedTitle.includes("source")) {
+    return "Source";
+  }
+  if (normalizedTitle.includes("binary")) {
+    return "Binary";
+  }
+
+  return humanize(
+    example.title
+      .replace(/^Install from\s+/i, "")
+      .replace(/^Use\s+/i, "")
+      .replace(/\s+and serve model$/i, "")
+  );
+}
+
+function syncBodyScrollLock() {
+  const hasOpenModal = [elements.runtimeModal, elements.skillModal, elements.useSkillsModal].some(
+    (modal) => modal && !modal.classList.contains("is-hidden")
+  );
+  document.body.style.overflow = hasOpenModal ? "hidden" : "";
+}
+
+function getActiveRuntime() {
+  return state.payload?.runtimes.find((runtime) => runtime.key === state.selectedRuntimeKey) ?? null;
+}
+
+function getActiveAgent() {
+  return state.payload?.agentOptions.find((agent) => agent.key === state.selectedAgentKey) ?? null;
+}
+
+function getActiveRuntimeExample(runtime = getActiveRuntime()) {
+  return runtime?.runtimeExamples?.find((example) => runtimeExampleKey(example) === state.selectedRuntimeExampleKey) ?? null;
+}
+
+function getActiveSkill() {
+  return state.payload?.skills.find((skill) => skill.relativePath === state.selectedSkillPath) ?? null;
+}
+
+function ensureSelections() {
+  if (!state.payload) {
+    return;
+  }
+
+  const availableRuntime = state.payload.runtimes.find((runtime) => runtime.key === state.selectedRuntimeKey);
+  const runtime = availableRuntime ?? state.payload.runtimes[0] ?? null;
+  state.selectedRuntimeKey = runtime?.key ?? null;
+
+  if (!runtime) {
+    state.selectedAgentKey = null;
+    state.selectedRuntimeExampleKey = null;
+    return;
+  }
+
+  const compatibleAgents = runtime.compatibleAgents ?? [];
+  if (!compatibleAgents.includes(state.selectedAgentKey)) {
+    state.selectedAgentKey = compatibleAgents.includes(state.payload.agent.key)
+      ? state.payload.agent.key
+      : compatibleAgents[0] ?? null;
+  }
+
+  const runtimeExamples = runtime.runtimeExamples ?? [];
+  const activeExample = runtimeExamples.find((example) => runtimeExampleKey(example) === state.selectedRuntimeExampleKey);
+  state.selectedRuntimeExampleKey = activeExample
+    ? runtimeExampleKey(activeExample)
+    : runtimeExamples[0]
+      ? runtimeExampleKey(runtimeExamples[0])
+      : null;
+}
+
+function renderHeader() {
+  const { agent } = state.payload;
+
+  document.title = `${agent.title} · Hugging Face`;
+  elements.agentTitle.textContent = agent.title;
+  elements.agentTitleInline.textContent = agent.title;
+  elements.agentSummary.textContent = agent.summary;
+  elements.cardTitle.textContent = agent.cardTitle;
+  elements.cardPathLabel.textContent = "Workspace file";
+  elements.cardPathPill.textContent = relativeFromRoot(agent.cardPath);
+}
+
+function renderModelMeta() {
+  const { model, runtimes } = state.payload;
+  elements.modelName.textContent = model.displayName;
+  elements.modelMeta.innerHTML = renderMetaList([
+    { label: "Repository", value: `<code>${escapeHtml(model.repoId)}</code>` },
+    { label: "Model ref", value: `<code>${escapeHtml(model.ref)}</code>` },
+    { label: "Pipeline", value: escapeHtml(humanize(model.pipelineTag)) },
+    { label: "Library", value: escapeHtml(model.libraryName) },
+    { label: "Engines", value: escapeHtml(runtimes.map((runtime) => runtime.label).join(", ")) }
+  ]);
+}
+
+function renderUseSkillsButton() {
+  const count = state.savedSkillPaths.length;
+  elements.useSkillsButton.textContent = count ? `Use skills (${count})` : "Use skills";
+}
+
+function openSkillModal(skillPath) {
+  state.selectedSkillPath = skillPath;
+  renderSkillModal();
+  elements.skillModal.classList.remove("is-hidden");
+  elements.skillModal.setAttribute("aria-hidden", "false");
+  syncBodyScrollLock();
+}
+
+function closeSkillModal() {
+  elements.skillModal.classList.add("is-hidden");
+  elements.skillModal.setAttribute("aria-hidden", "true");
+  syncBodyScrollLock();
+}
+
+function renderSkillsTable() {
+  elements.skillsTableBody.innerHTML = "";
+
+  for (const skill of state.payload.skills) {
+    const row = document.createElement("tr");
+    row.tabIndex = 0;
+    row.className = "skill-row";
+
+    if (state.savedSkillPaths.includes(skill.relativePath)) {
+      row.classList.add("is-saved");
+    }
+
+    const titleCell = document.createElement("td");
+    titleCell.textContent = skill.name;
+
+    const pathCell = document.createElement("td");
+    const pathCode = document.createElement("code");
+    pathCode.textContent = skill.relativePath;
+    pathCell.appendChild(pathCode);
+
+    row.append(titleCell, pathCell);
+    row.addEventListener("click", () => {
+      openSkillModal(skill.relativePath);
+    });
+    row.addEventListener("keydown", (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        openSkillModal(skill.relativePath);
+      }
+    });
+
+    elements.skillsTableBody.appendChild(row);
+  }
+}
+
+function buildCodeCard({ kicker, title, target, content }) {
+  const fragment = elements.codeCardTemplate.content.cloneNode(true);
+  fragment.querySelector(".snippet-kicker").textContent = kicker;
+  fragment.querySelector(".snippet-title").textContent = title;
+  fragment.querySelector(".snippet-target").textContent = target ?? "";
+  fragment.querySelector("code").textContent = content;
+
+  const button = fragment.querySelector(".copy-button");
+  attachCopyButton(button, content);
+
+  return fragment;
+}
+
+function renderRuntimeTabs() {
+  elements.runtimeTabs.innerHTML = "";
+
+  for (const runtime of state.payload.runtimes) {
+    const button = document.createElement("button");
+    button.className = `selection-pill${runtime.key === state.selectedRuntimeKey ? " is-active" : ""}`;
+    button.type = "button";
+    button.textContent = runtime.label;
+    button.addEventListener("click", () => {
+      state.selectedRuntimeKey = runtime.key;
+      ensureSelections();
+      renderModal();
+    });
+    elements.runtimeTabs.appendChild(button);
+  }
+}
+
+function renderAgentTabs(runtime) {
+  elements.agentTabs.innerHTML = "";
+
+  for (const agent of state.payload.agentOptions) {
+    const compatible = runtime.compatibleAgents.includes(agent.key);
+    const button = document.createElement("button");
+    button.className = `selection-pill${agent.key === state.selectedAgentKey ? " is-active" : ""}`;
+    button.type = "button";
+    button.textContent = agent.label;
+    button.disabled = !compatible;
+    if (!compatible) {
+      button.classList.add("is-disabled");
+    }
+    button.addEventListener("click", () => {
+      if (!compatible) {
+        return;
+      }
+      state.selectedAgentKey = agent.key;
+      renderModal();
+    });
+    elements.agentTabs.appendChild(button);
+  }
+}
+
+function renderRuntimeExampleTabs(runtime) {
+  const runtimeExamples = runtime.runtimeExamples ?? [];
+  elements.runtimeExampleTabs.innerHTML = "";
+  elements.runtimeExampleGroup.hidden = runtimeExamples.length === 0;
+
+  for (const example of runtimeExamples) {
+    const key = runtimeExampleKey(example);
+    const button = document.createElement("button");
+    button.className = `selection-pill${key === state.selectedRuntimeExampleKey ? " is-active" : ""}`;
+    button.type = "button";
+    button.textContent = labelRuntimeExample(example);
+    button.addEventListener("click", () => {
+      state.selectedRuntimeExampleKey = key;
+      renderModal();
+    });
+    elements.runtimeExampleTabs.appendChild(button);
+  }
+}
+
+function renderRuntimeMeta(runtime, agent) {
+  elements.runtimeMeta.innerHTML = "";
+
+  const summary = document.createElement("p");
+  summary.className = "modal-summary";
+
+  const summaryParts = [];
+  if (agent) {
+    summaryParts.push(`${agent.label} uses ${runtime.label} through the agent's existing provider config.`);
+  }
+
+  if (!runtime.baseUrl) {
+    summaryParts.push("Add the runtime base URL first so hf-launch can render the final config.");
+  } else if (runtime.servedModelId === "__PROBE_V1_MODELS__") {
+    summaryParts.push(`Base URL: ${runtime.baseUrl}. Probe /v1/models after startup to confirm the served model id.`);
+  } else {
+    summaryParts.push(`Base URL: ${runtime.baseUrl}. Served model: ${runtime.servedModelId}.`);
+  }
+
+  summary.textContent = summaryParts.join(" ");
+  elements.runtimeMeta.appendChild(summary);
+
+  if (runtime.docsUrl) {
+    const link = document.createElement("a");
+    link.className = "inline-link";
+    link.href = runtime.docsUrl;
+    link.textContent = "Runtime docs";
+    elements.runtimeMeta.appendChild(link);
+  }
+
+  setExternalLinkBehavior(elements.runtimeMeta);
+}
+
+function renderWarnings(runtime) {
+  if (!runtime.warnings.length) {
+    return "";
+  }
+
+  return `
+    <section class="note-card">
+      <ul class="warning-list">
+        ${runtime.warnings.map((warning) => `<li>${escapeHtml(warning)}</li>`).join("")}
+      </ul>
+    </section>
+  `;
+}
+
+function renderModal() {
+  ensureSelections();
+  const runtime = getActiveRuntime();
+  const agent = getActiveAgent();
+  renderRuntimeTabs();
+
+  if (!runtime) {
+    elements.runtimeMeta.innerHTML = "";
+    elements.runtimeExampleTabs.innerHTML = "";
+    elements.runtimeExampleGroup.hidden = true;
+    elements.runtimePanel.innerHTML = `<p class="empty-state">No runtime metadata is available for this model.</p>`;
+    return;
+  }
+
+  renderAgentTabs(runtime);
+  renderRuntimeMeta(runtime, agent);
+  renderRuntimeExampleTabs(runtime);
+
+  const runtimeExample = getActiveRuntimeExample(runtime);
+  const agentOutput = runtime.agentOutputs[state.selectedAgentKey] ?? null;
+  elements.runtimePanel.innerHTML = renderWarnings(runtime);
+
+  const warningsFragment = document.createElement("div");
+  warningsFragment.innerHTML = elements.runtimePanel.innerHTML;
+  elements.runtimePanel.innerHTML = "";
+  if (warningsFragment.firstElementChild) {
+    elements.runtimePanel.appendChild(warningsFragment.firstElementChild);
+  }
+
+  if (runtimeExample) {
+    elements.runtimePanel.appendChild(
+      buildCodeCard({
+        kicker: "Inference engine",
+        title: runtimeExample.title,
+        target: "Run this locally before starting the agent",
+        content: runtimeExample.content
+      })
+    );
+  }
+
+  if (agentOutput?.canGenerateAgentConfig) {
+    for (const file of agentOutput.files) {
+      elements.runtimePanel.appendChild(
+        buildCodeCard({
+          kicker: "Agent config",
+          title: file.name,
+          target: file.targetPath,
+          content: file.content
+        })
+      );
+    }
+
+    for (const command of agentOutput.cliCommands) {
+      elements.runtimePanel.appendChild(
+        buildCodeCard({
+          kicker: "Agent helper",
+          title: command.title,
+          target: "Run after the backend is up",
+          content: command.content
+        })
+      );
+    }
+
+    if (!runtimeExample && !agentOutput.files.length && !agentOutput.cliCommands.length) {
+      const message = document.createElement("p");
+      message.className = "empty-state";
+      message.textContent = "No snippets are available for this selection yet.";
+      elements.runtimePanel.appendChild(message);
+    }
+  } else {
+    const message = document.createElement("p");
+    message.className = "empty-state";
+    message.textContent =
+      "This runtime still needs a concrete base URL before hf-launch can render the final agent config.";
+    elements.runtimePanel.appendChild(message);
+  }
+
+  const footnote = document.createElement("p");
+  footnote.className = "modal-footnote";
+  footnote.textContent =
+    "hf-launch writes provider config and onboarding helpers. It does not start the backend or launch the agent process yet.";
+  elements.runtimePanel.appendChild(footnote);
+}
+
+function openModal() {
+  elements.runtimeModal.classList.remove("is-hidden");
+  elements.runtimeModal.setAttribute("aria-hidden", "false");
+  syncBodyScrollLock();
+}
+
+function closeModal() {
+  elements.runtimeModal.classList.add("is-hidden");
+  elements.runtimeModal.setAttribute("aria-hidden", "true");
+  syncBodyScrollLock();
+}
+
+function renderSkillModal() {
+  const skill = getActiveSkill();
+  if (!skill) {
+    return;
+  }
+
+  elements.skillModalTitle.textContent = skill.name;
+  elements.skillSummary.textContent = skill.description;
+  elements.skillPathPill.textContent = skill.relativePath;
+
+  const metadataItems = [
+    skill.homepage
+      ? {
+          label: "Homepage",
+          value: `<a class="inline-link" href="${escapeHtml(skill.homepage)}">${escapeHtml(skill.homepage)}</a>`
+        }
+      : null,
+    {
+      label: "User",
+      value: skill.userInvocable ? "User invocable" : "Agent only"
+    },
+    {
+      label: "Tools",
+      value: skill.allowedTools.length
+        ? skill.allowedTools.map((tool) => `<code>${escapeHtml(tool)}</code>`).join(", ")
+        : "None declared"
+    },
+    {
+      label: "Bins",
+      value: skill.requiresBins.length
+        ? skill.requiresBins.map((entry) => `<code>${escapeHtml(entry)}</code>`).join(", ")
+        : "None declared"
+    },
+    {
+      label: "Env",
+      value: skill.requiresEnv.length
+        ? skill.requiresEnv.map((entry) => `<code>${escapeHtml(entry)}</code>`).join(", ")
+        : "None declared"
+    },
+    {
+      label: "Config",
+      value: skill.requiresConfig.length
+        ? skill.requiresConfig.map((entry) => `<code>${escapeHtml(entry)}</code>`).join(", ")
+        : "None declared"
+    },
+    {
+      label: "Install",
+      value: skill.install.length ? skill.install.map((entry) => escapeHtml(entry)).join(", ") : "None declared"
+    },
+    {
+      label: "OS",
+      value: skill.os.length ? skill.os.map((entry) => escapeHtml(entry)).join(", ") : "Not specified"
+    }
+  ].filter(Boolean);
+
+  elements.skillMeta.innerHTML = renderMetaList(metadataItems);
+  elements.skillCardBody.innerHTML = skill.bodyHtml;
+
+  decorateCodeBlocks(elements.skillCardBody);
+  setExternalLinkBehavior(elements.skillMeta);
+  setExternalLinkBehavior(elements.skillCardBody);
+}
+
+function updateSkillsSaveStatus() {
+  if (state.lastSkillsSaveMessage) {
+    elements.skillsSaveStatus.textContent = state.lastSkillsSaveMessage;
+    return;
+  }
+
+  elements.skillsSaveStatus.textContent = state.savedSkillPaths.length
+    ? `${state.savedSkillPaths.length} skill${state.savedSkillPaths.length === 1 ? "" : "s"} saved locally.`
+    : "Selections are stored in this browser on the current machine.";
+}
+
+function renderUseSkillsModal() {
+  elements.skillsPicker.innerHTML = "";
+
+  for (const skill of state.payload.skills) {
+    const label = document.createElement("label");
+    label.className = "skill-picker-row";
+
+    const input = document.createElement("input");
+    input.type = "checkbox";
+    input.name = "saved-skills";
+    input.value = skill.relativePath;
+    input.checked = state.savedSkillPaths.includes(skill.relativePath);
+
+    const copy = document.createElement("div");
+    copy.className = "skill-picker-copy";
+
+    const title = document.createElement("strong");
+    title.textContent = skill.name;
+
+    const description = document.createElement("p");
+    description.className = "skill-picker-description";
+    description.textContent = skill.description;
+
+    const path = document.createElement("code");
+    path.className = "skill-picker-path";
+    path.textContent = skill.relativePath;
+
+    copy.append(title, description, path);
+    label.append(input, copy);
+    elements.skillsPicker.appendChild(label);
+  }
+
+  updateSkillsSaveStatus();
+}
+
+function openUseSkillsModal() {
+  state.lastSkillsSaveMessage = "";
+  renderUseSkillsModal();
+  elements.useSkillsModal.classList.remove("is-hidden");
+  elements.useSkillsModal.setAttribute("aria-hidden", "false");
+  syncBodyScrollLock();
+}
+
+function closeUseSkillsModal() {
+  elements.useSkillsModal.classList.add("is-hidden");
+  elements.useSkillsModal.setAttribute("aria-hidden", "true");
+  syncBodyScrollLock();
+}
+
+function saveSkillsSelection() {
+  const selectedPaths = [...elements.skillsPicker.querySelectorAll('input[name="saved-skills"]:checked')]
+    .map((input) => input.value)
+    .sort((left, right) => left.localeCompare(right));
+
+  state.savedSkillPaths = selectedPaths;
+  state.lastSkillsSaveMessage = `${selectedPaths.length} skill${selectedPaths.length === 1 ? "" : "s"} saved locally.`;
+  persistSavedSkillPaths(selectedPaths);
+  updateSkillsSaveStatus();
+  renderUseSkillsButton();
+  renderSkillsTable();
+}
+
+function renderCard() {
+  const { agent } = state.payload;
+  elements.agentCard.innerHTML = agent.cardHtml;
+  decorateCodeBlocks(elements.agentCard);
+  setExternalLinkBehavior(elements.agentCard);
+}
+
+function renderApp() {
+  ensureSelections();
+  renderHeader();
+  renderCard();
+  renderModelMeta();
+  renderUseSkillsButton();
+  renderSkillsTable();
+
+  elements.useAgentButton.disabled = false;
+  elements.useAgentButton.textContent = "Use this agent";
+}
+
+function renderError(message) {
+  elements.agentTitle.textContent = "Demo failed to load";
+  elements.agentSummary.textContent = message;
+  elements.useAgentButton.disabled = true;
+}
+
+async function loadAgentCard() {
+  const response = await fetch("/api/agent-card");
+  if (!response.ok) {
+    const payload = await response.json().catch(() => ({ error: "Unknown server error" }));
+    throw new Error(payload.error ?? "Unknown server error");
+  }
+
+  state.payload = await response.json();
+}
+
+async function main() {
+  try {
+    await loadAgentCard();
+    renderApp();
+  } catch (error) {
+    renderError(error.message);
+  }
+}
+
+elements.useAgentButton.addEventListener("click", () => {
+  if (!state.payload) {
+    return;
+  }
+  openModal();
+  renderModal();
+});
+
+elements.useSkillsButton.addEventListener("click", () => {
+  if (!state.payload) {
+    return;
+  }
+  openUseSkillsModal();
+});
+
+elements.closeModalButton.addEventListener("click", closeModal);
+elements.closeSkillModalButton.addEventListener("click", closeSkillModal);
+elements.closeUseSkillsModalButton.addEventListener("click", closeUseSkillsModal);
+elements.saveSkillsButton.addEventListener("click", saveSkillsSelection);
+
+elements.runtimeModal.addEventListener("click", (event) => {
+  if (event.target === elements.runtimeModal) {
+    closeModal();
+  }
+});
+
+elements.skillModal.addEventListener("click", (event) => {
+  if (event.target === elements.skillModal) {
+    closeSkillModal();
+  }
+});
+
+elements.useSkillsModal.addEventListener("click", (event) => {
+  if (event.target === elements.useSkillsModal) {
+    closeUseSkillsModal();
+  }
+});
+
+document.addEventListener("keydown", (event) => {
+  if (event.key !== "Escape") {
+    return;
+  }
+
+  if (!elements.skillModal.classList.contains("is-hidden")) {
+    closeSkillModal();
+    return;
+  }
+
+  if (!elements.useSkillsModal.classList.contains("is-hidden")) {
+    closeUseSkillsModal();
+    return;
+  }
+
+  if (!elements.runtimeModal.classList.contains("is-hidden")) {
+    closeModal();
+  }
+});
+
+main();

public/index.html

@@ -0,0 +1,202 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hugging Face</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <header class="site-nav">
+      <div class="site-nav-inner">
+        <div class="site-brand">
+          <img
+            class="site-brand-logo"
+            src="https://huggingface.co/front/assets/huggingface_logo-noborder.svg"
+            alt=""
+          />
+          <span>Hugging Face</span>
+        </div>
+
+        <label class="site-search" aria-label="Search">
+          <span class="site-search-icon">⌕</span>
+          <input type="text" value="" placeholder="Search models, datasets, users..." readonly />
+        </label>
+
+        <nav class="site-links" aria-label="Primary">
+          <a href="#">Models</a>
+          <a href="#">Datasets</a>
+          <a href="#">Spaces</a>
+          <a href="#">Docs</a>
+        </nav>
+      </div>
+    </header>
+
+    <main class="page-shell">
+      <section class="repo-header">
+        <div class="repo-heading-row">
+          <div class="repo-heading-copy">
+            <p class="repo-breadcrumb">
+              <span>demo</span>
+              <span>/</span>
+              <span id="agent-title-inline">claw</span>
+            </p>
+            <h1 id="agent-title">Loading agent card...</h1>
+            <p class="repo-summary" id="agent-summary">
+              Loading the agent card, runtime metadata, and workspace skills.
+            </p>
+          </div>
+
+          <div class="repo-actions">
+            <button class="primary-button" id="use-agent-button" type="button" disabled>Use this agent</button>
+          </div>
+        </div>
+
+        <div class="repo-tabs">
+          <span class="repo-tab is-active">Agent card</span>
+          <span class="repo-tab" id="card-path-label"></span>
+        </div>
+      </section>
+
+      <section class="page-grid">
+        <section class="content-column">
+          <article class="content-card">
+            <div class="content-card-header">
+              <div>
+                <p class="content-kicker">Rendered from workspace</p>
+                <h2 id="card-title">AGENTS.md</h2>
+              </div>
+              <span class="subtle-path" id="card-path-pill"></span>
+            </div>
+
+            <div class="markdown-body" id="agent-card"></div>
+          </article>
+        </section>
+
+        <aside class="sidebar-column">
+          <section class="sidebar-card">
+            <p class="sidebar-kicker">Reference model</p>
+            <h2 id="model-name"></h2>
+            <div class="meta-list" id="model-meta"></div>
+          </section>
+
+          <section class="sidebar-card" id="skills">
+            <div class="sidebar-card-header">
+              <div>
+                <p class="sidebar-kicker">Skills</p>
+                <h2>skills</h2>
+              </div>
+              <button class="secondary-button" id="use-skills-button" type="button">Use skills</button>
+            </div>
+
+            <div class="skills-table-wrap">
+              <table class="skills-table">
+                <thead>
+                  <tr>
+                    <th scope="col">Title</th>
+                    <th scope="col">Path</th>
+                  </tr>
+                </thead>
+                <tbody id="skills-table-body"></tbody>
+              </table>
+            </div>
+          </section>
+        </aside>
+      </section>
+    </main>
+
+    <div class="modal-overlay is-hidden" id="runtime-modal" aria-hidden="true">
+      <div class="modal-shell" role="dialog" aria-modal="true" aria-labelledby="modal-title">
+        <header class="modal-header">
+          <div>
+            <p class="modal-kicker">Local usage</p>
+            <h2 id="modal-title">Use this agent</h2>
+          </div>
+          <button class="icon-button" id="close-modal-button" type="button" aria-label="Close">x</button>
+        </header>
+
+        <div class="selection-toolbar">
+          <section class="selection-group">
+            <p class="selection-label">Inference engine</p>
+            <div class="selection-pills" id="runtime-tabs"></div>
+          </section>
+
+          <section class="selection-group">
+            <p class="selection-label">Agent</p>
+            <div class="selection-pills" id="agent-tabs"></div>
+          </section>
+        </div>
+
+        <div class="modal-meta" id="runtime-meta"></div>
+        <section class="runtime-example-group" id="runtime-example-group">
+          <p class="selection-label">Install and run</p>
+          <div class="selection-pills" id="runtime-example-tabs"></div>
+        </section>
+        <div class="runtime-panel" id="runtime-panel"></div>
+      </div>
+    </div>
+
+    <div class="modal-overlay is-hidden" id="skill-modal" aria-hidden="true">
+      <div class="modal-shell modal-shell-skill" role="dialog" aria-modal="true" aria-labelledby="skill-modal-title">
+        <header class="modal-header">
+          <div>
+            <p class="modal-kicker">Skill card</p>
+            <h2 id="skill-modal-title">Skill</h2>
+          </div>
+          <button class="icon-button" id="close-skill-modal-button" type="button" aria-label="Close">x</button>
+        </header>
+
+        <p class="modal-summary" id="skill-summary"></p>
+        <div class="skill-meta-grid" id="skill-meta"></div>
+
+        <section class="skill-file-section">
+          <div class="content-card-header">
+            <div>
+              <p class="content-kicker">Workspace file</p>
+              <h3>SKILL.md</h3>
+            </div>
+            <span class="subtle-path" id="skill-path-pill"></span>
+          </div>
+
+          <div class="markdown-body skill-markdown" id="skill-card-body"></div>
+        </section>
+      </div>
+    </div>
+
+    <div class="modal-overlay is-hidden" id="use-skills-modal" aria-hidden="true">
+      <div class="modal-shell modal-shell-skills" role="dialog" aria-modal="true" aria-labelledby="use-skills-title">
+        <header class="modal-header">
+          <div>
+            <p class="modal-kicker">Local skills</p>
+            <h2 id="use-skills-title">Use skills</h2>
+          </div>
+          <button class="icon-button" id="close-use-skills-modal-button" type="button" aria-label="Close">x</button>
+        </header>
+
+        <p class="modal-summary">Select the skills you want to save locally for this demo.</p>
+        <div class="skills-picker" id="skills-picker"></div>
+
+        <div class="modal-actions">
+          <p class="modal-status" id="skills-save-status"></p>
+          <button class="primary-button" id="save-skills-button" type="button">Save locally</button>
+        </div>
+      </div>
+    </div>
+
+    <template id="code-card-template">
+      <section class="snippet-card">
+        <div class="snippet-card-header">
+          <div>
+            <p class="snippet-kicker"></p>
+            <h3 class="snippet-title"></h3>
+          </div>
+          <button class="copy-button" type="button">Copy</button>
+        </div>
+        <p class="snippet-target"></p>
+        <pre><code></code></pre>
+      </section>
+    </template>
+
+    <script type="module" src="/app.js"></script>
+  </body>
+</html>

public/styles.css

@@ -0,0 +1,825 @@
+:root {
+  --bg: #ffffff;
+  --surface: #ffffff;
+  --surface-muted: #f9fafb;
+  --surface-soft: #f3f4f6;
+  --border: #e5e7eb;
+  --border-strong: #d1d5db;
+  --text: #111827;
+  --muted: #6b7280;
+  --muted-strong: #4b5563;
+  --accent: #111827;
+  --accent-soft: #f3f4f6;
+  --shadow: 0 18px 48px rgba(15, 23, 42, 0.08);
+  --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  --sans:
+    ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  min-height: 100%;
+}
+
+body {
+  background: var(--bg);
+  color: var(--text);
+  font-family: var(--sans);
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+input,
+textarea,
+select {
+  font: inherit;
+}
+
+code,
+pre {
+  font-family: var(--mono);
+}
+
+.site-nav {
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  background: rgba(255, 255, 255, 0.94);
+  border-bottom: 1px solid var(--border);
+  backdrop-filter: blur(14px);
+}
+
+.site-nav-inner {
+  width: min(1440px, calc(100vw - 32px));
+  margin: 0 auto;
+  min-height: 72px;
+  display: grid;
+  gap: 18px;
+  grid-template-columns: auto minmax(280px, 1fr) auto;
+  align-items: center;
+}
+
+.site-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 1.05rem;
+  font-weight: 700;
+}
+
+.site-brand-logo {
+  width: 28px;
+  height: 28px;
+  display: block;
+}
+
+.site-search {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  height: 44px;
+  padding: 0 14px;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  background: var(--surface-muted);
+  color: var(--muted);
+}
+
+.site-search input {
+  width: 100%;
+  border: 0;
+  background: transparent;
+  color: var(--muted);
+  outline: 0;
+}
+
+.site-links {
+  display: flex;
+  align-items: center;
+  gap: 22px;
+  color: var(--muted-strong);
+  font-size: 0.96rem;
+}
+
+.page-shell {
+  width: min(1440px, calc(100vw - 32px));
+  margin: 0 auto;
+  padding: 24px 0 56px;
+}
+
+.repo-header {
+  padding-top: 10px;
+}
+
+.repo-heading-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 24px;
+  align-items: flex-start;
+}
+
+.repo-breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0 0 10px;
+  color: #94a3b8;
+  font-size: 1.05rem;
+  font-weight: 600;
+}
+
+.repo-heading-copy h1 {
+  margin: 0;
+  font-size: clamp(2rem, 3vw, 2.7rem);
+  line-height: 1.02;
+  letter-spacing: -0.03em;
+}
+
+.repo-summary {
+  max-width: 72ch;
+  margin: 14px 0 0;
+  color: var(--muted-strong);
+  line-height: 1.65;
+}
+
+.repo-actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.primary-button,
+.secondary-button,
+.copy-button,
+.selection-pill,
+.icon-button {
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition:
+    background 120ms ease,
+    border-color 120ms ease,
+    color 120ms ease,
+    transform 120ms ease;
+}
+
+.primary-button {
+  height: 40px;
+  padding: 0 16px;
+  border-radius: 12px;
+  background: linear-gradient(180deg, #1f2937 0%, #111827 100%);
+  color: #ffffff;
+  font-weight: 600;
+  box-shadow: 0 8px 20px rgba(17, 24, 39, 0.18);
+}
+
+.secondary-button {
+  min-height: 36px;
+  padding: 0 14px;
+  border-radius: 10px;
+  border-color: var(--border);
+  background: var(--surface-muted);
+  color: var(--text);
+  font-weight: 600;
+}
+
+.primary-button:disabled {
+  cursor: wait;
+  opacity: 0.5;
+  box-shadow: none;
+}
+
+.primary-button:not(:disabled):hover,
+.secondary-button:hover,
+.copy-button:hover,
+.selection-pill:hover,
+.icon-button:hover {
+  transform: translateY(-1px);
+}
+
+.modal-meta {
+  display: grid;
+  gap: 10px;
+}
+
+.repo-tabs {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+  margin-top: 22px;
+  border-bottom: 1px solid var(--border);
+}
+
+.repo-tab {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-height: 48px;
+  color: var(--muted);
+  font-weight: 600;
+}
+
+.repo-tab.is-active {
+  color: var(--text);
+}
+
+.repo-tab.is-active::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: -1px;
+  height: 2px;
+  background: var(--text);
+}
+
+.page-grid {
+  display: grid;
+  gap: 32px;
+  grid-template-columns: minmax(0, 1.55fr) minmax(300px, 0.85fr);
+  align-items: start;
+  margin-top: 0;
+}
+
+.content-column {
+  min-width: 0;
+}
+
+.content-card,
+.sidebar-card,
+.snippet-card,
+.note-card,
+.modal-shell {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow);
+}
+
+.content-card {
+  border-top: 0;
+  border-radius: 0 0 18px 18px;
+  padding: 24px 28px 30px;
+}
+
+.content-card-header,
+.sidebar-card-header,
+.modal-header,
+.snippet-card-header {
+  display: flex;
+  justify-content: space-between;
+  gap: 18px;
+  align-items: flex-start;
+}
+
+.content-kicker,
+.sidebar-kicker,
+.modal-kicker,
+.snippet-kicker,
+.selection-label {
+  margin: 0 0 6px;
+  color: var(--muted);
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.content-card-header h2,
+.sidebar-card h2,
+.modal-header h2,
+.snippet-title {
+  margin: 0;
+  font-size: 1.15rem;
+  line-height: 1.15;
+}
+
+.subtle-path {
+  display: inline-flex;
+  align-items: center;
+  min-height: 32px;
+  padding: 0 12px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--surface-muted);
+  color: var(--muted);
+  font-size: 0.82rem;
+}
+
+.sidebar-column {
+  display: grid;
+  gap: 18px;
+  position: sticky;
+  top: 92px;
+}
+
+.sidebar-card {
+  border-radius: 18px;
+  padding: 18px;
+}
+
+.meta-list {
+  display: grid;
+  gap: 10px;
+  margin-top: 16px;
+}
+
+.meta-row {
+  display: grid;
+  grid-template-columns: 96px 1fr;
+  gap: 12px;
+  font-size: 0.93rem;
+}
+
+.meta-row dt {
+  color: var(--muted);
+  font-weight: 600;
+}
+
+.meta-row dd {
+  margin: 0;
+  color: var(--text);
+}
+
+.meta-row code {
+  font-size: 0.9em;
+}
+
+.skills-table-wrap {
+  max-height: 640px;
+  margin-top: 14px;
+  overflow: auto;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+}
+
+.skills-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.skills-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  padding: 10px 14px;
+  background: var(--surface-muted);
+  border-bottom: 1px solid var(--border);
+  color: var(--muted);
+  font-size: 0.76rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-align: left;
+  text-transform: uppercase;
+}
+
+.skills-table tbody td {
+  padding: 11px 14px;
+  border-bottom: 1px solid var(--border);
+  font-size: 0.94rem;
+}
+
+.skills-table tbody td code {
+  padding: 0;
+  background: transparent;
+  color: var(--muted-strong);
+  font-size: 0.86rem;
+}
+
+.skills-table tbody tr {
+  cursor: pointer;
+  outline: none;
+  transition: background 120ms ease;
+}
+
+.skills-table tbody tr:hover,
+.skills-table tbody tr:focus-visible {
+  background: var(--surface-muted);
+}
+
+.skills-table tbody tr.is-saved {
+  background: #fff8eb;
+}
+
+.skills-table tbody tr:last-child td {
+  border-bottom: 0;
+}
+
+.markdown-body {
+  margin-top: 22px;
+  color: var(--text);
+  font-size: 0.98rem;
+  line-height: 1.74;
+}
+
+.markdown-body > :first-child {
+  margin-top: 0;
+}
+
+.markdown-body > :last-child {
+  margin-bottom: 0;
+}
+
+.markdown-body h1,
+.markdown-body h2,
+.markdown-body h3 {
+  margin: 1.7em 0 0.7em;
+  font-size: 1.35rem;
+  line-height: 1.18;
+}
+
+.markdown-body h1 {
+  font-size: 1.6rem;
+}
+
+.markdown-body p,
+.markdown-body ul,
+.markdown-body ol,
+.markdown-body blockquote {
+  margin: 0 0 1.05em;
+}
+
+.markdown-body ul,
+.markdown-body ol {
+  padding-left: 1.4em;
+}
+
+.markdown-body code {
+  padding: 0.12em 0.35em;
+  border-radius: 6px;
+  background: var(--surface-soft);
+  font-size: 0.92em;
+}
+
+.markdown-body pre,
+.snippet-card pre {
+  position: relative;
+  margin: 0;
+  padding: 18px;
+  overflow: auto;
+  border-radius: 14px;
+  background: #0f172a;
+  color: #e5edf8;
+  font-size: 0.88rem;
+  line-height: 1.65;
+}
+
+.markdown-body pre {
+  margin: 0 0 1.2em;
+}
+
+.markdown-body pre code,
+.snippet-card pre code {
+  padding: 0;
+  background: transparent;
+  color: inherit;
+}
+
+.markdown-body blockquote {
+  padding-left: 16px;
+  border-left: 3px solid var(--border-strong);
+  color: var(--muted-strong);
+}
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 30;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+  background: rgba(15, 23, 42, 0.38);
+  backdrop-filter: blur(10px);
+}
+
+.modal-overlay.is-hidden {
+  display: none;
+}
+
+.modal-shell {
+  width: min(1120px, 100%);
+  max-height: calc(100vh - 48px);
+  overflow: auto;
+  border-radius: 20px;
+  padding: 22px;
+}
+
+.icon-button {
+  width: 38px;
+  height: 38px;
+  border-radius: 12px;
+  background: var(--surface-muted);
+  color: var(--text);
+}
+
+.selection-toolbar {
+  display: grid;
+  gap: 18px;
+  margin-top: 18px;
+  padding: 16px 0 18px;
+  border-top: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+}
+
+.selection-group {
+  display: grid;
+  gap: 10px;
+}
+
+.selection-pills {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.runtime-example-group {
+  display: grid;
+  gap: 10px;
+  margin-top: 18px;
+}
+
+.runtime-example-group[hidden] {
+  display: none;
+}
+
+.selection-pill {
+  min-height: 34px;
+  padding: 0 12px;
+  border-radius: 999px;
+  border-color: var(--border);
+  background: var(--surface);
+  color: var(--muted-strong);
+  font-size: 0.92rem;
+}
+
+.selection-pill.is-active {
+  border-color: #111827;
+  background: #111827;
+  color: #ffffff;
+}
+
+.selection-pill.is-disabled,
+.selection-pill:disabled {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+
+.modal-meta {
+  margin-top: 16px;
+}
+
+.inline-link {
+  display: inline-flex;
+  align-items: center;
+  color: var(--muted-strong);
+  font-weight: 600;
+}
+
+.inline-link:hover {
+  color: var(--text);
+}
+
+.modal-summary {
+  margin: 0;
+  color: var(--muted-strong);
+  line-height: 1.6;
+}
+
+.modal-meta .inline-link {
+  width: fit-content;
+  margin-top: -2px;
+}
+
+.skill-meta-grid {
+  display: grid;
+  gap: 10px;
+  margin-top: 18px;
+  padding: 18px 0;
+  border-top: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+}
+
+.skill-file-section {
+  margin-top: 18px;
+}
+
+.skills-picker {
+  display: grid;
+  gap: 12px;
+  margin-top: 18px;
+}
+
+.skill-picker-row {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: 12px;
+  align-items: flex-start;
+  padding: 14px;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  background: var(--surface-muted);
+}
+
+.skill-picker-row input {
+  margin-top: 2px;
+}
+
+.skill-picker-copy {
+  display: grid;
+  gap: 6px;
+  min-width: 0;
+}
+
+.skill-picker-copy strong {
+  font-size: 0.96rem;
+}
+
+.skill-picker-description,
+.modal-status {
+  margin: 0;
+  color: var(--muted-strong);
+  line-height: 1.55;
+}
+
+.skill-picker-path {
+  display: inline-block;
+  width: fit-content;
+  padding: 0;
+  background: transparent;
+  color: var(--muted);
+  font-size: 0.86rem;
+}
+
+.skill-markdown {
+  margin-top: 18px;
+}
+
+.modal-shell-skill .content-card-header h3 {
+  margin: 0;
+  font-size: 1.05rem;
+  line-height: 1.2;
+}
+
+.modal-shell-skill .subtle-path {
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.modal-shell-skill .meta-row {
+  grid-template-columns: 110px 1fr;
+}
+
+.modal-link {
+  display: inline-flex;
+  align-items: center;
+  min-height: 32px;
+  padding: 0 12px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--muted-strong);
+}
+
+.runtime-panel {
+  display: grid;
+  gap: 14px;
+  margin-top: 18px;
+}
+
+.modal-actions {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 16px;
+  margin-top: 18px;
+}
+
+.snippet-card,
+.note-card {
+  border-radius: 16px;
+  padding: 16px;
+}
+
+.snippet-target {
+  margin: 8px 0 12px;
+  color: var(--muted);
+  font-size: 0.9rem;
+  line-height: 1.5;
+}
+
+.copy-button {
+  min-height: 34px;
+  padding: 0 12px;
+  border-radius: 10px;
+  border-color: var(--border);
+  background: var(--surface-muted);
+  color: var(--text);
+  font-weight: 600;
+}
+
+.copy-button.is-copied {
+  background: #111827;
+  border-color: #111827;
+  color: #ffffff;
+}
+
+.pre-copy-button {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+}
+
+.warning-list {
+  margin: 0;
+  padding-left: 1.2em;
+  color: var(--muted-strong);
+  line-height: 1.6;
+}
+
+.empty-state,
+.modal-footnote {
+  margin: 0;
+  padding: 14px 16px;
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  background: var(--surface-muted);
+  color: var(--muted-strong);
+  line-height: 1.6;
+}
+
+.modal-footnote {
+  font-size: 0.92rem;
+}
+
+@media (max-width: 1100px) {
+  .page-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .sidebar-column {
+    position: static;
+  }
+}
+
+@media (max-width: 920px) {
+  .site-nav-inner {
+    grid-template-columns: 1fr;
+    padding: 14px 0;
+  }
+
+  .site-links {
+    flex-wrap: wrap;
+    gap: 14px;
+  }
+
+  .repo-heading-row {
+    flex-direction: column;
+  }
+
+  .repo-actions {
+    width: 100%;
+  }
+}
+
+@media (max-width: 720px) {
+  .page-shell,
+  .site-nav-inner {
+    width: min(100vw - 20px, 1440px);
+  }
+
+  .content-card,
+  .sidebar-card,
+  .modal-shell {
+    padding: 16px;
+  }
+
+  .content-card {
+    padding-top: 18px;
+  }
+
+  .repo-tabs,
+  .content-card-header,
+  .sidebar-card-header,
+  .modal-header,
+  .snippet-card-header,
+  .modal-actions {
+    flex-direction: column;
+  }
+
+  .meta-row {
+    grid-template-columns: 1fr;
+    gap: 4px;
+  }
+
+  .modal-overlay {
+    padding: 12px;
+  }
+}

skills/1password/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: 1password
+description: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
+homepage: https://developer.1password.com/docs/cli/get-started/
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔐",
+        "requires": { "bins": ["op"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "1password-cli",
+              "bins": ["op"],
+              "label": "Install 1Password CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# 1Password CLI
+
+Follow the official CLI get-started steps. Don't guess install commands.
+
+## References
+
+- `references/get-started.md` (install + app integration + sign-in flow)
+- `references/cli-examples.md` (real `op` examples)
+
+## Workflow
+
+1. Check OS + shell.
+2. Verify CLI present: `op --version`.
+3. Confirm desktop app integration is enabled (per get-started) and the app is unlocked.
+4. REQUIRED: create a fresh tmux session for all `op` commands (no direct `op` calls outside tmux).
+5. Sign in / authorize inside tmux: `op signin` (expect app prompt).
+6. Verify access inside tmux: `op whoami` (must succeed before any secret read).
+7. If multiple accounts: use `--account` or `OP_ACCOUNT`.
+
+## REQUIRED tmux session (T-Max)
+
+The shell tool uses a fresh TTY per command. To avoid re-prompts and failures, always run `op` inside a dedicated tmux session with a fresh socket/session name.
+
+Example (see `tmux` skill for socket conventions, do not reuse old session names):
+
+```bash
+SOCKET_DIR="${OPENCLAW_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/openclaw-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/openclaw-op.sock"
+SESSION="op-auth-$(date +%Y%m%d-%H%M%S)"
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin --account my.1password.com" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op whoami" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+tmux -S "$SOCKET" kill-session -t "$SESSION"
+```
+
+## Guardrails
+
+- Never paste secrets into logs, chat, or code.
+- Prefer `op run` / `op inject` over writing secrets to disk.
+- If sign-in without app integration is needed, use `op account add`.
+- If a command returns "account is not signed in", re-run `op signin` inside tmux and authorize in the app.
+- Do not run `op` outside tmux; stop and ask if tmux is unavailable.

skills/apple-notes/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: apple-notes
+description: Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks OpenClaw to add a note, list notes, search notes, or manage note folders.
+homepage: https://github.com/antoniorodr/memo
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📝",
+        "os": ["darwin"],
+        "requires": { "bins": ["memo"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "antoniorodr/memo/memo",
+              "bins": ["memo"],
+              "label": "Install memo via Homebrew",
+            },
+          ],
+      },
+  }
+---
+
+# Apple Notes CLI
+
+Use `memo notes` to manage Apple Notes directly from the terminal. Create, view, edit, delete, search, move notes between folders, and export to HTML/Markdown.
+
+Setup
+
+- Install (Homebrew): `brew tap antoniorodr/memo && brew install antoniorodr/memo/memo`
+- Manual (pip): `pip install .` (after cloning the repo)
+- macOS-only; if prompted, grant Automation access to Notes.app.
+
+View Notes
+
+- List all notes: `memo notes`
+- Filter by folder: `memo notes -f "Folder Name"`
+- Search notes (fuzzy): `memo notes -s "query"`
+
+Create Notes
+
+- Add a new note: `memo notes -a`
+  - Opens an interactive editor to compose the note.
+- Quick add with title: `memo notes -a "Note Title"`
+
+Edit Notes
+
+- Edit existing note: `memo notes -e`
+  - Interactive selection of note to edit.
+
+Delete Notes
+
+- Delete a note: `memo notes -d`
+  - Interactive selection of note to delete.
+
+Move Notes
+
+- Move note to folder: `memo notes -m`
+  - Interactive selection of note and destination folder.
+
+Export Notes
+
+- Export to HTML/Markdown: `memo notes -ex`
+  - Exports selected note; uses Mistune for markdown processing.
+
+Limitations
+
+- Cannot edit notes containing images or attachments.
+- Interactive prompts may require terminal access.
+
+Notes
+
+- macOS-only.
+- Requires Apple Notes.app to be accessible.
+- For automation, grant permissions in System Settings > Privacy & Security > Automation.

skills/apple-reminders/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: apple-reminders
+description: Manage Apple Reminders via remindctl CLI (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.
+homepage: https://github.com/steipete/remindctl
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "⏰",
+        "os": ["darwin"],
+        "requires": { "bins": ["remindctl"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/remindctl",
+              "bins": ["remindctl"],
+              "label": "Install remindctl via Homebrew",
+            },
+          ],
+      },
+  }
+---
+
+# Apple Reminders CLI (remindctl)
+
+Use `remindctl` to manage Apple Reminders directly from the terminal.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- User explicitly mentions "reminder" or "Reminders app"
+- Creating personal to-dos with due dates that sync to iOS
+- Managing Apple Reminders lists
+- User wants tasks to appear in their iPhone/iPad Reminders app
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Scheduling OpenClaw tasks or alerts → use `cron` tool with systemEvent instead
+- Calendar events or appointments → use Apple Calendar
+- Project/work task management → use Notion, GitHub Issues, or task queue
+- One-time notifications → use `cron` tool for timed alerts
+- User says "remind me" but means an OpenClaw alert → clarify first
+
+## Setup
+
+- Install: `brew install steipete/tap/remindctl`
+- macOS-only; grant Reminders permission when prompted
+- Check status: `remindctl status`
+- Request access: `remindctl authorize`
+
+## Common Commands
+
+### View Reminders
+
+```bash
+remindctl                    # Today's reminders
+remindctl today              # Today
+remindctl tomorrow           # Tomorrow
+remindctl week               # This week
+remindctl overdue            # Past due
+remindctl all                # Everything
+remindctl 2026-01-04         # Specific date
+```
+
+### Manage Lists
+
+```bash
+remindctl list               # List all lists
+remindctl list Work          # Show specific list
+remindctl list Projects --create    # Create list
+remindctl list Work --delete        # Delete list
+```
+
+### Create Reminders
+
+```bash
+remindctl add "Buy milk"
+remindctl add --title "Call mom" --list Personal --due tomorrow
+remindctl add --title "Meeting prep" --due "2026-02-15 09:00"
+```
+
+### Complete/Delete
+
+```bash
+remindctl complete 1 2 3     # Complete by ID
+remindctl delete 4A83 --force  # Delete by ID
+```
+
+### Output Formats
+
+```bash
+remindctl today --json       # JSON for scripting
+remindctl today --plain      # TSV format
+remindctl today --quiet      # Counts only
+```
+
+## Date Formats
+
+Accepted by `--due` and date filters:
+
+- `today`, `tomorrow`, `yesterday`
+- `YYYY-MM-DD`
+- `YYYY-MM-DD HH:mm`
+- ISO 8601 (`2026-01-04T12:34:56Z`)
+
+## Example: Clarifying User Intent
+
+User: "Remind me to check on the deploy in 2 hours"
+
+**Ask:** "Do you want this in Apple Reminders (syncs to your phone) or as an OpenClaw alert (I'll message you here)?"
+
+- Apple Reminders → use this skill
+- OpenClaw alert → use `cron` tool with systemEvent

skills/bear-notes/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: bear-notes
+description: Create, search, and manage Bear notes via grizzly CLI.
+homepage: https://bear.app
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🐻",
+        "os": ["darwin"],
+        "requires": { "bins": ["grizzly"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/tylerwince/grizzly/cmd/grizzly@latest",
+              "bins": ["grizzly"],
+              "label": "Install grizzly (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Bear Notes
+
+Use `grizzly` to create, read, and manage notes in Bear on macOS.
+
+Requirements
+
+- Bear app installed and running
+- For some operations (add-text, tags, open-note --selected), a Bear app token (stored in `~/.config/grizzly/token`)
+
+## Getting a Bear Token
+
+For operations that require a token (add-text, tags, open-note --selected), you need an authentication token:
+
+1. Open Bear → Help → API Token → Copy Token
+2. Save it: `echo "YOUR_TOKEN" > ~/.config/grizzly/token`
+
+## Common Commands
+
+Create a note
+
+```bash
+echo "Note content here" | grizzly create --title "My Note" --tag work
+grizzly create --title "Quick Note" --tag inbox < /dev/null
+```
+
+Open/read a note by ID
+
+```bash
+grizzly open-note --id "NOTE_ID" --enable-callback --json
+```
+
+Append text to a note
+
+```bash
+echo "Additional content" | grizzly add-text --id "NOTE_ID" --mode append --token-file ~/.config/grizzly/token
+```
+
+List all tags
+
+```bash
+grizzly tags --enable-callback --json --token-file ~/.config/grizzly/token
+```
+
+Search notes (via open-tag)
+
+```bash
+grizzly open-tag --name "work" --enable-callback --json
+```
+
+## Options
+
+Common flags:
+
+- `--dry-run` — Preview the URL without executing
+- `--print-url` — Show the x-callback-url
+- `--enable-callback` — Wait for Bear's response (needed for reading data)
+- `--json` — Output as JSON (when using callbacks)
+- `--token-file PATH` — Path to Bear API token file
+
+## Configuration
+
+Grizzly reads config from (in priority order):
+
+1. CLI flags
+2. Environment variables (`GRIZZLY_TOKEN_FILE`, `GRIZZLY_CALLBACK_URL`, `GRIZZLY_TIMEOUT`)
+3. `.grizzly.toml` in current directory
+4. `~/.config/grizzly/config.toml`
+
+Example `~/.config/grizzly/config.toml`:
+
+```toml
+token_file = "~/.config/grizzly/token"
+callback_url = "http://127.0.0.1:42123/success"
+timeout = "5s"
+```
+
+## Notes
+
+- Bear must be running for commands to work
+- Note IDs are Bear's internal identifiers (visible in note info or via callbacks)
+- Use `--enable-callback` when you need to read data back from Bear
+- Some operations require a valid token (add-text, tags, open-note --selected)

skills/blogwatcher/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: blogwatcher
+description: Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI.
+homepage: https://github.com/Hyaxia/blogwatcher
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📰",
+        "requires": { "bins": ["blogwatcher"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest",
+              "bins": ["blogwatcher"],
+              "label": "Install blogwatcher (go)",
+            },
+          ],
+      },
+  }
+---
+
+# blogwatcher
+
+Track blog and RSS/Atom feed updates with the `blogwatcher` CLI.
+
+Install
+
+- Go: `go install github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest`
+
+Quick start
+
+- `blogwatcher --help`
+
+Common commands
+
+- Add a blog: `blogwatcher add "My Blog" https://example.com`
+- List blogs: `blogwatcher blogs`
+- Scan for updates: `blogwatcher scan`
+- List articles: `blogwatcher articles`
+- Mark an article read: `blogwatcher read 1`
+- Mark all articles read: `blogwatcher read-all`
+- Remove a blog: `blogwatcher remove "My Blog"`
+
+Example output
+
+```
+$ blogwatcher blogs
+Tracked blogs (1):
+
+  xkcd
+    URL: https://xkcd.com
+```
+
+```
+$ blogwatcher scan
+Scanning 1 blog(s)...
+
+  xkcd
+    Source: RSS | Found: 4 | New: 4
+
+Found 4 new article(s) total!
+```
+
+Notes
+
+- Use `blogwatcher <command> --help` to discover flags and options.

skills/blucli/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: blucli
+description: BluOS CLI (blu) for discovery, playback, grouping, and volume.
+homepage: https://blucli.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🫐",
+        "requires": { "bins": ["blu"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/blucli/cmd/blu@latest",
+              "bins": ["blu"],
+              "label": "Install blucli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# blucli (blu)
+
+Use `blu` to control Bluesound/NAD players.
+
+Quick start
+
+- `blu devices` (pick target)
+- `blu --device <id> status`
+- `blu play|pause|stop`
+- `blu volume set 15`
+
+Target selection (in priority order)
+
+- `--device <id|name|alias>`
+- `BLU_DEVICE`
+- config default (if set)
+
+Common tasks
+
+- Grouping: `blu group status|add|remove`
+- TuneIn search/play: `blu tunein search "query"`, `blu tunein play "query"`
+
+Prefer `--json` for scripts. Confirm the target device before changing playback.

skills/bluebubbles/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: bluebubbles
+description: Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".
+metadata: { "openclaw": { "emoji": "🫧", "requires": { "config": ["channels.bluebubbles"] } } }
+---
+
+# BlueBubbles Actions
+
+## Overview
+
+BlueBubbles is OpenClaw’s recommended iMessage integration. Use the `message` tool with `channel: "bluebubbles"` to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons.
+
+## Inputs to collect
+
+- `target` (prefer `chat_guid:...`; also `+15551234567` in E.164 or `user@example.com`)
+- `message` text for send/edit/reply
+- `messageId` for react/edit/unsend/reply
+- Attachment `path` for local files, or `buffer` + `filename` for base64
+
+If the user is vague ("text my mom"), ask for the recipient handle or chat guid and the exact message content.
+
+## Actions
+
+### Send a message
+
+```json
+{
+  "action": "send",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "message": "hello from OpenClaw"
+}
+```
+
+### React (tapback)
+
+```json
+{
+  "action": "react",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "messageId": "<message-guid>",
+  "emoji": "❤️"
+}
+```
+
+### Remove a reaction
+
+```json
+{
+  "action": "react",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "messageId": "<message-guid>",
+  "emoji": "❤️",
+  "remove": true
+}
+```
+
+### Edit a previously sent message
+
+```json
+{
+  "action": "edit",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "messageId": "<message-guid>",
+  "message": "updated text"
+}
+```
+
+### Unsend a message
+
+```json
+{
+  "action": "unsend",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "messageId": "<message-guid>"
+}
+```
+
+### Reply to a specific message
+
+```json
+{
+  "action": "reply",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "replyTo": "<message-guid>",
+  "message": "replying to that"
+}
+```
+
+### Send an attachment
+
+```json
+{
+  "action": "sendAttachment",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "path": "/tmp/photo.jpg",
+  "caption": "here you go"
+}
+```
+
+### Send with an iMessage effect
+
+```json
+{
+  "action": "sendWithEffect",
+  "channel": "bluebubbles",
+  "target": "+15551234567",
+  "message": "big news",
+  "effect": "balloons"
+}
+```
+
+## Notes
+
+- Requires gateway config `channels.bluebubbles` (serverUrl/password/webhookPath).
+- Prefer `chat_guid` targets when you have them (especially for group chats).
+- BlueBubbles supports rich actions, but some are macOS-version dependent (for example, edit may be broken on macOS 26 Tahoe).
+- The gateway may expose both short and full message ids; full ids are more durable across restarts.
+- Developer reference for the underlying plugin lives in the BlueBubbles plugin package README.
+
+## Ideas to try
+
+- React with a tapback to acknowledge a request.
+- Reply in-thread when a user references a specific message.
+- Send a file attachment with a short caption.

skills/camsnap/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: camsnap
+description: Capture frames or clips from RTSP/ONVIF cameras.
+homepage: https://camsnap.ai
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📸",
+        "requires": { "bins": ["camsnap"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/camsnap",
+              "bins": ["camsnap"],
+              "label": "Install camsnap (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# camsnap
+
+Use `camsnap` to grab snapshots, clips, or motion events from configured cameras.
+
+Setup
+
+- Config file: `~/.config/camsnap/config.yaml`
+- Add camera: `camsnap add --name kitchen --host 192.168.0.10 --user user --pass pass`
+
+Common commands
+
+- Discover: `camsnap discover --info`
+- Snapshot: `camsnap snap kitchen --out shot.jpg`
+- Clip: `camsnap clip kitchen --dur 5s --out clip.mp4`
+- Motion watch: `camsnap watch kitchen --threshold 0.2 --action '...'`
+- Doctor: `camsnap doctor --probe`
+
+Notes
+
+- Requires `ffmpeg` on PATH.
+- Prefer a short test capture before longer clips.

skills/canvas/SKILL.md

@@ -0,0 +1,199 @@
+# Canvas Skill
+
+Display HTML content on connected OpenClaw nodes (Mac app, iOS, Android).
+
+## Overview
+
+The canvas tool lets you present web content on any connected node's canvas view. Great for:
+
+- Displaying games, visualizations, dashboards
+- Showing generated HTML content
+- Interactive demos
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  Canvas Host    │────▶│   Node Bridge    │────▶│  Node App   │
+│  (HTTP Server)  │     │  (TCP Server)    │     │ (Mac/iOS/   │
+│  Port 18793     │     │  Port 18790      │     │  Android)   │
+└─────────────────┘     └──────────────────┘     └─────────────┘
+```
+
+1. **Canvas Host Server**: Serves static HTML/CSS/JS files from `canvasHost.root` directory
+2. **Node Bridge**: Communicates canvas URLs to connected nodes
+3. **Node Apps**: Render the content in a WebView
+
+### Tailscale Integration
+
+The canvas host server binds based on `gateway.bind` setting:
+
+| Bind Mode  | Server Binds To     | Canvas URL Uses            |
+| ---------- | ------------------- | -------------------------- |
+| `loopback` | 127.0.0.1           | localhost (local only)     |
+| `lan`      | LAN interface       | LAN IP address             |
+| `tailnet`  | Tailscale interface | Tailscale hostname         |
+| `auto`     | Best available      | Tailscale > LAN > loopback |
+
+**Key insight:** The `canvasHostHostForBridge` is derived from `bridgeHost`. When bound to Tailscale, nodes receive URLs like:
+
+```
+http://<tailscale-hostname>:18793/__openclaw__/canvas/<file>.html
+```
+
+This is why localhost URLs don't work - the node receives the Tailscale hostname from the bridge!
+
+## Actions
+
+| Action     | Description                          |
+| ---------- | ------------------------------------ |
+| `present`  | Show canvas with optional target URL |
+| `hide`     | Hide the canvas                      |
+| `navigate` | Navigate to a new URL                |
+| `eval`     | Execute JavaScript in the canvas     |
+| `snapshot` | Capture screenshot of canvas         |
+
+## Configuration
+
+In the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`):
+
+```json
+{
+  "canvasHost": {
+    "enabled": true,
+    "port": 18793,
+    "root": "/Users/you/clawd/canvas",
+    "liveReload": true
+  },
+  "gateway": {
+    "bind": "auto"
+  }
+}
+```
+
+### Live Reload
+
+When `liveReload: true` (default), the canvas host:
+
+- Watches the root directory for changes (via chokidar)
+- Injects a WebSocket client into HTML files
+- Automatically reloads connected canvases when files change
+
+Great for development!
+
+## Workflow
+
+### 1. Create HTML content
+
+Place files in the canvas root directory (default `~/clawd/canvas/`):
+
+```bash
+cat > ~/clawd/canvas/my-game.html << 'HTML'
+<!DOCTYPE html>
+<html>
+<head><title>My Game</title></head>
+<body>
+  <h1>Hello Canvas!</h1>
+</body>
+</html>
+HTML
+```
+
+### 2. Find your canvas host URL
+
+Check how your gateway is bound:
+
+```bash
+CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
+cat "$CONFIG_PATH" | jq '.gateway.bind'
+```
+
+Then construct the URL:
+
+- **loopback**: `http://127.0.0.1:18793/__openclaw__/canvas/<file>.html`
+- **lan/tailnet/auto**: `http://<hostname>:18793/__openclaw__/canvas/<file>.html`
+
+Find your Tailscale hostname:
+
+```bash
+tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//'
+```
+
+### 3. Find connected nodes
+
+```bash
+openclaw nodes list
+```
+
+Look for Mac/iOS/Android nodes with canvas capability.
+
+### 4. Present content
+
+```
+canvas action:present node:<node-id> target:<full-url>
+```
+
+**Example:**
+
+```
+canvas action:present node:mac-63599bc4-b54d-4392-9048-b97abd58343a target:http://peters-mac-studio-1.sheep-coho.ts.net:18793/__openclaw__/canvas/snake.html
+```
+
+### 5. Navigate, snapshot, or hide
+
+```
+canvas action:navigate node:<node-id> url:<new-url>
+canvas action:snapshot node:<node-id>
+canvas action:hide node:<node-id>
+```
+
+## Debugging
+
+### White screen / content not loading
+
+**Cause:** URL mismatch between server bind and node expectation.
+
+**Debug steps:**
+
+1. Check server bind: `CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"; cat "$CONFIG_PATH" | jq '.gateway.bind'`
+2. Check what port canvas is on: `lsof -i :18793`
+3. Test URL directly: `curl http://<hostname>:18793/__openclaw__/canvas/<file>.html`
+
+**Solution:** Use the full hostname matching your bind mode, not localhost.
+
+### "node required" error
+
+Always specify `node:<node-id>` parameter.
+
+### "node not connected" error
+
+Node is offline. Use `openclaw nodes list` to find online nodes.
+
+### Content not updating
+
+If live reload isn't working:
+
+1. Check `liveReload: true` in config
+2. Ensure file is in the canvas root directory
+3. Check for watcher errors in logs
+
+## URL Path Structure
+
+The canvas host serves from `/__openclaw__/canvas/` prefix:
+
+```
+http://<host>:18793/__openclaw__/canvas/index.html  → ~/clawd/canvas/index.html
+http://<host>:18793/__openclaw__/canvas/games/snake.html → ~/clawd/canvas/games/snake.html
+```
+
+The `/__openclaw__/canvas/` prefix is defined by `CANVAS_HOST_PATH` constant.
+
+## Tips
+
+- Keep HTML self-contained (inline CSS/JS) for best results
+- Use the default index.html as a test page (has bridge diagnostics)
+- The canvas persists until you `hide` it or navigate away
+- Live reload makes development fast - just save and it updates!
+- A2UI JSON push is WIP - use HTML files for now

skills/clawhub/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: clawhub
+description: Use the ClawHub CLI to search, install, update, and publish agent skills from clawhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawhub CLI.
+metadata:
+  {
+    "openclaw":
+      {
+        "requires": { "bins": ["clawhub"] },
+        "install":
+          [
+            {
+              "id": "node",
+              "kind": "node",
+              "package": "clawhub",
+              "bins": ["clawhub"],
+              "label": "Install ClawHub CLI (npm)",
+            },
+          ],
+      },
+  }
+---
+
+# ClawHub CLI
+
+Install
+
+```bash
+npm i -g clawhub
+```
+
+Auth (publish)
+
+```bash
+clawhub login
+clawhub whoami
+```
+
+Search
+
+```bash
+clawhub search "postgres backups"
+```
+
+Install
+
+```bash
+clawhub install my-skill
+clawhub install my-skill --version 1.2.3
+```
+
+Update (hash-based match + upgrade)
+
+```bash
+clawhub update my-skill
+clawhub update my-skill --version 1.2.3
+clawhub update --all
+clawhub update my-skill --force
+clawhub update --all --no-input --force
+```
+
+List
+
+```bash
+clawhub list
+```
+
+Publish
+
+```bash
+clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.2.0 --changelog "Fixes + docs"
+```
+
+Notes
+
+- Default registry: https://clawhub.com (override with CLAWHUB_REGISTRY or --registry)
+- Default workdir: cwd (falls back to OpenClaw workspace); install dir: ./skills (override with --workdir / --dir / CLAWHUB_WORKDIR)
+- Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set

skills/coding-agent/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: coding-agent
+description: 'Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required.'
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🧩",
+        "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] },
+        "install":
+          [
+            {
+              "id": "node-claude",
+              "kind": "node",
+              "package": "@anthropic-ai/claude-code",
+              "bins": ["claude"],
+              "label": "Install Claude Code CLI (npm)",
+            },
+            {
+              "id": "node-codex",
+              "kind": "node",
+              "package": "@openai/codex",
+              "bins": ["codex"],
+              "label": "Install Codex CLI (npm)",
+            },
+          ],
+      },
+  }
+---
+
+# Coding Agent (bash-first)
+
+Use **bash** (with optional background mode) for all coding agent work. Simple and effective.
+
+## ⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no
+
+For **Codex, Pi, and OpenCode**, PTY is still required (interactive terminal apps):
+
+```bash
+# ✅ Correct for Codex/Pi/OpenCode
+bash pty:true command:"codex exec 'Your prompt'"
+```
+
+For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead.
+`--dangerously-skip-permissions` with PTY can exit after the confirmation dialog.
+`--print` mode keeps full tool access and avoids interactive confirmation:
+
+```bash
+# ✅ Correct for Claude Code (no PTY needed)
+cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'
+
+# For background execution: use background:true on the exec tool
+
+# ❌ Wrong for Claude Code
+bash pty:true command:"claude --dangerously-skip-permissions 'task'"
+```
+
+### Bash Tool Parameters
+
+| Parameter    | Type    | Description                                                                 |
+| ------------ | ------- | --------------------------------------------------------------------------- |
+| `command`    | string  | The shell command to run                                                    |
+| `pty`        | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs |
+| `workdir`    | string  | Working directory (agent sees only this folder's context)                   |
+| `background` | boolean | Run in background, returns sessionId for monitoring                         |
+| `timeout`    | number  | Timeout in seconds (kills process on expiry)                                |
+| `elevated`   | boolean | Run on host instead of sandbox (if allowed)                                 |
+
+### Process Tool Actions (for background sessions)
+
+| Action      | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| `list`      | List all running/recent sessions                     |
+| `poll`      | Check if session is still running                    |
+| `log`       | Get session output (with optional offset/limit)      |
+| `write`     | Send raw data to stdin                               |
+| `submit`    | Send data + newline (like typing and pressing Enter) |
+| `send-keys` | Send key tokens or hex bytes                         |
+| `paste`     | Paste text (with optional bracketed mode)            |
+| `kill`      | Terminate the session                                |
+
+---
+
+## Quick Start: One-Shot Tasks
+
+For quick prompts/chats, create a temp git repo and run:
+
+```bash
+# Quick chat (Codex needs a git repo!)
+SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"
+
+# Or in a real project - with PTY!
+bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"
+```
+
+**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.
+
+---
+
+## The Pattern: workdir + background + pty
+
+For longer tasks, use background mode with PTY:
+
+```bash
+# Start agent in target directory (with PTY!)
+bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
+# Returns sessionId for tracking
+
+# Monitor progress
+process action:log sessionId:XXX
+
+# Check if done
+process action:poll sessionId:XXX
+
+# Send input (if agent asks a question)
+process action:write sessionId:XXX data:"y"
+
+# Submit with Enter (like typing "yes" and pressing Enter)
+process action:submit sessionId:XXX data:"yes"
+
+# Kill if needed
+process action:kill sessionId:XXX
+```
+
+**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
+
+---
+
+## Codex CLI
+
+**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)
+
+### Flags
+
+| Flag            | Effect                                             |
+| --------------- | -------------------------------------------------- |
+| `exec "prompt"` | One-shot execution, exits when done                |
+| `--full-auto`   | Sandboxed but auto-approves in workspace           |
+| `--yolo`        | NO sandbox, NO approvals (fastest, most dangerous) |
+
+### Building/Creating
+
+```bash
+# Quick one-shot (auto-approves) - remember PTY!
+bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"
+
+# Background for longer work
+bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"
+```
+
+### Reviewing PRs
+
+**⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!**
+Clone to temp folder or use git worktree.
+
+```bash
+# Clone to temp for safe review
+REVIEW_DIR=$(mktemp -d)
+git clone https://github.com/user/repo.git $REVIEW_DIR
+cd $REVIEW_DIR && gh pr checkout 130
+bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
+# Clean up after: trash $REVIEW_DIR
+
+# Or use git worktree (keeps main intact)
+git worktree add /tmp/pr-130-review pr-130-branch
+bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"
+```
+
+### Batch PR Reviews (parallel army!)
+
+```bash
+# Fetch all PR refs first
+git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
+
+# Deploy the army - one Codex per PR (all with PTY!)
+bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
+bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"
+
+# Monitor all
+process action:list
+
+# Post results to GitHub
+gh pr comment <PR#> --body "<review content>"
+```
+
+---
+
+## Claude Code
+
+```bash
+# Foreground
+bash workdir:~/project command:"claude --permission-mode bypassPermissions --print 'Your task'"
+
+# Background
+bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'"
+```
+
+---
+
+## OpenCode
+
+```bash
+bash pty:true workdir:~/project command:"opencode run 'Your task'"
+```
+
+---
+
+## Pi Coding Agent
+
+```bash
+# Install: npm install -g @mariozechner/pi-coding-agent
+bash pty:true workdir:~/project command:"pi 'Your task'"
+
+# Non-interactive mode (PTY still recommended)
+bash pty:true command:"pi -p 'Summarize src/'"
+
+# Different provider/model
+bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"
+```
+
+**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!
+
+---
+
+## Parallel Issue Fixing with git worktrees
+
+For fixing multiple issues in parallel, use git worktrees:
+
+```bash
+# 1. Create worktrees for each issue
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# 2. Launch Codex in each (background + PTY!)
+bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
+bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'"
+
+# 3. Monitor progress
+process action:list
+process action:log sessionId:XXX
+
+# 4. Create PRs after fixes
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+
+# 5. Cleanup
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+
+---
+
+## ⚠️ Rules
+
+1. **Use the right execution mode per agent**:
+   - Codex/Pi/OpenCode: `pty:true`
+   - Claude Code: `--print --permission-mode bypassPermissions` (no PTY required)
+2. **Respect tool choice** - if user asks for Codex, use Codex.
+   - Orchestrator mode: do NOT hand-code patches yourself.
+   - If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
+3. **Be patient** - don't kill sessions because they're "slow"
+4. **Monitor with process:log** - check progress without interfering
+5. **--full-auto for building** - auto-approves changes
+6. **vanilla for reviewing** - no special flags needed
+7. **Parallel is OK** - run many Codex processes at once for batch work
+8. **NEVER start Codex inside your OpenClaw state directory** (`$OPENCLAW_STATE_DIR`, default `~/.openclaw`) - it'll read your soul docs and get weird ideas about the org chart!
+9. **NEVER checkout branches in ~/Projects/openclaw/** - that's the LIVE OpenClaw instance!
+
+---
+
+## Progress Updates (Critical)
+
+When you spawn coding agents in the background, keep the user in the loop.
+
+- Send 1 short message when you start (what's running + where).
+- Then only update again when something changes:
+  - a milestone completes (build finished, tests passed)
+  - the agent asks a question / needs input
+  - you hit an error or need user action
+  - the agent finishes (include what changed + where)
+- If you kill a session, immediately say you killed it and why.
+
+This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.
+
+---
+
+## Auto-Notify on Completion
+
+For long-running background tasks, append a wake trigger to your prompt so OpenClaw gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):
+
+```
+... your task here.
+
+When completely finished, run this command to notify me:
+openclaw system event --text "Done: [brief summary of what was built]" --mode now
+```
+
+**Example:**
+
+```bash
+bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.
+
+When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"
+```
+
+This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.
+
+---
+
+## Learnings (Jan 2026)
+
+- **PTY is essential:** Coding agents are interactive terminal apps. Without `pty:true`, output breaks or agent hangs.
+- **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work.
+- **exec is your friend:** `codex exec "prompt"` runs and exits cleanly - perfect for one-shots.
+- **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline.
+- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: _"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"_ 🦞

skills/discord/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: discord
+description: "Discord ops via the message tool (channel=discord)."
+metadata: { "openclaw": { "emoji": "🎮", "requires": { "config": ["channels.discord.token"] } } }
+allowed-tools: ["message"]
+---
+
+# Discord (Via `message`)
+
+Use the `message` tool. No provider-specific `discord` tool exposed to the agent.
+
+## Musts
+
+- Always: `channel: "discord"`.
+- Respect gating: `channels.discord.actions.*` (some default off: `roles`, `moderation`, `presence`, `channels`).
+- Prefer explicit ids: `guildId`, `channelId`, `messageId`, `userId`.
+- Multi-account: optional `accountId`.
+
+## Guidelines
+
+- Avoid Markdown tables in outbound Discord messages.
+- Mention users as `<@USER_ID>`.
+- Prefer Discord components v2 (`components`) for rich UI; use legacy `embeds` only when you must.
+
+## Targets
+
+- Send-like actions: `to: "channel:<id>"` or `to: "user:<id>"`.
+- Message-specific actions: `channelId: "<id>"` (or `to`) + `messageId: "<id>"`.
+
+## Common Actions (Examples)
+
+Send message:
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "hello",
+  "silent": true
+}
+```
+
+Send with media:
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "see attachment",
+  "media": "file:///tmp/example.png"
+}
+```
+
+- Optional `silent: true` to suppress Discord notifications.
+
+Send with components v2 (recommended for rich UI):
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "Status update",
+  "components": "[Carbon v2 components]"
+}
+```
+
+- `components` expects Carbon component instances (Container, TextDisplay, etc.) from JS/TS integrations.
+- Do not combine `components` with `embeds` (Discord rejects v2 + embeds).
+
+Legacy embeds (not recommended):
+
+```json
+{
+  "action": "send",
+  "channel": "discord",
+  "to": "channel:123",
+  "message": "Status update",
+  "embeds": [{ "title": "Legacy", "description": "Embeds are legacy." }]
+}
+```
+
+- `embeds` are ignored when components v2 are present.
+
+React:
+
+```json
+{
+  "action": "react",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456",
+  "emoji": "✅"
+}
+```
+
+Read:
+
+```json
+{
+  "action": "read",
+  "channel": "discord",
+  "to": "channel:123",
+  "limit": 20
+}
+```
+
+Edit / delete:
+
+```json
+{
+  "action": "edit",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456",
+  "message": "fixed typo"
+}
+```
+
+```json
+{
+  "action": "delete",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456"
+}
+```
+
+Poll:
+
+```json
+{
+  "action": "poll",
+  "channel": "discord",
+  "to": "channel:123",
+  "pollQuestion": "Lunch?",
+  "pollOption": ["Pizza", "Sushi", "Salad"],
+  "pollMulti": false,
+  "pollDurationHours": 24
+}
+```
+
+Pins:
+
+```json
+{
+  "action": "pin",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456"
+}
+```
+
+Threads:
+
+```json
+{
+  "action": "thread-create",
+  "channel": "discord",
+  "channelId": "123",
+  "messageId": "456",
+  "threadName": "bug triage"
+}
+```
+
+Search:
+
+```json
+{
+  "action": "search",
+  "channel": "discord",
+  "guildId": "999",
+  "query": "release notes",
+  "channelIds": ["123", "456"],
+  "limit": 10
+}
+```
+
+Presence (often gated):
+
+```json
+{
+  "action": "set-presence",
+  "channel": "discord",
+  "activityType": "playing",
+  "activityName": "with fire",
+  "status": "online"
+}
+```
+
+## Writing Style (Discord)
+
+- Short, conversational, low ceremony.
+- No markdown tables.
+- Mention users as `<@USER_ID>`.

skills/eightctl/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: eightctl
+description: Control Eight Sleep pods (status, temperature, alarms, schedules).
+homepage: https://eightctl.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🛌",
+        "requires": { "bins": ["eightctl"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/eightctl/cmd/eightctl@latest",
+              "bins": ["eightctl"],
+              "label": "Install eightctl (go)",
+            },
+          ],
+      },
+  }
+---
+
+# eightctl
+
+Use `eightctl` for Eight Sleep pod control. Requires auth.
+
+Auth
+
+- Config: `~/.config/eightctl/config.yaml`
+- Env: `EIGHTCTL_EMAIL`, `EIGHTCTL_PASSWORD`
+
+Quick start
+
+- `eightctl status`
+- `eightctl on|off`
+- `eightctl temp 20`
+
+Common tasks
+
+- Alarms: `eightctl alarm list|create|dismiss`
+- Schedules: `eightctl schedule list|create|update`
+- Audio: `eightctl audio state|play|pause`
+- Base: `eightctl base info|angle`
+
+Notes
+
+- API is unofficial and rate-limited; avoid repeated logins.
+- Confirm before changing temperature or alarms.

skills/gemini/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gemini
+description: Gemini CLI for one-shot Q&A, summaries, and generation.
+homepage: https://ai.google.dev/
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "✨",
+        "requires": { "bins": ["gemini"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gemini-cli",
+              "bins": ["gemini"],
+              "label": "Install Gemini CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Gemini CLI
+
+Use Gemini in one-shot mode with a positional prompt (avoid interactive mode).
+
+Quick start
+
+- `gemini "Answer this question..."`
+- `gemini --model <name> "Prompt..."`
+- `gemini --output-format json "Return JSON"`
+
+Extensions
+
+- List: `gemini --list-extensions`
+- Manage: `gemini extensions <command>`
+
+Notes
+
+- If auth is required, run `gemini` once interactively and follow the login flow.
+- Avoid `--yolo` for safety.

skills/gh-issues/SKILL.md

@@ -0,0 +1,885 @@
+---
+name: gh-issues
+description: "Fetch GitHub issues, spawn sub-agents to implement fixes and open PRs, then monitor and address PR review comments. Usage: /gh-issues [owner/repo] [--label bug] [--limit 5] [--milestone v1.0] [--assignee @me] [--fork user/repo] [--watch] [--interval 5] [--reviews-only] [--cron] [--dry-run] [--model glm-5] [--notify-channel -1002381931352]"
+user-invocable: true
+metadata:
+  {
+    "openclaw":
+      {
+        "requires": { "bins": ["curl", "git", "gh"] },
+        "primaryEnv": "GH_TOKEN",
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# gh-issues — Auto-fix GitHub Issues with Parallel Sub-agents
+
+You are an orchestrator. Follow these 6 phases exactly. Do not skip phases.
+
+IMPORTANT — No `gh` CLI dependency. This skill uses curl + the GitHub REST API exclusively. The GH_TOKEN env var is already injected by OpenClaw. Pass it as a Bearer token in all API calls:
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" ...
+```
+
+---
+
+## Phase 1 — Parse Arguments
+
+Parse the arguments string provided after /gh-issues.
+
+Positional:
+
+- owner/repo — optional. This is the source repo to fetch issues from. If omitted, detect from the current git remote:
+  `git remote get-url origin`
+  Extract owner/repo from the URL (handles both HTTPS and SSH formats).
+  - HTTPS: https://github.com/owner/repo.git → owner/repo
+  - SSH: git@github.com:owner/repo.git → owner/repo
+    If not in a git repo or no remote found, stop with an error asking the user to specify owner/repo.
+
+Flags (all optional):
+| Flag | Default | Description |
+|------|---------|-------------|
+| --label | _(none)_ | Filter by label (e.g. bug, `enhancement`) |
+| --limit | 10 | Max issues to fetch per poll |
+| --milestone | _(none)_ | Filter by milestone title |
+| --assignee | _(none)_ | Filter by assignee (`@me` for self) |
+| --state | open | Issue state: open, closed, all |
+| --fork | _(none)_ | Your fork (`user/repo`) to push branches and open PRs from. Issues are fetched from the source repo; code is pushed to the fork; PRs are opened from the fork to the source repo. |
+| --watch | false | Keep polling for new issues and PR reviews after each batch |
+| --interval | 5 | Minutes between polls (only with `--watch`) |
+| --dry-run | false | Fetch and display only — no sub-agents |
+| --yes | false | Skip confirmation and auto-process all filtered issues |
+| --reviews-only | false | Skip issue processing (Phases 2-5). Only run Phase 6 — check open PRs for review comments and address them. |
+| --cron | false | Cron-safe mode: fetch issues and spawn sub-agents, exit without waiting for results. |
+| --model | _(none)_ | Model to use for sub-agents (e.g. `glm-5`, `zai/glm-5`). If not specified, uses the agent's default model. |
+| --notify-channel | _(none)_ | Telegram channel ID to send final PR summary to (e.g. -1002381931352). Only the final result with PR links is sent, not status updates. |
+
+Store parsed values for use in subsequent phases.
+
+Derived values:
+
+- SOURCE_REPO = the positional owner/repo (where issues live)
+- PUSH_REPO = --fork value if provided, otherwise same as SOURCE_REPO
+- FORK_MODE = true if --fork was provided, false otherwise
+
+**If `--reviews-only` is set:** Skip directly to Phase 6. Run token resolution (from Phase 2) first, then jump to Phase 6.
+
+**If `--cron` is set:**
+
+- Force `--yes` (skip confirmation)
+- If `--reviews-only` is also set, run token resolution then jump to Phase 6 (cron review mode)
+- Otherwise, proceed normally through Phases 2-5 with cron-mode behavior active
+
+---
+
+## Phase 2 — Fetch Issues
+
+**Token Resolution:**
+First, ensure GH_TOKEN is available. Check environment:
+
+```
+echo $GH_TOKEN
+```
+
+If empty, read from config:
+
+```
+CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
+cat "$CONFIG_PATH" | jq -r '.skills.entries["gh-issues"].apiKey // empty'
+```
+
+If still empty, check `/data/.clawdbot/openclaw.json`:
+
+```
+cat /data/.clawdbot/openclaw.json | jq -r '.skills.entries["gh-issues"].apiKey // empty'
+```
+
+Export as GH_TOKEN for subsequent commands:
+
+```
+export GH_TOKEN="<token>"
+```
+
+Build and run a curl request to the GitHub Issues API via exec:
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{SOURCE_REPO}/issues?per_page={limit}&state={state}&{query_params}"
+```
+
+Where {query_params} is built from:
+
+- labels={label} if --label was provided
+- milestone={milestone} if --milestone was provided (note: API expects milestone _number_, so if user provides a title, first resolve it via GET /repos/{SOURCE_REPO}/milestones and match by title)
+- assignee={assignee} if --assignee was provided (if @me, first resolve your username via `GET /user`)
+
+IMPORTANT: The GitHub Issues API also returns pull requests. Filter them out — exclude any item where pull_request key exists in the response object.
+
+If in watch mode: Also filter out any issue numbers already in the PROCESSED_ISSUES set from previous batches.
+
+Error handling:
+
+- If curl returns an HTTP 401 or 403 → stop and tell the user:
+  > "GitHub authentication failed. Please check your apiKey in the OpenClaw dashboard or in the active OpenClaw config path (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`) under `skills.entries.gh-issues`."
+- If the response is an empty array (after filtering) → report "No issues found matching filters" and stop (or loop back if in watch mode).
+- If curl fails or returns any other error → report the error verbatim and stop.
+
+Parse the JSON response. For each issue, extract: number, title, body, labels (array of label names), assignees, html_url.
+
+---
+
+## Phase 3 — Present & Confirm
+
+Display a markdown table of fetched issues:
+
+| #   | Title                         | Labels        |
+| --- | ----------------------------- | ------------- |
+| 42  | Fix null pointer in parser    | bug, critical |
+| 37  | Add retry logic for API calls | enhancement   |
+
+If FORK_MODE is active, also display:
+
+> "Fork mode: branches will be pushed to {PUSH_REPO}, PRs will target `{SOURCE_REPO}`"
+
+If `--dry-run` is active:
+
+- Display the table and stop. Do not proceed to Phase 4.
+
+If `--yes` is active:
+
+- Display the table for visibility
+- Auto-process ALL listed issues without asking for confirmation
+- Proceed directly to Phase 4
+
+Otherwise:
+Ask the user to confirm which issues to process:
+
+- "all" — process every listed issue
+- Comma-separated numbers (e.g. `42, 37`) — process only those
+- "cancel" — abort entirely
+
+Wait for user response before proceeding.
+
+Watch mode note: On the first poll, always confirm with the user (unless --yes is set). On subsequent polls, auto-process all new issues without re-confirming (the user already opted in). Still display the table so they can see what's being processed.
+
+---
+
+## Phase 4 — Pre-flight Checks
+
+Run these checks sequentially via exec:
+
+1. **Dirty working tree check:**
+
+   ```
+   git status --porcelain
+   ```
+
+   If output is non-empty, warn the user:
+
+   > "Working tree has uncommitted changes. Sub-agents will create branches from HEAD — uncommitted changes will NOT be included. Continue?"
+   > Wait for confirmation. If declined, stop.
+
+2. **Record base branch:**
+
+   ```
+   git rev-parse --abbrev-ref HEAD
+   ```
+
+   Store as BASE_BRANCH.
+
+3. **Verify remote access:**
+   If FORK_MODE:
+   - Verify the fork remote exists. Check if a git remote named `fork` exists:
+     ```
+     git remote get-url fork
+     ```
+     If it doesn't exist, add it:
+     ```
+     git remote add fork https://x-access-token:$GH_TOKEN@github.com/{PUSH_REPO}.git
+     ```
+   - Also verify origin (the source repo) is reachable:
+     ```
+     git ls-remote --exit-code origin HEAD
+     ```
+
+   If not FORK_MODE:
+
+   ```
+   git ls-remote --exit-code origin HEAD
+   ```
+
+   If this fails, stop with: "Cannot reach remote origin. Check your network and git config."
+
+4. **Verify GH_TOKEN validity:**
+
+   ```
+   curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $GH_TOKEN" https://api.github.com/user
+   ```
+
+   If HTTP status is not 200, stop with:
+
+   > "GitHub authentication failed. Please check your apiKey in the OpenClaw dashboard or in the active OpenClaw config path (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`) under `skills.entries.gh-issues`."
+
+5. **Check for existing PRs:**
+   For each confirmed issue number N, run:
+
+   ```
+   curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+     "https://api.github.com/repos/{SOURCE_REPO}/pulls?head={PUSH_REPO_OWNER}:fix/issue-{N}&state=open&per_page=1"
+   ```
+
+   (Where PUSH_REPO_OWNER is the owner portion of `PUSH_REPO`)
+   If the response array is non-empty, remove that issue from the processing list and report:
+
+   > "Skipping #{N} — PR already exists: {html_url}"
+
+   If all issues are skipped, report and stop (or loop back if in watch mode).
+
+6. **Check for in-progress branches (no PR yet = sub-agent still working):**
+   For each remaining issue number N (not already skipped by the PR check above), check if a `fix/issue-{N}` branch exists on the **push repo** (which may be a fork, not origin):
+
+   ```
+   curl -s -o /dev/null -w "%{http_code}" \
+     -H "Authorization: Bearer $GH_TOKEN" \
+     "https://api.github.com/repos/{PUSH_REPO}/branches/fix/issue-{N}"
+   ```
+
+   If HTTP 200 → the branch exists on the push repo but no open PR was found for it in step 5. Skip that issue:
+
+   > "Skipping #{N} — branch fix/issue-{N} exists on {PUSH_REPO}, fix likely in progress"
+
+   This check uses the GitHub API instead of `git ls-remote` so it works correctly in fork mode (where branches are pushed to the fork, not origin).
+
+   If all issues are skipped after this check, report and stop (or loop back if in watch mode).
+
+7. **Check claim-based in-progress tracking:**
+   This prevents duplicate processing when a sub-agent from a previous cron run is still working but hasn't pushed a branch or opened a PR yet.
+
+   Read the claims file (create empty `{}` if missing):
+
+   ```
+   CLAIMS_FILE="/data/.clawdbot/gh-issues-claims.json"
+   if [ ! -f "$CLAIMS_FILE" ]; then
+     mkdir -p /data/.clawdbot
+     echo '{}' > "$CLAIMS_FILE"
+   fi
+   ```
+
+   Parse the claims file. For each entry, check if the claim timestamp is older than 2 hours. If so, remove it (expired — the sub-agent likely finished or failed silently). Write back the cleaned file:
+
+   ```
+   CLAIMS=$(cat "$CLAIMS_FILE")
+   CUTOFF=$(date -u -d '2 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-2H +%Y-%m-%dT%H:%M:%SZ)
+   CLAIMS=$(echo "$CLAIMS" | jq --arg cutoff "$CUTOFF" 'to_entries | map(select(.value > $cutoff)) | from_entries')
+   echo "$CLAIMS" > "$CLAIMS_FILE"
+   ```
+
+   For each remaining issue number N (not already skipped by steps 5 or 6), check if `{SOURCE_REPO}#{N}` exists as a key in the claims file.
+
+   If claimed and not expired → skip:
+
+   > "Skipping #{N} — sub-agent claimed this issue {minutes}m ago, still within timeout window"
+
+   Where `{minutes}` is calculated from the claim timestamp to now.
+
+   If all issues are skipped after this check, report and stop (or loop back if in watch mode).
+
+---
+
+## Phase 5 — Spawn Sub-agents (Parallel)
+
+**Cron mode (`--cron` is active):**
+
+- **Sequential cursor tracking:** Use a cursor file to track which issue to process next:
+
+  ```
+  CURSOR_FILE="/data/.clawdbot/gh-issues-cursor-{SOURCE_REPO_SLUG}.json"
+  # SOURCE_REPO_SLUG = owner-repo with slashes replaced by hyphens (e.g., openclaw-openclaw)
+  ```
+
+  Read the cursor file (create if missing):
+
+  ```
+  if [ ! -f "$CURSOR_FILE" ]; then
+    echo '{"last_processed": null, "in_progress": null}' > "$CURSOR_FILE"
+  fi
+  ```
+
+  - `last_processed`: issue number of the last completed issue (or null if none)
+  - `in_progress`: issue number currently being processed (or null)
+
+- **Select next issue:** Filter the fetched issues list to find the first issue where:
+  - Issue number > last_processed (if last_processed is set)
+  - AND issue is not in the claims file (not already in progress)
+  - AND no PR exists for the issue (checked in Phase 4 step 5)
+  - AND no branch exists on the push repo (checked in Phase 4 step 6)
+- If no eligible issue is found after the last_processed cursor, wrap around to the beginning (start from the oldest eligible issue).
+
+- If an eligible issue is found:
+  1. Mark it as in_progress in the cursor file
+  2. Spawn a single sub-agent for that one issue with `cleanup: "keep"` and `runTimeoutSeconds: 3600`
+  3. If `--model` was provided, include `model: "{MODEL}"` in the spawn config
+  4. If `--notify-channel` was provided, include the channel in the task so the sub-agent can notify
+  5. Do NOT await the sub-agent result — fire and forget
+  6. **Write claim:** After spawning, read the claims file, add `{SOURCE_REPO}#{N}` with the current ISO timestamp, and write it back
+  7. Immediately report: "Spawned fix agent for #{N} — will create PR when complete"
+  8. Exit the skill. Do not proceed to Results Collection or Phase 6.
+
+- If no eligible issue is found (all issues either have PRs, have branches, or are in progress), report "No eligible issues to process — all issues have PRs/branches or are in progress" and exit.
+
+**Normal mode (`--cron` is NOT active):**
+For each confirmed issue, spawn a sub-agent using sessions_spawn. Launch up to 8 concurrently (matching `subagents.maxConcurrent: 8`). If more than 8 issues, batch them — launch the next agent as each completes.
+
+**Write claims:** After spawning each sub-agent, read the claims file, add `{SOURCE_REPO}#{N}` with the current ISO timestamp, and write it back (same procedure as cron mode above). This covers interactive usage where watch mode might overlap with cron runs.
+
+### Sub-agent Task Prompt
+
+For each issue, construct the following prompt and pass it to sessions_spawn. Variables to inject into the template:
+
+- {SOURCE_REPO} — upstream repo where the issue lives
+- {PUSH_REPO} — repo to push branches to (same as SOURCE_REPO unless fork mode)
+- {FORK_MODE} — true/false
+- {PUSH_REMOTE} — `fork` if FORK_MODE, otherwise `origin`
+- {number}, {title}, {url}, {labels}, {body} — from the issue
+- {BASE_BRANCH} — from Phase 4
+- {notify_channel} — Telegram channel ID for notifications (empty if not set). Replace {notify_channel} in the template below with the value of `--notify-channel` flag (or leave as empty string if not provided).
+
+When constructing the task, replace all template variables including {notify_channel} with actual values.
+
+```
+You are a focused code-fix agent. Your task is to fix a single GitHub issue and open a PR.
+
+IMPORTANT: Do NOT use the gh CLI — it is not installed. Use curl with the GitHub REST API for all GitHub operations.
+
+First, ensure GH_TOKEN is set. Check: `echo $GH_TOKEN`. If empty, read from config:
+CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
+GH_TOKEN=$(cat "$CONFIG_PATH" 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty')
+
+Use the token in all GitHub API calls:
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" ...
+
+<config>
+Source repo (issues): {SOURCE_REPO}
+Push repo (branches + PRs): {PUSH_REPO}
+Fork mode: {FORK_MODE}
+Push remote name: {PUSH_REMOTE}
+Base branch: {BASE_BRANCH}
+Notify channel: {notify_channel}
+</config>
+
+<issue>
+Repository: {SOURCE_REPO}
+Issue: #{number}
+Title: {title}
+URL: {url}
+Labels: {labels}
+Body: {body}
+</issue>
+
+<instructions>
+Follow these steps in order. If any step fails, report the failure and stop.
+
+0. SETUP — Ensure GH_TOKEN is available:
+```
+
+export GH_TOKEN=$(node -e "const fs=require('fs'); const c=JSON.parse(fs.readFileSync('/data/.clawdbot/openclaw.json','utf8')); console.log(c.skills?.entries?.['gh-issues']?.apiKey || '')")
+
+```
+If that fails, also try:
+```
+
+export CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
+export GH_TOKEN=$(cat "$CONFIG_PATH" 2>/dev/null | node -e "const fs=require('fs');const d=JSON.parse(fs.readFileSync(0,'utf8'));console.log(d.skills?.entries?.['gh-issues']?.apiKey||'')")
+
+```
+Verify: echo "Token: ${GH_TOKEN:0:10}..."
+
+1. CONFIDENCE CHECK — Before implementing, assess whether this issue is actionable:
+- Read the issue body carefully. Is the problem clearly described?
+- Search the codebase (grep/find) for the relevant code. Can you locate it?
+- Is the scope reasonable? (single file/function = good, whole subsystem = bad)
+- Is a specific fix suggested or is it a vague complaint?
+
+Rate your confidence (1-10). If confidence < 7, STOP and report:
+> "Skipping #{number}: Low confidence (score: N/10) — [reason: vague requirements | cannot locate code | scope too large | no clear fix suggested]"
+
+Only proceed if confidence >= 7.
+
+1. UNDERSTAND — Read the issue carefully. Identify what needs to change and where.
+
+2. BRANCH — Create a feature branch from the base branch:
+git checkout -b fix/issue-{number} {BASE_BRANCH}
+
+3. ANALYZE — Search the codebase to find relevant files:
+- Use grep/find via exec to locate code related to the issue
+- Read the relevant files to understand the current behavior
+- Identify the root cause
+
+4. IMPLEMENT — Make the minimal, focused fix:
+- Follow existing code style and conventions
+- Change only what is necessary to fix the issue
+- Do not add unrelated changes or new dependencies without justification
+
+5. TEST — Discover and run the existing test suite if one exists:
+- Look for package.json scripts, Makefile targets, pytest, cargo test, etc.
+- Run the relevant tests
+- If tests fail after your fix, attempt ONE retry with a corrected approach
+- If tests still fail, report the failure
+
+6. COMMIT — Stage and commit your changes:
+git add {changed_files}
+git commit -m "fix: {short_description}
+
+Fixes {SOURCE_REPO}#{number}"
+
+7. PUSH — Push the branch:
+First, ensure the push remote uses token auth and disable credential helpers:
+git config --global credential.helper ""
+git remote set-url {PUSH_REMOTE} https://x-access-token:$GH_TOKEN@github.com/{PUSH_REPO}.git
+Then push:
+GIT_ASKPASS=true git push -u {PUSH_REMOTE} fix/issue-{number}
+
+8. PR — Create a pull request using the GitHub API:
+
+If FORK_MODE is true, the PR goes from your fork to the source repo:
+- head = "{PUSH_REPO_OWNER}:fix/issue-{number}"
+- base = "{BASE_BRANCH}"
+- PR is created on {SOURCE_REPO}
+
+If FORK_MODE is false:
+- head = "fix/issue-{number}"
+- base = "{BASE_BRANCH}"
+- PR is created on {SOURCE_REPO}
+
+curl -s -X POST \
+  -H "Authorization: Bearer $GH_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  https://api.github.com/repos/{SOURCE_REPO}/pulls \
+  -d '{
+    "title": "fix: {title}",
+    "head": "{head_value}",
+    "base": "{BASE_BRANCH}",
+    "body": "## Summary\n\n{one_paragraph_description_of_fix}\n\n## Changes\n\n{bullet_list_of_changes}\n\n## Testing\n\n{what_was_tested_and_results}\n\nFixes {SOURCE_REPO}#{number}"
+  }'
+
+Extract the `html_url` from the response — this is the PR link.
+
+9. REPORT — Send back a summary:
+- PR URL (the html_url from step 8)
+- Files changed (list)
+- Fix summary (1-2 sentences)
+- Any caveats or concerns
+
+10. NOTIFY (if notify_channel is set) — If {notify_channel} is not empty, send a notification to the Telegram channel:
+```
+
+Use the message tool with:
+
+- action: "send"
+- channel: "telegram"
+- target: "{notify_channel}"
+- message: "✅ PR Created: {SOURCE_REPO}#{number}
+
+{title}
+
+{pr_url}
+
+Files changed: {files_changed_list}"
+
+```
+</instructions>
+
+<constraints>
+- No force-push, no modifying the base branch
+- No unrelated changes or gratuitous refactoring
+- No new dependencies without strong justification
+- If the issue is unclear or too complex to fix confidently, report your analysis instead of guessing
+- Do NOT use the gh CLI — it is not available. Use curl + GitHub REST API for all GitHub operations.
+- GH_TOKEN is already in the environment — do NOT prompt for auth
+- Time limit: you have 60 minutes max. Be thorough — analyze properly, test your fix, don't rush.
+</constraints>
+```
+
+### Spawn configuration per sub-agent:
+
+- runTimeoutSeconds: 3600 (60 minutes)
+- cleanup: "keep" (preserve transcripts for review)
+- If `--model` was provided, include `model: "{MODEL}"` in the spawn config
+
+### Timeout Handling
+
+If a sub-agent exceeds 60 minutes, record it as:
+
+> "#{N} — Timed out (issue may be too complex for auto-fix)"
+
+---
+
+## Results Collection
+
+**If `--cron` is active:** Skip this section entirely — the orchestrator already exited after spawning in Phase 5.
+
+After ALL sub-agents complete (or timeout), collect their results. Store the list of successfully opened PRs in `OPEN_PRS` (PR number, branch name, issue number, PR URL) for use in Phase 6.
+
+Present a summary table:
+
+| Issue                 | Status    | PR                             | Notes                          |
+| --------------------- | --------- | ------------------------------ | ------------------------------ |
+| #42 Fix null pointer  | PR opened | https://github.com/.../pull/99 | 3 files changed                |
+| #37 Add retry logic   | Failed    | --                             | Could not identify target code |
+| #15 Update docs       | Timed out | --                             | Too complex for auto-fix       |
+| #8 Fix race condition | Skipped   | --                             | PR already exists              |
+
+**Status values:**
+
+- **PR opened** — success, link to PR
+- **Failed** — sub-agent could not complete (include reason in Notes)
+- **Timed out** — exceeded 60-minute limit
+- **Skipped** — existing PR detected in pre-flight
+
+End with a one-line summary:
+
+> "Processed {N} issues: {success} PRs opened, {failed} failed, {skipped} skipped."
+
+**Send notification to channel (if --notify-channel is set):**
+If `--notify-channel` was provided, send the final summary to that Telegram channel using the `message` tool:
+
+```
+Use the message tool with:
+- action: "send"
+- channel: "telegram"
+- target: "{notify-channel}"
+- message: "✅ GitHub Issues Processed
+
+Processed {N} issues: {success} PRs opened, {failed} failed, {skipped} skipped.
+
+{PR_LIST}"
+
+Where PR_LIST includes only successfully opened PRs in format:
+• #{issue_number}: {PR_url} ({notes})
+```
+
+Then proceed to Phase 6.
+
+---
+
+## Phase 6 — PR Review Handler
+
+This phase monitors open PRs (created by this skill or pre-existing `fix/issue-*` PRs) for review comments and spawns sub-agents to address them.
+
+**When this phase runs:**
+
+- After Results Collection (Phases 2-5 completed) — checks PRs that were just opened
+- When `--reviews-only` flag is set — skips Phases 2-5 entirely, runs only this phase
+- In watch mode — runs every poll cycle after checking for new issues
+
+**Cron review mode (`--cron --reviews-only`):**
+When both `--cron` and `--reviews-only` are set:
+
+1. Run token resolution (Phase 2 token section)
+2. Discover open `fix/issue-*` PRs (Step 6.1)
+3. Fetch review comments (Step 6.2)
+4. **Analyze comment content for actionability** (Step 6.3)
+5. If actionable comments are found, spawn ONE review-fix sub-agent for the first PR with unaddressed comments — fire-and-forget (do NOT await result)
+   - Use `cleanup: "keep"` and `runTimeoutSeconds: 3600`
+   - If `--model` was provided, include `model: "{MODEL}"` in the spawn config
+6. Report: "Spawned review handler for PR #{N} — will push fixes when complete"
+7. Exit the skill immediately. Do not proceed to Step 6.5 (Review Results).
+
+If no actionable comments found, report "No actionable review comments found" and exit.
+
+**Normal mode (non-cron) continues below:**
+
+### Step 6.1 — Discover PRs to Monitor
+
+Collect PRs to check for review comments:
+
+**If coming from Phase 5:** Use the `OPEN_PRS` list from Results Collection.
+
+**If `--reviews-only` or subsequent watch cycle:** Fetch all open PRs with `fix/issue-` branch pattern:
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{SOURCE_REPO}/pulls?state=open&per_page=100"
+```
+
+Filter to only PRs where `head.ref` starts with `fix/issue-`.
+
+For each PR, extract: `number` (PR number), `head.ref` (branch name), `html_url`, `title`, `body`.
+
+If no PRs found, report "No open fix/ PRs to monitor" and stop (or loop back if in watch mode).
+
+### Step 6.2 — Fetch All Review Sources
+
+For each PR, fetch reviews from multiple sources:
+
+**Fetch PR reviews:**
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}/reviews"
+```
+
+**Fetch PR review comments (inline/file-level):**
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}/comments"
+```
+
+**Fetch PR issue comments (general conversation):**
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{SOURCE_REPO}/issues/{pr_number}/comments"
+```
+
+**Fetch PR body for embedded reviews:**
+Some review tools (like Greptile) embed their feedback directly in the PR body. Check for:
+
+- `<!-- greptile_comment -->` markers
+- Other structured review sections in the PR body
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}"
+```
+
+Extract the `body` field and parse for embedded review content.
+
+### Step 6.3 — Analyze Comments for Actionability
+
+**Determine the bot's own username** for filtering:
+
+```
+curl -s -H "Authorization: Bearer $GH_TOKEN" https://api.github.com/user | jq -r '.login'
+```
+
+Store as `BOT_USERNAME`. Exclude any comment where `user.login` equals `BOT_USERNAME`.
+
+**For each comment/review, analyze the content to determine if it requires action:**
+
+**NOT actionable (skip):**
+
+- Pure approvals or "LGTM" without suggestions
+- Bot comments that are informational only (CI status, auto-generated summaries without specific requests)
+- Comments already addressed (check if bot replied with "Addressed in commit...")
+- Reviews with state `APPROVED` and no inline comments requesting changes
+
+**IS actionable (requires attention):**
+
+- Reviews with state `CHANGES_REQUESTED`
+- Reviews with state `COMMENTED` that contain specific requests:
+  - "this test needs to be updated"
+  - "please fix", "change this", "update", "can you", "should be", "needs to"
+  - "will fail", "will break", "causes an error"
+  - Mentions of specific code issues (bugs, missing error handling, edge cases)
+- Inline review comments pointing out issues in the code
+- Embedded reviews in PR body that identify:
+  - Critical issues or breaking changes
+  - Test failures expected
+  - Specific code that needs attention
+  - Confidence scores with concerns
+
+**Parse embedded review content (e.g., Greptile):**
+Look for sections marked with `<!-- greptile_comment -->` or similar. Extract:
+
+- Summary text
+- Any mentions of "Critical issue", "needs attention", "will fail", "test needs to be updated"
+- Confidence scores below 4/5 (indicates concerns)
+
+**Build actionable_comments list** with:
+
+- Source (review, inline comment, PR body, etc.)
+- Author
+- Body text
+- For inline: file path and line number
+- Specific action items identified
+
+If no actionable comments found across any PR, report "No actionable review comments found" and stop (or loop back if in watch mode).
+
+### Step 6.4 — Present Review Comments
+
+Display a table of PRs with pending actionable comments:
+
+```
+| PR | Branch | Actionable Comments | Sources |
+|----|--------|---------------------|---------|
+| #99 | fix/issue-42 | 2 comments | @reviewer1, greptile |
+| #101 | fix/issue-37 | 1 comment | @reviewer2 |
+```
+
+If `--yes` is NOT set and this is not a subsequent watch poll: ask the user to confirm which PRs to address ("all", comma-separated PR numbers, or "skip").
+
+### Step 6.5 — Spawn Review Fix Sub-agents (Parallel)
+
+For each PR with actionable comments, spawn a sub-agent. Launch up to 8 concurrently.
+
+**Review fix sub-agent prompt:**
+
+```
+You are a PR review handler agent. Your task is to address review comments on a pull request by making the requested changes, pushing updates, and replying to each comment.
+
+IMPORTANT: Do NOT use the gh CLI — it is not installed. Use curl with the GitHub REST API for all GitHub operations.
+
+First, ensure GH_TOKEN is set. Check: echo $GH_TOKEN. If empty, read from config:
+CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
+GH_TOKEN=$(cat "$CONFIG_PATH" 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/openclaw.json 2>/dev/null | jq -r '.skills.entries["gh-issues"].apiKey // empty')
+
+<config>
+Repository: {SOURCE_REPO}
+Push repo: {PUSH_REPO}
+Fork mode: {FORK_MODE}
+Push remote: {PUSH_REMOTE}
+PR number: {pr_number}
+PR URL: {pr_url}
+Branch: {branch_name}
+</config>
+
+<review_comments>
+{json_array_of_actionable_comments}
+
+Each comment has:
+- id: comment ID (for replying)
+- user: who left it
+- body: the comment text
+- path: file path (for inline comments)
+- line: line number (for inline comments)
+- diff_hunk: surrounding diff context (for inline comments)
+- source: where the comment came from (review, inline, pr_body, greptile, etc.)
+</review_comments>
+
+<instructions>
+Follow these steps in order:
+
+0. SETUP — Ensure GH_TOKEN is available:
+```
+
+export GH_TOKEN=$(node -e "const fs=require('fs'); const c=JSON.parse(fs.readFileSync('/data/.clawdbot/openclaw.json','utf8')); console.log(c.skills?.entries?.['gh-issues']?.apiKey || '')")
+
+```
+Verify: echo "Token: ${GH_TOKEN:0:10}..."
+
+1. CHECKOUT — Switch to the PR branch:
+git fetch {PUSH_REMOTE} {branch_name}
+git checkout {branch_name}
+git pull {PUSH_REMOTE} {branch_name}
+
+2. UNDERSTAND — Read ALL review comments carefully. Group them by file. Understand what each reviewer is asking for.
+
+3. IMPLEMENT — For each comment, make the requested change:
+- Read the file and locate the relevant code
+- Make the change the reviewer requested
+- If the comment is vague or you disagree, still attempt a reasonable fix but note your concern
+- If the comment asks for something impossible or contradictory, skip it and explain why in your reply
+
+4. TEST — Run existing tests to make sure your changes don't break anything:
+- If tests fail, fix the issue or revert the problematic change
+- Note any test failures in your replies
+
+5. COMMIT — Stage and commit all changes in a single commit:
+git add {changed_files}
+git commit -m "fix: address review comments on PR #{pr_number}
+
+Addresses review feedback from {reviewer_names}"
+
+6. PUSH — Push the updated branch:
+git config --global credential.helper ""
+git remote set-url {PUSH_REMOTE} https://x-access-token:$GH_TOKEN@github.com/{PUSH_REPO}.git
+GIT_ASKPASS=true git push {PUSH_REMOTE} {branch_name}
+
+7. REPLY — For each addressed comment, post a reply:
+
+For inline review comments (have a path/line), reply to the comment thread:
+curl -s -X POST \
+  -H "Authorization: Bearer $GH_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}/comments/{comment_id}/replies \
+  -d '{"body": "Addressed in commit {short_sha} — {brief_description_of_change}"}'
+
+For general PR comments (issue comments), reply on the PR:
+curl -s -X POST \
+  -H "Authorization: Bearer $GH_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  https://api.github.com/repos/{SOURCE_REPO}/issues/{pr_number}/comments \
+  -d '{"body": "Addressed feedback from @{reviewer}:\n\n{summary_of_changes_made}\n\nUpdated in commit {short_sha}"}'
+
+For comments you could NOT address, reply explaining why:
+"Unable to address this comment: {reason}. This may need manual review."
+
+8. REPORT — Send back a summary:
+- PR URL
+- Number of comments addressed vs skipped
+- Commit SHA
+- Files changed
+- Any comments that need manual attention
+</instructions>
+
+<constraints>
+- Only modify files relevant to the review comments
+- Do not make unrelated changes
+- Do not force-push — always regular push
+- If a comment contradicts another comment, address the most recent one and flag the conflict
+- Do NOT use the gh CLI — use curl + GitHub REST API
+- GH_TOKEN is already in the environment — do not prompt for auth
+- Time limit: 60 minutes max
+</constraints>
+```
+
+**Spawn configuration per sub-agent:**
+
+- runTimeoutSeconds: 3600 (60 minutes)
+- cleanup: "keep" (preserve transcripts for review)
+- If `--model` was provided, include `model: "{MODEL}"` in the spawn config
+
+### Step 6.6 — Review Results
+
+After all review sub-agents complete, present a summary:
+
+```
+| PR | Comments Addressed | Comments Skipped | Commit | Status |
+|----|-------------------|-----------------|--------|--------|
+| #99 fix/issue-42 | 3 | 0 | abc123f | All addressed |
+| #101 fix/issue-37 | 1 | 1 | def456a | 1 needs manual review |
+```
+
+Add comment IDs from this batch to `ADDRESSED_COMMENTS` set to prevent re-processing.
+
+---
+
+## Watch Mode (if --watch is active)
+
+After presenting results from the current batch:
+
+1. Add all issue numbers from this batch to the running set PROCESSED_ISSUES.
+2. Add all addressed comment IDs to ADDRESSED_COMMENTS.
+3. Tell the user:
+   > "Next poll in {interval} minutes... (say 'stop' to end watch mode)"
+4. Sleep for {interval} minutes.
+5. Go back to **Phase 2 — Fetch Issues**. The fetch will automatically filter out:
+   - Issues already in PROCESSED_ISSUES
+   - Issues that have existing fix/issue-{N} PRs (caught in Phase 4 pre-flight)
+6. After Phases 2-5 (or if no new issues), run **Phase 6** to check for new review comments on ALL tracked PRs (both newly created and previously opened).
+7. If no new issues AND no new actionable review comments → report "No new activity. Polling again in {interval} minutes..." and loop back to step 4.
+8. The user can say "stop" at any time to exit watch mode. When stopping, present a final cumulative summary of ALL batches — issues processed AND review comments addressed.
+
+**Context hygiene between polls — IMPORTANT:**
+Only retain between poll cycles:
+
+- PROCESSED_ISSUES (set of issue numbers)
+- ADDRESSED_COMMENTS (set of comment IDs)
+- OPEN_PRS (list of tracked PRs: number, branch, URL)
+- Cumulative results (one line per issue + one line per review batch)
+- Parsed arguments from Phase 1
+- BASE_BRANCH, SOURCE_REPO, PUSH_REPO, FORK_MODE, BOT_USERNAME
+  Do NOT retain issue bodies, comment bodies, sub-agent transcripts, or codebase analysis between polls.

skills/gifgrep/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: gifgrep
+description: Search GIF providers with CLI/TUI, download results, and extract stills/sheets.
+homepage: https://gifgrep.com
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🧲",
+        "requires": { "bins": ["gifgrep"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/gifgrep",
+              "bins": ["gifgrep"],
+              "label": "Install gifgrep (brew)",
+            },
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/gifgrep/cmd/gifgrep@latest",
+              "bins": ["gifgrep"],
+              "label": "Install gifgrep (go)",
+            },
+          ],
+      },
+  }
+---
+
+# gifgrep
+
+Use `gifgrep` to search GIF providers (Tenor/Giphy), browse in a TUI, download results, and extract stills or sheets.
+
+GIF-Grab (gifgrep workflow)
+
+- Search → preview → download → extract (still/sheet) for fast review and sharing.
+
+Quick start
+
+- `gifgrep cats --max 5`
+- `gifgrep cats --format url | head -n 5`
+- `gifgrep search --json cats | jq '.[0].url'`
+- `gifgrep tui "office handshake"`
+- `gifgrep cats --download --max 1 --format url`
+
+TUI + previews
+
+- TUI: `gifgrep tui "query"`
+- CLI still previews: `--thumbs` (Kitty/Ghostty only; still frame)
+
+Download + reveal
+
+- `--download` saves to `~/Downloads`
+- `--reveal` shows the last download in Finder
+
+Stills + sheets
+
+- `gifgrep still ./clip.gif --at 1.5s -o still.png`
+- `gifgrep sheet ./clip.gif --frames 9 --cols 3 -o sheet.png`
+- Sheets = single PNG grid of sampled frames (great for quick review, docs, PRs, chat).
+- Tune: `--frames` (count), `--cols` (grid width), `--padding` (spacing).
+
+Providers
+
+- `--source auto|tenor|giphy`
+- `GIPHY_API_KEY` required for `--source giphy`
+- `TENOR_API_KEY` optional (Tenor demo key used if unset)
+
+Output
+
+- `--json` prints an array of results (`id`, `title`, `url`, `preview_url`, `tags`, `width`, `height`)
+- `--format` for pipe-friendly fields (e.g., `url`)
+
+Environment tweaks
+
+- `GIFGREP_SOFTWARE_ANIM=1` to force software animation
+- `GIFGREP_CELL_ASPECT=0.5` to tweak preview geometry

skills/github/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: github
+description: "GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues, (3) listing/filtering PRs or issues, (4) viewing run logs. NOT for: complex web UI interactions requiring manual browser flows (use browser tooling when available), bulk operations across many repos (script with gh api), or when gh auth is not configured."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🐙",
+        "requires": { "bins": ["gh"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+            {
+              "id": "apt",
+              "kind": "apt",
+              "package": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (apt)",
+            },
+          ],
+      },
+  }
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub repositories, issues, PRs, and CI.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- Checking PR status, reviews, or merge readiness
+- Viewing CI/workflow run status and logs
+- Creating, closing, or commenting on issues
+- Creating or merging pull requests
+- Querying GitHub API for repository data
+- Listing repos, releases, or collaborators
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Local git operations (commit, push, pull, branch) → use `git` directly
+- Non-GitHub repos (GitLab, Bitbucket, self-hosted) → different CLIs
+- Cloning repositories → use `git clone`
+- Reviewing actual code changes → use `coding-agent` skill
+- Complex multi-file diffs → use `coding-agent` or read files directly
+
+## Setup
+
+```bash
+# Authenticate (one-time)
+gh auth login
+
+# Verify
+gh auth status
+```
+
+## Common Commands
+
+### Pull Requests
+
+```bash
+# List PRs
+gh pr list --repo owner/repo
+
+# Check CI status
+gh pr checks 55 --repo owner/repo
+
+# View PR details
+gh pr view 55 --repo owner/repo
+
+# Create PR
+gh pr create --title "feat: add feature" --body "Description"
+
+# Merge PR
+gh pr merge 55 --squash --repo owner/repo
+```
+
+### Issues
+
+```bash
+# List issues
+gh issue list --repo owner/repo --state open
+
+# Create issue
+gh issue create --title "Bug: something broken" --body "Details..."
+
+# Close issue
+gh issue close 42 --repo owner/repo
+```
+
+### CI/Workflow Runs
+
+```bash
+# List recent runs
+gh run list --repo owner/repo --limit 10
+
+# View specific run
+gh run view <run-id> --repo owner/repo
+
+# View failed step logs only
+gh run view <run-id> --repo owner/repo --log-failed
+
+# Re-run failed jobs
+gh run rerun <run-id> --failed --repo owner/repo
+```
+
+### API Queries
+
+```bash
+# Get PR with specific fields
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+
+# List all labels
+gh api repos/owner/repo/labels --jq '.[].name'
+
+# Get repo stats
+gh api repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output with `--jq` filtering:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+gh pr list --json number,title,state,mergeable --jq '.[] | select(.mergeable == "MERGEABLE")'
+```
+
+## Templates
+
+### PR Review Summary
+
+```bash
+# Get PR overview for review
+PR=55 REPO=owner/repo
+echo "## PR #$PR Summary"
+gh pr view $PR --repo $REPO --json title,body,author,additions,deletions,changedFiles \
+  --jq '"**\(.title)** by @\(.author.login)\n\n\(.body)\n\n📊 +\(.additions) -\(.deletions) across \(.changedFiles) files"'
+gh pr checks $PR --repo $REPO
+```
+
+### Issue Triage
+
+```bash
+# Quick issue triage view
+gh issue list --repo owner/repo --state open --json number,title,labels,createdAt \
+  --jq '.[] | "[\(.number)] \(.title) - \([.labels[].name] | join(", ")) (\(.createdAt[:10]))"'
+```
+
+## Notes
+
+- Always specify `--repo owner/repo` when not in a git directory
+- Use URLs directly: `gh pr view https://github.com/owner/repo/pull/55`
+- Rate limits apply; use `gh api --cache 1h` for repeated queries

skills/gog/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: gog
+description: Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
+homepage: https://gogcli.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🎮",
+        "requires": { "bins": ["gog"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/gogcli",
+              "bins": ["gog"],
+              "label": "Install gog (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# gog
+
+Use `gog` for Gmail/Calendar/Drive/Contacts/Sheets/Docs. Requires OAuth setup.
+
+Setup (once)
+
+- `gog auth credentials /path/to/client_secret.json`
+- `gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets`
+- `gog auth list`
+
+Common commands
+
+- Gmail search: `gog gmail search 'newer_than:7d' --max 10`
+- Gmail messages search (per email, ignores threading): `gog gmail messages search "in:inbox from:ryanair.com" --max 20 --account you@example.com`
+- Gmail send (plain): `gog gmail send --to a@b.com --subject "Hi" --body "Hello"`
+- Gmail send (multi-line): `gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt`
+- Gmail send (stdin): `gog gmail send --to a@b.com --subject "Hi" --body-file -`
+- Gmail send (HTML): `gog gmail send --to a@b.com --subject "Hi" --body-html "<p>Hello</p>"`
+- Gmail draft: `gog gmail drafts create --to a@b.com --subject "Hi" --body-file ./message.txt`
+- Gmail send draft: `gog gmail drafts send <draftId>`
+- Gmail reply: `gog gmail send --to a@b.com --subject "Re: Hi" --body "Reply" --reply-to-message-id <msgId>`
+- Calendar list events: `gog calendar events <calendarId> --from <iso> --to <iso>`
+- Calendar create event: `gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso>`
+- Calendar create with color: `gog calendar create <calendarId> --summary "Title" --from <iso> --to <iso> --event-color 7`
+- Calendar update event: `gog calendar update <calendarId> <eventId> --summary "New Title" --event-color 4`
+- Calendar show colors: `gog calendar colors`
+- Drive search: `gog drive search "query" --max 10`
+- Contacts: `gog contacts list --max 20`
+- Sheets get: `gog sheets get <sheetId> "Tab!A1:D10" --json`
+- Sheets update: `gog sheets update <sheetId> "Tab!A1:B2" --values-json '[["A","B"],["1","2"]]' --input USER_ENTERED`
+- Sheets append: `gog sheets append <sheetId> "Tab!A:C" --values-json '[["x","y","z"]]' --insert INSERT_ROWS`
+- Sheets clear: `gog sheets clear <sheetId> "Tab!A2:Z"`
+- Sheets metadata: `gog sheets metadata <sheetId> --json`
+- Docs export: `gog docs export <docId> --format txt --out /tmp/doc.txt`
+- Docs cat: `gog docs cat <docId>`
+
+Calendar Colors
+
+- Use `gog calendar colors` to see all available event colors (IDs 1-11)
+- Add colors to events with `--event-color <id>` flag
+- Event color IDs (from `gog calendar colors` output):
+  - 1: #a4bdfc
+  - 2: #7ae7bf
+  - 3: #dbadff
+  - 4: #ff887c
+  - 5: #fbd75b
+  - 6: #ffb878
+  - 7: #46d6db
+  - 8: #e1e1e1
+  - 9: #5484ed
+  - 10: #51b749
+  - 11: #dc2127
+
+Email Formatting
+
+- Prefer plain text. Use `--body-file` for multi-paragraph messages (or `--body-file -` for stdin).
+- Same `--body-file` pattern works for drafts and replies.
+- `--body` does not unescape `\n`. If you need inline newlines, use a heredoc or `$'Line 1\n\nLine 2'`.
+- Use `--body-html` only when you need rich formatting.
+- HTML tags: `<p>` for paragraphs, `<br>` for line breaks, `<strong>` for bold, `<em>` for italic, `<a href="url">` for links, `<ul>`/`<li>` for lists.
+- Example (plain text via stdin):
+
+  ```bash
+  gog gmail send --to recipient@example.com \
+    --subject "Meeting Follow-up" \
+    --body-file - <<'EOF'
+  Hi Name,
+
+  Thanks for meeting today. Next steps:
+  - Item one
+  - Item two
+
+  Best regards,
+  Your Name
+  EOF
+  ```
+
+- Example (HTML list):
+  ```bash
+  gog gmail send --to recipient@example.com \
+    --subject "Meeting Follow-up" \
+    --body-html "<p>Hi Name,</p><p>Thanks for meeting today. Here are the next steps:</p><ul><li>Item one</li><li>Item two</li></ul><p>Best regards,<br>Your Name</p>"
+  ```
+
+Notes
+
+- Set `GOG_ACCOUNT=you@gmail.com` to avoid repeating `--account`.
+- For scripting, prefer `--json` plus `--no-input`.
+- Sheets values can be passed via `--values-json` (recommended) or as inline rows.
+- Docs supports export/cat/copy. In-place edits require a Docs API client (not in gog).
+- Confirm before sending mail or creating events.
+- `gog gmail search` returns one row per thread; use `gog gmail messages search` when you need every individual email returned separately.

skills/goplaces/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: goplaces
+description: Query Google Places API (New) via the goplaces CLI for text search, place details, resolve, and reviews. Use for human-friendly place lookup or JSON output for scripts.
+homepage: https://github.com/steipete/goplaces
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📍",
+        "requires": { "bins": ["goplaces"], "env": ["GOOGLE_PLACES_API_KEY"] },
+        "primaryEnv": "GOOGLE_PLACES_API_KEY",
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/goplaces",
+              "bins": ["goplaces"],
+              "label": "Install goplaces (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# goplaces
+
+Modern Google Places API (New) CLI. Human output by default, `--json` for scripts.
+
+Install
+
+- Homebrew: `brew install steipete/tap/goplaces`
+
+Config
+
+- `GOOGLE_PLACES_API_KEY` required.
+- Optional: `GOOGLE_PLACES_BASE_URL` for testing/proxying.
+
+Common commands
+
+- Search: `goplaces search "coffee" --open-now --min-rating 4 --limit 5`
+- Bias: `goplaces search "pizza" --lat 40.8 --lng -73.9 --radius-m 3000`
+- Pagination: `goplaces search "pizza" --page-token "NEXT_PAGE_TOKEN"`
+- Resolve: `goplaces resolve "Soho, London" --limit 5`
+- Details: `goplaces details <place_id> --reviews`
+- JSON: `goplaces search "sushi" --json`
+
+Notes
+
+- `--no-color` or `NO_COLOR` disables ANSI color.
+- Price levels: 0..4 (free → very expensive).
+- Type filter sends only the first `--type` value (API accepts one).

skills/healthcheck/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: healthcheck
+description: Host security hardening and risk-tolerance configuration for OpenClaw deployments. Use when a user asks for security audits, firewall/SSH/update hardening, risk posture, exposure review, OpenClaw cron scheduling for periodic checks, or version status checks on a machine running OpenClaw (laptop, workstation, Pi, VPS).
+---
+
+# OpenClaw Host Hardening
+
+## Overview
+
+Assess and harden the host running OpenClaw, then align it to a user-defined risk tolerance without breaking access. Use OpenClaw security tooling as a first-class signal, but treat OS hardening as a separate, explicit set of steps.
+
+## Core rules
+
+- Recommend running this skill with a state-of-the-art model (e.g., Opus 4.5, GPT 5.2+). The agent should self-check the current model and suggest switching if below that level; do not block execution.
+- Require explicit approval before any state-changing action.
+- Do not modify remote access settings without confirming how the user connects.
+- Prefer reversible, staged changes with a rollback plan.
+- Never claim OpenClaw changes the host firewall, SSH, or OS updates; it does not.
+- If role/identity is unknown, provide recommendations only.
+- Formatting: every set of user choices must be numbered so the user can reply with a single digit.
+- System-level backups are recommended; try to verify status.
+
+## Workflow (follow in order)
+
+### 0) Model self-check (non-blocking)
+
+Before starting, check the current model. If it is below state-of-the-art (e.g., Opus 4.5, GPT 5.2+), recommend switching. Do not block execution.
+
+### 1) Establish context (read-only)
+
+Try to infer 1–5 from the environment before asking. Prefer simple, non-technical questions if you need confirmation.
+
+Determine (in order):
+
+1. OS and version (Linux/macOS/Windows), container vs host.
+2. Privilege level (root/admin vs user).
+3. Access path (local console, SSH, RDP, tailnet).
+4. Network exposure (public IP, reverse proxy, tunnel).
+5. OpenClaw gateway status and bind address.
+6. Backup system and status (e.g., Time Machine, system images, snapshots).
+7. Deployment context (local mac app, headless gateway host, remote gateway, container/CI).
+8. Disk encryption status (FileVault/LUKS/BitLocker).
+9. OS automatic security updates status.
+   Note: these are not blocking items, but are highly recommended, especially if OpenClaw can access sensitive data.
+10. Usage mode for a personal assistant with full access (local workstation vs headless/remote vs other).
+
+First ask once for permission to run read-only checks. If granted, run them by default and only ask questions for items you cannot infer or verify. Do not ask for information already visible in runtime or command output. Keep the permission ask as a single sentence, and list follow-up info needed as an unordered list (not numbered) unless you are presenting selectable choices.
+
+If you must ask, use non-technical prompts:
+
+- “Are you using a Mac, Windows PC, or Linux?”
+- “Are you logged in directly on the machine, or connecting from another computer?”
+- “Is this machine reachable from the public internet, or only on your home/network?”
+- “Do you have backups enabled (e.g., Time Machine), and are they current?”
+- “Is disk encryption turned on (FileVault/BitLocker/LUKS)?”
+- “Are automatic security updates enabled?”
+- “How do you use this machine?”
+  Examples:
+  - Personal machine shared with the assistant
+  - Dedicated local machine for the assistant
+  - Dedicated remote machine/server accessed remotely (always on)
+  - Something else?
+
+Only ask for the risk profile after system context is known.
+
+If the user grants read-only permission, run the OS-appropriate checks by default. If not, offer them (numbered). Examples:
+
+1. OS: `uname -a`, `sw_vers`, `cat /etc/os-release`.
+2. Listening ports:
+   - Linux: `ss -ltnup` (or `ss -ltnp` if `-u` unsupported).
+   - macOS: `lsof -nP -iTCP -sTCP:LISTEN`.
+3. Firewall status:
+   - Linux: `ufw status`, `firewall-cmd --state`, `nft list ruleset` (pick what is installed).
+   - macOS: `/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate` and `pfctl -s info`.
+4. Backups (macOS): `tmutil status` (if Time Machine is used).
+
+### 2) Run OpenClaw security audits (read-only)
+
+As part of the default read-only checks, run `openclaw security audit --deep`. Only offer alternatives if the user requests them:
+
+1. `openclaw security audit` (faster, non-probing)
+2. `openclaw security audit --json` (structured output)
+
+Offer to apply OpenClaw safe defaults (numbered):
+
+1. `openclaw security audit --fix`
+
+Be explicit that `--fix` only tightens OpenClaw defaults and file permissions. It does not change host firewall, SSH, or OS update policies.
+
+If browser control is enabled, recommend that 2FA be enabled on all important accounts, with hardware keys preferred and SMS not sufficient.
+
+### 3) Check OpenClaw version/update status (read-only)
+
+As part of the default read-only checks, run `openclaw update status`.
+
+Report the current channel and whether an update is available.
+
+### 4) Determine risk tolerance (after system context)
+
+Ask the user to pick or confirm a risk posture and any required open services/ports (numbered choices below).
+Do not pigeonhole into fixed profiles; if the user prefers, capture requirements instead of choosing a profile.
+Offer suggested profiles as optional defaults (numbered). Note that most users pick Home/Workstation Balanced:
+
+1. Home/Workstation Balanced (most common): firewall on with reasonable defaults, remote access restricted to LAN or tailnet.
+2. VPS Hardened: deny-by-default inbound firewall, minimal open ports, key-only SSH, no root login, automatic security updates.
+3. Developer Convenience: more local services allowed, explicit exposure warnings, still audited.
+4. Custom: user-defined constraints (services, exposure, update cadence, access methods).
+
+### 5) Produce a remediation plan
+
+Provide a plan that includes:
+
+- Target profile
+- Current posture summary
+- Gaps vs target
+- Step-by-step remediation with exact commands
+- Access-preservation strategy and rollback
+- Risks and potential lockout scenarios
+- Least-privilege notes (e.g., avoid admin usage, tighten ownership/permissions where safe)
+- Credential hygiene notes (location of OpenClaw creds, prefer disk encryption)
+
+Always show the plan before any changes.
+
+### 6) Offer execution options
+
+Offer one of these choices (numbered so users can reply with a single digit):
+
+1. Do it for me (guided, step-by-step approvals)
+2. Show plan only
+3. Fix only critical issues
+4. Export commands for later
+
+### 7) Execute with confirmations
+
+For each step:
+
+- Show the exact command
+- Explain impact and rollback
+- Confirm access will remain available
+- Stop on unexpected output and ask for guidance
+
+### 8) Verify and report
+
+Re-check:
+
+- Firewall status
+- Listening ports
+- Remote access still works
+- OpenClaw security audit (re-run)
+
+Deliver a final posture report and note any deferred items.
+
+## Required confirmations (always)
+
+Require explicit approval for:
+
+- Firewall rule changes
+- Opening/closing ports
+- SSH/RDP configuration changes
+- Installing/removing packages
+- Enabling/disabling services
+- User/group modifications
+- Scheduling tasks or startup persistence
+- Update policy changes
+- Access to sensitive files or credentials
+
+If unsure, ask.
+
+## Periodic checks
+
+After OpenClaw install or first hardening pass, run at least one baseline audit and version check:
+
+- `openclaw security audit`
+- `openclaw security audit --deep`
+- `openclaw update status`
+
+Ongoing monitoring is recommended. Use the OpenClaw cron tool/CLI to schedule periodic audits (Gateway scheduler). Do not create scheduled tasks without explicit approval. Store outputs in a user-approved location and avoid secrets in logs.
+When scheduling headless cron runs, include a note in the output that instructs the user to call `healthcheck` so issues can be fixed.
+
+### Required prompt to schedule (always)
+
+After any audit or hardening pass, explicitly offer scheduling and require a direct response. Use a short prompt like (numbered):
+
+1. “Do you want me to schedule periodic audits (e.g., daily/weekly) via `openclaw cron add`?”
+
+If the user says yes, ask for:
+
+- cadence (daily/weekly), preferred time window, and output location
+- whether to also schedule `openclaw update status`
+
+Use a stable cron job name so updates are deterministic. Prefer exact names:
+
+- `healthcheck:security-audit`
+- `healthcheck:update-status`
+
+Before creating, `openclaw cron list` and match on exact `name`. If found, `openclaw cron edit <id> ...`.
+If not found, `openclaw cron add --name <name> ...`.
+
+Also offer a periodic version check so the user can decide when to update (numbered):
+
+1. `openclaw update status` (preferred for source checkouts and channels)
+2. `npm view openclaw version` (published npm version)
+
+## OpenClaw command accuracy
+
+Use only supported commands and flags:
+
+- `openclaw security audit [--deep] [--fix] [--json]`
+- `openclaw status` / `openclaw status --deep`
+- `openclaw health --json`
+- `openclaw update status`
+- `openclaw cron add|list|runs|run`
+
+Do not invent CLI flags or imply OpenClaw enforces host firewall/SSH policies.
+
+## Logging and audit trail
+
+Record:
+
+- Gateway identity and role
+- Plan ID and timestamp
+- Approved steps and exact commands
+- Exit codes and files modified (best effort)
+
+Redact secrets. Never log tokens or full credential contents.
+
+## Memory writes (conditional)
+
+Only write to memory files when the user explicitly opts in and the session is a private/local workspace
+(per `docs/reference/templates/AGENTS.md`). Otherwise provide a redacted, paste-ready summary the user can
+decide to save elsewhere.
+
+Follow the durable-memory prompt format used by OpenClaw compaction:
+
+- Write lasting notes to `memory/YYYY-MM-DD.md`.
+
+After each audit/hardening run, if opted-in, append a short, dated summary to `memory/YYYY-MM-DD.md`
+(what was checked, key findings, actions taken, any scheduled cron jobs, key decisions,
+and all commands executed). Append-only: never overwrite existing entries.
+Redact sensitive host details (usernames, hostnames, IPs, serials, service names, tokens).
+If there are durable preferences or decisions (risk posture, allowed ports, update policy),
+also update `MEMORY.md` (long-term memory is optional and only used in private sessions).
+
+If the session cannot write to the workspace, ask for permission or provide exact entries
+the user can paste into the memory files.

skills/himalaya/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: himalaya
+description: "CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language)."
+homepage: https://github.com/pimalaya/himalaya
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📧",
+        "requires": { "bins": ["himalaya"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "himalaya",
+              "bins": ["himalaya"],
+              "label": "Install Himalaya (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Himalaya Email CLI
+
+Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.
+
+## References
+
+- `references/configuration.md` (config file setup + IMAP/SMTP authentication)
+- `references/message-composition.md` (MML syntax for composing emails)
+
+## Prerequisites
+
+1. Himalaya CLI installed (`himalaya --version` to verify)
+2. A configuration file at `~/.config/himalaya/config.toml`
+3. IMAP/SMTP credentials configured (password stored securely)
+
+## Configuration Setup
+
+Run the interactive wizard to set up an account:
+
+```bash
+himalaya account configure
+```
+
+Or create `~/.config/himalaya/config.toml` manually:
+
+```toml
+[accounts.personal]
+email = "you@example.com"
+display-name = "Your Name"
+default = true
+
+backend.type = "imap"
+backend.host = "imap.example.com"
+backend.port = 993
+backend.encryption.type = "tls"
+backend.login = "you@example.com"
+backend.auth.type = "password"
+backend.auth.cmd = "pass show email/imap"  # or use keyring
+
+message.send.backend.type = "smtp"
+message.send.backend.host = "smtp.example.com"
+message.send.backend.port = 587
+message.send.backend.encryption.type = "start-tls"
+message.send.backend.login = "you@example.com"
+message.send.backend.auth.type = "password"
+message.send.backend.auth.cmd = "pass show email/smtp"
+```
+
+## Common Operations
+
+### List Folders
+
+```bash
+himalaya folder list
+```
+
+### List Emails
+
+List emails in INBOX (default):
+
+```bash
+himalaya envelope list
+```
+
+List emails in a specific folder:
+
+```bash
+himalaya envelope list --folder "Sent"
+```
+
+List with pagination:
+
+```bash
+himalaya envelope list --page 1 --page-size 20
+```
+
+### Search Emails
+
+```bash
+himalaya envelope list from john@example.com subject meeting
+```
+
+### Read an Email
+
+Read email by ID (shows plain text):
+
+```bash
+himalaya message read 42
+```
+
+Export raw MIME:
+
+```bash
+himalaya message export 42 --full
+```
+
+### Reply to an Email
+
+Interactive reply (opens $EDITOR):
+
+```bash
+himalaya message reply 42
+```
+
+Reply-all:
+
+```bash
+himalaya message reply 42 --all
+```
+
+### Forward an Email
+
+```bash
+himalaya message forward 42
+```
+
+### Write a New Email
+
+Interactive compose (opens $EDITOR):
+
+```bash
+himalaya message write
+```
+
+Send directly using template:
+
+```bash
+cat << 'EOF' | himalaya template send
+From: you@example.com
+To: recipient@example.com
+Subject: Test Message
+
+Hello from Himalaya!
+EOF
+```
+
+Or with headers flag:
+
+```bash
+himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"
+```
+
+### Move/Copy Emails
+
+Move to folder:
+
+```bash
+himalaya message move 42 "Archive"
+```
+
+Copy to folder:
+
+```bash
+himalaya message copy 42 "Important"
+```
+
+### Delete an Email
+
+```bash
+himalaya message delete 42
+```
+
+### Manage Flags
+
+Add flag:
+
+```bash
+himalaya flag add 42 --flag seen
+```
+
+Remove flag:
+
+```bash
+himalaya flag remove 42 --flag seen
+```
+
+## Multiple Accounts
+
+List accounts:
+
+```bash
+himalaya account list
+```
+
+Use a specific account:
+
+```bash
+himalaya --account work envelope list
+```
+
+## Attachments
+
+Save attachments from a message:
+
+```bash
+himalaya attachment download 42
+```
+
+Save to specific directory:
+
+```bash
+himalaya attachment download 42 --dir ~/Downloads
+```
+
+## Output Formats
+
+Most commands support `--output` for structured output:
+
+```bash
+himalaya envelope list --output json
+himalaya envelope list --output plain
+```
+
+## Debugging
+
+Enable debug logging:
+
+```bash
+RUST_LOG=debug himalaya envelope list
+```
+
+Full trace with backtrace:
+
+```bash
+RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list
+```
+
+## Tips
+
+- Use `himalaya --help` or `himalaya <command> --help` for detailed usage.
+- Message IDs are relative to the current folder; re-list after folder changes.
+- For composing rich emails with attachments, use MML syntax (see `references/message-composition.md`).
+- Store passwords securely using `pass`, system keyring, or a command that outputs the password.

skills/imsg/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: imsg
+description: iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.
+homepage: https://imsg.to
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📨",
+        "os": ["darwin"],
+        "requires": { "bins": ["imsg"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/imsg",
+              "bins": ["imsg"],
+              "label": "Install imsg (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# imsg
+
+Use `imsg` to read and send iMessage/SMS via macOS Messages.app.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- User explicitly asks to send iMessage or SMS
+- Reading iMessage conversation history
+- Checking recent Messages.app chats
+- Sending to phone numbers or Apple IDs
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Telegram messages → use `message` tool with `channel:telegram`
+- Signal messages → use Signal channel if configured
+- WhatsApp messages → use WhatsApp channel if configured
+- Discord messages → use `message` tool with `channel:discord`
+- Slack messages → use `slack` skill
+- Group chat management (adding/removing members) → not supported
+- Bulk/mass messaging → always confirm with user first
+- Replying in current conversation → just reply normally (OpenClaw routes automatically)
+
+## Requirements
+
+- macOS with Messages.app signed in
+- Full Disk Access for terminal
+- Automation permission for Messages.app (for sending)
+
+## Common Commands
+
+### List Chats
+
+```bash
+imsg chats --limit 10 --json
+```
+
+### View History
+
+```bash
+# By chat ID
+imsg history --chat-id 1 --limit 20 --json
+
+# With attachments info
+imsg history --chat-id 1 --limit 20 --attachments --json
+```
+
+### Watch for New Messages
+
+```bash
+imsg watch --chat-id 1 --attachments
+```
+
+### Send Messages
+
+```bash
+# Text only
+imsg send --to "+14155551212" --text "Hello!"
+
+# With attachment
+imsg send --to "+14155551212" --text "Check this out" --file /path/to/image.jpg
+
+# Specify service
+imsg send --to "+14155551212" --text "Hi" --service imessage
+imsg send --to "+14155551212" --text "Hi" --service sms
+```
+
+## Service Options
+
+- `--service imessage` — Force iMessage (requires recipient has iMessage)
+- `--service sms` — Force SMS (green bubble)
+- `--service auto` — Let Messages.app decide (default)
+
+## Safety Rules
+
+1. **Always confirm recipient and message content** before sending
+2. **Never send to unknown numbers** without explicit user approval
+3. **Be careful with attachments** — confirm file path exists
+4. **Rate limit yourself** — don't spam
+
+## Example Workflow
+
+User: "Text mom that I'll be late"
+
+```bash
+# 1. Find mom's chat
+imsg chats --limit 20 --json | jq '.[] | select(.displayName | contains("Mom"))'
+
+# 2. Confirm with user
+# "Found Mom at +1555123456. Send 'I'll be late' via iMessage?"
+
+# 3. Send after confirmation
+imsg send --to "+1555123456" --text "I'll be late"
+```

skills/mcporter/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: mcporter
+description: Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
+homepage: http://mcporter.dev
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📦",
+        "requires": { "bins": ["mcporter"] },
+        "install":
+          [
+            {
+              "id": "node",
+              "kind": "node",
+              "package": "mcporter",
+              "bins": ["mcporter"],
+              "label": "Install mcporter (node)",
+            },
+          ],
+      },
+  }
+---
+
+# mcporter
+
+Use `mcporter` to work with MCP servers directly.
+
+Quick start
+
+- `mcporter list`
+- `mcporter list <server> --schema`
+- `mcporter call <server.tool> key=value`
+
+Call tools
+
+- Selector: `mcporter call linear.list_issues team=ENG limit:5`
+- Function syntax: `mcporter call "linear.create_issue(title: \"Bug\")"`
+- Full URL: `mcporter call https://api.example.com/mcp.fetch url:https://example.com`
+- Stdio: `mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com`
+- JSON payload: `mcporter call <server.tool> --args '{"limit":5}'`
+
+Auth + config
+
+- OAuth: `mcporter auth <server | url> [--reset]`
+- Config: `mcporter config list|get|add|remove|import|login|logout`
+
+Daemon
+
+- `mcporter daemon start|status|stop|restart`
+
+Codegen
+
+- CLI: `mcporter generate-cli --server <name>` or `--command <url>`
+- Inspect: `mcporter inspect-cli <path> [--json]`
+- TS: `mcporter emit-ts <server> --mode client|types`
+
+Notes
+
+- Config default: `./config/mcporter.json` (override with `--config`).
+- Prefer `--output json` for machine-readable results.

skills/model-usage/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: model-usage
+description: Use CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📊",
+        "os": ["darwin"],
+        "requires": { "bins": ["codexbar"] },
+        "install":
+          [
+            {
+              "id": "brew-cask",
+              "kind": "brew",
+              "formula": "steipete/tap/codexbar",
+              "bins": ["codexbar"],
+              "label": "Install CodexBar (brew cask)",
+            },
+          ],
+      },
+  }
+---
+
+# Model usage
+
+## Overview
+
+Get per-model usage cost from CodexBar's local cost logs. Supports "current model" (most recent daily entry) or "all models" summaries for Codex or Claude.
+
+TODO: add Linux CLI support guidance once CodexBar CLI install path is documented for Linux.
+
+## Quick start
+
+1. Fetch cost JSON via CodexBar CLI or pass a JSON file.
+2. Use the bundled script to summarize by model.
+
+```bash
+python {baseDir}/scripts/model_usage.py --provider codex --mode current
+python {baseDir}/scripts/model_usage.py --provider codex --mode all
+python {baseDir}/scripts/model_usage.py --provider claude --mode all --format json --pretty
+```
+
+## Current model logic
+
+- Uses the most recent daily row with `modelBreakdowns`.
+- Picks the model with the highest cost in that row.
+- Falls back to the last entry in `modelsUsed` when breakdowns are missing.
+- Override with `--model <name>` when you need a specific model.
+
+## Inputs
+
+- Default: runs `codexbar cost --format json --provider <codex|claude>`.
+- File or stdin:
+
+```bash
+codexbar cost --provider codex --format json > /tmp/cost.json
+python {baseDir}/scripts/model_usage.py --input /tmp/cost.json --mode all
+cat /tmp/cost.json | python {baseDir}/scripts/model_usage.py --input - --mode current
+```
+
+## Output
+
+- Text (default) or JSON (`--format json --pretty`).
+- Values are cost-only per model; tokens are not split by model in CodexBar output.
+
+## References
+
+- Read `references/codexbar-cli.md` for CLI flags and cost JSON fields.

skills/nano-pdf/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: nano-pdf
+description: Edit PDFs with natural-language instructions using the nano-pdf CLI.
+homepage: https://pypi.org/project/nano-pdf/
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📄",
+        "requires": { "bins": ["nano-pdf"] },
+        "install":
+          [
+            {
+              "id": "uv",
+              "kind": "uv",
+              "package": "nano-pdf",
+              "bins": ["nano-pdf"],
+              "label": "Install nano-pdf (uv)",
+            },
+          ],
+      },
+  }
+---
+
+# nano-pdf
+
+Use `nano-pdf` to apply edits to a specific page in a PDF using a natural-language instruction.
+
+## Quick start
+
+```bash
+nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"
+```
+
+Notes:
+
+- Page numbers are 0-based or 1-based depending on the tool’s version/config; if the result looks off by one, retry with the other.
+- Always sanity-check the output PDF before sending it out.

skills/node-connect/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: node-connect
+description: Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps. Use when QR/setup code/manual connect fails, local Wi-Fi works but VPS/tailnet does not, or errors mention pairing required, unauthorized, bootstrap token invalid or expired, gateway.bind, gateway.remote.url, Tailscale, or plugins.entries.device-pair.config.publicUrl.
+---
+
+# Node Connect
+
+Goal: find the one real route from node -> gateway, verify OpenClaw is advertising that route, then fix pairing/auth.
+
+## Topology first
+
+Decide which case you are in before proposing fixes:
+
+- same machine / emulator / USB tunnel
+- same LAN / local Wi-Fi
+- same Tailscale tailnet
+- public URL / reverse proxy
+
+Do not mix them.
+
+- Local Wi-Fi problem: do not switch to Tailscale unless remote access is actually needed.
+- VPS / remote gateway problem: do not keep debugging `localhost` or LAN IPs.
+
+## If ambiguous, ask first
+
+If the setup is unclear or the failure report is vague, ask short clarifying questions before diagnosing.
+
+Ask for:
+
+- which route they intend: same machine, same LAN, Tailscale tailnet, or public URL
+- whether they used QR/setup code or manual host/port
+- the exact app text/status/error, quoted exactly if possible
+- whether `openclaw devices list` shows a pending pairing request
+
+Do not guess from `can't connect`.
+
+## Canonical checks
+
+Prefer `openclaw qr --json`. It uses the same setup-code payload Android scans.
+
+```bash
+openclaw config get gateway.mode
+openclaw config get gateway.bind
+openclaw config get gateway.tailscale.mode
+openclaw config get gateway.remote.url
+openclaw config get gateway.auth.mode
+openclaw config get gateway.auth.allowTailscale
+openclaw config get plugins.entries.device-pair.config.publicUrl
+openclaw qr --json
+openclaw devices list
+openclaw nodes status
+```
+
+If this OpenClaw instance is pointed at a remote gateway, also run:
+
+```bash
+openclaw qr --remote --json
+```
+
+If Tailscale is part of the story:
+
+```bash
+tailscale status --json
+```
+
+## Read the result, not guesses
+
+`openclaw qr --json` success means:
+
+- `gatewayUrl`: this is the actual endpoint the app should use.
+- `urlSource`: this tells you which config path won.
+
+Common good sources:
+
+- `gateway.bind=lan`: same Wi-Fi / LAN only
+- `gateway.bind=tailnet`: direct tailnet access
+- `gateway.tailscale.mode=serve` or `gateway.tailscale.mode=funnel`: Tailscale route
+- `plugins.entries.device-pair.config.publicUrl`: explicit public/reverse-proxy route
+- `gateway.remote.url`: remote gateway route
+
+## Root-cause map
+
+If `openclaw qr --json` says `Gateway is only bound to loopback`:
+
+- remote node cannot connect yet
+- fix the route, then generate a fresh setup code
+- `gateway.bind=auto` is not enough if the effective QR route is still loopback
+- same LAN: use `gateway.bind=lan`
+- same tailnet: prefer `gateway.tailscale.mode=serve` or use `gateway.bind=tailnet`
+- public internet: set a real `plugins.entries.device-pair.config.publicUrl` or `gateway.remote.url`
+
+If `gateway.bind=tailnet set, but no tailnet IP was found`:
+
+- gateway host is not actually on Tailscale
+
+If `qr --remote requires gateway.remote.url`:
+
+- remote-mode config is incomplete
+
+If the app says `pairing required`:
+
+- network route and auth worked
+- approve the pending device
+
+```bash
+openclaw devices list
+openclaw devices approve --latest
+```
+
+If the app says `bootstrap token invalid or expired`:
+
+- old setup code
+- generate a fresh one and rescan
+- do this after any URL/auth fix too
+
+If the app says `unauthorized`:
+
+- wrong token/password, or wrong Tailscale expectation
+- for Tailscale Serve, `gateway.auth.allowTailscale` must match the intended flow
+- otherwise use explicit token/password
+
+## Fast heuristics
+
+- Same Wi-Fi setup + gateway advertises `127.0.0.1`, `localhost`, or loopback-only config: wrong.
+- Remote setup + setup/manual uses private LAN IP: wrong.
+- Tailnet setup + gateway advertises LAN IP instead of MagicDNS / tailnet route: wrong.
+- Public URL set but QR still advertises something else: inspect `urlSource`; config is not what you think.
+- `openclaw devices list` shows pending requests: stop changing network config and approve first.
+
+## Fix style
+
+Reply with one concrete diagnosis and one route.
+
+If there is not enough signal yet, ask for setup + exact app text instead of guessing.
+
+Good:
+
+- `The gateway is still loopback-only, so a node on another network can never reach it. Enable Tailscale Serve, restart the gateway, run openclaw qr again, rescan, then approve the pending device pairing.`
+
+Bad:
+
+- `Maybe LAN, maybe Tailscale, maybe port forwarding, maybe public URL.`

skills/notion/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: notion
+description: Notion API for creating and managing pages, databases, and blocks.
+homepage: https://developers.notion.com
+metadata:
+  {
+    "openclaw":
+      { "emoji": "📝", "requires": { "env": ["NOTION_API_KEY"] }, "primaryEnv": "NOTION_API_KEY" },
+  }
+---
+
+# notion
+
+Use the Notion API to create/read/update pages, data sources (databases), and blocks.
+
+## Setup
+
+1. Create an integration at https://notion.so/my-integrations
+2. Copy the API key (starts with `ntn_` or `secret_`)
+3. Store it:
+
+```bash
+mkdir -p ~/.config/notion
+echo "ntn_your_key_here" > ~/.config/notion/api_key
+```
+
+4. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)
+
+## API Basics
+
+All requests need:
+
+```bash
+NOTION_KEY=$(cat ~/.config/notion/api_key)
+curl -X GET "https://api.notion.com/v1/..." \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json"
+```
+
+> **Note:** The `Notion-Version` header is required. This skill uses `2025-09-03` (latest). In this version, databases are called "data sources" in the API.
+
+## Common Operations
+
+**Search for pages and data sources:**
+
+```bash
+curl -X POST "https://api.notion.com/v1/search" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "page title"}'
+```
+
+**Get page:**
+
+```bash
+curl "https://api.notion.com/v1/pages/{page_id}" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03"
+```
+
+**Get page content (blocks):**
+
+```bash
+curl "https://api.notion.com/v1/blocks/{page_id}/children" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03"
+```
+
+**Create page in a data source:**
+
+```bash
+curl -X POST "https://api.notion.com/v1/pages" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parent": {"database_id": "xxx"},
+    "properties": {
+      "Name": {"title": [{"text": {"content": "New Item"}}]},
+      "Status": {"select": {"name": "Todo"}}
+    }
+  }'
+```
+
+**Query a data source (database):**
+
+```bash
+curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filter": {"property": "Status", "select": {"equals": "Active"}},
+    "sorts": [{"property": "Date", "direction": "descending"}]
+  }'
+```
+
+**Create a data source (database):**
+
+```bash
+curl -X POST "https://api.notion.com/v1/data_sources" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parent": {"page_id": "xxx"},
+    "title": [{"text": {"content": "My Database"}}],
+    "properties": {
+      "Name": {"title": {}},
+      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
+      "Date": {"date": {}}
+    }
+  }'
+```
+
+**Update page properties:**
+
+```bash
+curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'
+```
+
+**Add blocks to page:**
+
+```bash
+curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "children": [
+      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
+    ]
+  }'
+```
+
+## Property Types
+
+Common property formats for database items:
+
+- **Title:** `{"title": [{"text": {"content": "..."}}]}`
+- **Rich text:** `{"rich_text": [{"text": {"content": "..."}}]}`
+- **Select:** `{"select": {"name": "Option"}}`
+- **Multi-select:** `{"multi_select": [{"name": "A"}, {"name": "B"}]}`
+- **Date:** `{"date": {"start": "2024-01-15", "end": "2024-01-16"}}`
+- **Checkbox:** `{"checkbox": true}`
+- **Number:** `{"number": 42}`
+- **URL:** `{"url": "https://..."}`
+- **Email:** `{"email": "a@b.com"}`
+- **Relation:** `{"relation": [{"id": "page_id"}]}`
+
+## Key Differences in 2025-09-03
+
+- **Databases → Data Sources:** Use `/data_sources/` endpoints for queries and retrieval
+- **Two IDs:** Each database now has both a `database_id` and a `data_source_id`
+  - Use `database_id` when creating pages (`parent: {"database_id": "..."}`)
+  - Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)
+- **Search results:** Databases return as `"object": "data_source"` with their `data_source_id`
+- **Parent in responses:** Pages show `parent.data_source_id` alongside `parent.database_id`
+- **Finding the data_source_id:** Search for the database, or call `GET /v1/data_sources/{data_source_id}`
+
+## Notes
+
+- Page/database IDs are UUIDs (with or without dashes)
+- The API cannot set database view filters — that's UI-only
+- Rate limit: ~3 requests/second average, with `429 rate_limited` responses using `Retry-After`
+- Append block children: up to 100 children per request, up to two levels of nesting in a single append request
+- Payload size limits: up to 1000 block elements and 500KB overall
+- Use `is_inline: true` when creating data sources to embed them in pages

skills/obsidian/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: obsidian
+description: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.
+homepage: https://help.obsidian.md
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "💎",
+        "requires": { "bins": ["obsidian-cli"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "yakitrak/yakitrak/obsidian-cli",
+              "bins": ["obsidian-cli"],
+              "label": "Install obsidian-cli (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Obsidian
+
+Obsidian vault = a normal folder on disk.
+
+Vault structure (typical)
+
+- Notes: `*.md` (plain text Markdown; edit with any editor)
+- Config: `.obsidian/` (workspace + plugin settings; usually don’t touch from scripts)
+- Canvases: `*.canvas` (JSON)
+- Attachments: whatever folder you chose in Obsidian settings (images/PDFs/etc.)
+
+## Find the active vault(s)
+
+Obsidian desktop tracks vaults here (source of truth):
+
+- `~/Library/Application Support/obsidian/obsidian.json`
+
+`obsidian-cli` resolves vaults from that file; vault name is typically the **folder name** (path suffix).
+
+Fast “what vault is active / where are the notes?”
+
+- If you’ve already set a default: `obsidian-cli print-default --path-only`
+- Otherwise, read `~/Library/Application Support/obsidian/obsidian.json` and use the vault entry with `"open": true`.
+
+Notes
+
+- Multiple vaults common (iCloud vs `~/Documents`, work/personal, etc.). Don’t guess; read config.
+- Avoid writing hardcoded vault paths into scripts; prefer reading the config or using `print-default`.
+
+## obsidian-cli quick start
+
+Pick a default vault (once):
+
+- `obsidian-cli set-default "<vault-folder-name>"`
+- `obsidian-cli print-default` / `obsidian-cli print-default --path-only`
+
+Search
+
+- `obsidian-cli search "query"` (note names)
+- `obsidian-cli search-content "query"` (inside notes; shows snippets + lines)
+
+Create
+
+- `obsidian-cli create "Folder/New note" --content "..." --open`
+- Requires Obsidian URI handler (`obsidian://…`) working (Obsidian installed).
+- Avoid creating notes under “hidden” dot-folders (e.g. `.something/...`) via URI; Obsidian may refuse.
+
+Move/rename (safe refactor)
+
+- `obsidian-cli move "old/path/note" "new/path/note"`
+- Updates `[[wikilinks]]` and common Markdown links across the vault (this is the main win vs `mv`).
+
+Delete
+
+- `obsidian-cli delete "path/note"`
+
+Prefer direct edits when appropriate: open the `.md` file and change it; Obsidian will pick it up.

skills/openai-whisper-api/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: openai-whisper-api
+description: Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
+homepage: https://platform.openai.com/docs/guides/speech-to-text
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🌐",
+        "requires": { "bins": ["curl"], "env": ["OPENAI_API_KEY"] },
+        "primaryEnv": "OPENAI_API_KEY",
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "curl",
+              "bins": ["curl"],
+              "label": "Install curl (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# OpenAI Whisper API (curl)
+
+Transcribe an audio file via OpenAI’s `/v1/audio/transcriptions` endpoint. Set `OPENAI_BASE_URL` to use an OpenAI-compatible proxy or local gateway.
+
+## Quick start
+
+```bash
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a
+```
+
+Defaults:
+
+- Model: `whisper-1`
+- Output: `<input>.txt`
+
+## Useful flags
+
+```bash
+{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1 --out /tmp/transcript.txt
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --language en
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --prompt "Speaker names: Peter, Daniel"
+{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --json --out /tmp/transcript.json
+```
+
+## API key
+
+Set `OPENAI_API_KEY`, or configure it in the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`). Optionally set `OPENAI_BASE_URL` (for example `http://127.0.0.1:51805/v1`) to use an OpenAI-compatible proxy or local gateway:
+
+```json5
+{
+  skills: {
+    "openai-whisper-api": {
+      apiKey: "OPENAI_KEY_HERE",
+    },
+  },
+}
+```

skills/openai-whisper/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: openai-whisper
+description: Local speech-to-text with the Whisper CLI (no API key).
+homepage: https://openai.com/research/whisper
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🎤",
+        "requires": { "bins": ["whisper"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "openai-whisper",
+              "bins": ["whisper"],
+              "label": "Install OpenAI Whisper (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Whisper (CLI)
+
+Use `whisper` to transcribe audio locally.
+
+Quick start
+
+- `whisper /path/audio.mp3 --model medium --output_format txt --output_dir .`
+- `whisper /path/audio.m4a --task translate --output_format srt`
+
+Notes
+
+- Models download to `~/.cache/whisper` on first run.
+- `--model` defaults to `turbo` on this install.
+- Use smaller models for speed, larger for accuracy.

skills/openhue/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: openhue
+description: Control Philips Hue lights and scenes via the OpenHue CLI.
+homepage: https://www.openhue.io/cli
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "💡",
+        "requires": { "bins": ["openhue"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "openhue/cli/openhue-cli",
+              "bins": ["openhue"],
+              "label": "Install OpenHue CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# OpenHue CLI
+
+Use `openhue` to control Philips Hue lights and scenes via a Hue Bridge.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- "Turn on/off the lights"
+- "Dim the living room lights"
+- "Set a scene" or "movie mode"
+- Controlling specific Hue rooms or zones
+- Adjusting brightness, color, or color temperature
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Non-Hue smart devices (other brands) → not supported
+- HomeKit scenes or Shortcuts → use Apple's ecosystem
+- TV or entertainment system control
+- Thermostat or HVAC
+- Smart plugs (unless Hue smart plugs)
+
+## Common Commands
+
+### List Resources
+
+```bash
+openhue get light       # List all lights
+openhue get room        # List all rooms
+openhue get scene       # List all scenes
+```
+
+### Control Lights
+
+```bash
+# Turn on/off
+openhue set light "Bedroom Lamp" --on
+openhue set light "Bedroom Lamp" --off
+
+# Brightness (0-100)
+openhue set light "Bedroom Lamp" --on --brightness 50
+
+# Color temperature (warm to cool: 153-500 mirek)
+openhue set light "Bedroom Lamp" --on --temperature 300
+
+# Color (by name or hex)
+openhue set light "Bedroom Lamp" --on --color red
+openhue set light "Bedroom Lamp" --on --rgb "#FF5500"
+```
+
+### Control Rooms
+
+```bash
+# Turn off entire room
+openhue set room "Bedroom" --off
+
+# Set room brightness
+openhue set room "Bedroom" --on --brightness 30
+```
+
+### Scenes
+
+```bash
+# Activate scene
+openhue set scene "Relax" --room "Bedroom"
+openhue set scene "Concentrate" --room "Office"
+```
+
+## Quick Presets
+
+```bash
+# Bedtime (dim warm)
+openhue set room "Bedroom" --on --brightness 20 --temperature 450
+
+# Work mode (bright cool)
+openhue set room "Office" --on --brightness 100 --temperature 250
+
+# Movie mode (dim)
+openhue set room "Living Room" --on --brightness 10
+```
+
+## Notes
+
+- Bridge must be on local network
+- First run requires button press on Hue bridge to pair
+- Colors only work on color-capable bulbs (not white-only)

skills/oracle/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: oracle
+description: Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).
+homepage: https://askoracle.dev
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🧿",
+        "requires": { "bins": ["oracle"] },
+        "install":
+          [
+            {
+              "id": "node",
+              "kind": "node",
+              "package": "@steipete/oracle",
+              "bins": ["oracle"],
+              "label": "Install oracle (node)",
+            },
+          ],
+      },
+  }
+---
+
+# oracle — best use
+
+Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat output as advisory: verify against code + tests.
+
+## Main use case (browser, GPT‑5.2 Pro)
+
+Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.
+
+Recommended defaults:
+
+- Engine: browser (`--engine browser`)
+- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model "5.2 Pro"`)
+
+## Golden path
+
+1. Pick a tight file set (fewest files that still contain the truth).
+2. Preview payload + token spend (`--dry-run` + `--files-report`).
+3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
+4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).
+
+## Commands (preferred)
+
+- Help:
+  - `oracle --help`
+  - If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).
+
+- Preview (no tokens):
+  - `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`
+  - `oracle --dry-run full -p "<task>" --file "src/**"`
+
+- Token sanity:
+  - `oracle --dry-run summary --files-report -p "<task>" --file "src/**"`
+
+- Browser run (main path; long-running is normal):
+  - `oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`
+
+- Manual paste fallback:
+  - `oracle --render --copy -p "<task>" --file "src/**"`
+  - Note: `--copy` is a hidden alias for `--copy-markdown`.
+
+## Attaching files (`--file`)
+
+`--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.
+
+- Include:
+  - `--file "src/**"`
+  - `--file src/index.ts`
+  - `--file docs --file README.md`
+
+- Exclude:
+  - `--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"`
+
+- Defaults (implementation behavior):
+  - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless explicitly passed as literal dirs/files).
+  - Honors `.gitignore` when expanding globs.
+  - Does not follow symlinks.
+  - Dotfiles filtered unless opted in via pattern (e.g. `--file ".github/**"`).
+  - Files > 1 MB rejected.
+
+## Engines (API vs browser)
+
+- Auto-pick: `api` when `OPENAI_API_KEY` is set; otherwise `browser`.
+- Browser supports GPT + Gemini only; use `--engine api` for Claude/Grok/Codex or multi-model runs.
+- Browser attachments:
+  - `--browser-attachments auto|never|always` (auto pastes inline up to ~60k chars then uploads).
+- Remote browser host:
+  - Host: `oracle serve --host 0.0.0.0 --port 9473 --token <secret>`
+  - Client: `oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"`
+
+## Sessions + slugs
+
+- Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
+- Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach.
+  - List: `oracle status --hours 72`
+  - Attach: `oracle session <id> --render`
+- Use `--slug "<3-5 words>"` to keep session IDs readable.
+- Duplicate prompt guard exists; use `--force` only when you truly want a fresh run.
+
+## Prompt template (high signal)
+
+Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:
+
+- Project briefing (stack + build/test commands + platform constraints).
+- “Where things live” (key directories, entrypoints, config files, boundaries).
+- Exact question + what you tried + the error text (verbatim).
+- Constraints (“don’t change X”, “must keep public API”, etc).
+- Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).
+
+## Safety
+
+- Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required.
+
+## “Exhaustive prompt” restoration pattern
+
+For long investigations, write a standalone prompt + file set so you can rerun days later:
+
+- 6–30 sentence project briefing + the goal.
+- Repro steps + exact errors + what you tried.
+- Attach all context files needed (entrypoints, configs, key modules, docs).
+
+Oracle runs are one-shot; the model doesn’t remember prior runs. “Restoring context” means re-running with the same prompt + `--file …` set (or reattaching a still-running stored session).

skills/ordercli/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ordercli
+description: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).
+homepage: https://ordercli.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🛵",
+        "requires": { "bins": ["ordercli"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/ordercli",
+              "bins": ["ordercli"],
+              "label": "Install ordercli (brew)",
+            },
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/ordercli/cmd/ordercli@latest",
+              "bins": ["ordercli"],
+              "label": "Install ordercli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# ordercli
+
+Use `ordercli` to check past orders and track active order status (Foodora only right now).
+
+Quick start (Foodora)
+
+- `ordercli foodora countries`
+- `ordercli foodora config set --country AT`
+- `ordercli foodora login --email you@example.com --password-stdin`
+- `ordercli foodora orders`
+- `ordercli foodora history --limit 20`
+- `ordercli foodora history show <orderCode>`
+
+Orders
+
+- Active list (arrival/status): `ordercli foodora orders`
+- Watch: `ordercli foodora orders --watch`
+- Active order detail: `ordercli foodora order <orderCode>`
+- History detail JSON: `ordercli foodora history show <orderCode> --json`
+
+Reorder (adds to cart)
+
+- Preview: `ordercli foodora reorder <orderCode>`
+- Confirm: `ordercli foodora reorder <orderCode> --confirm`
+- Address: `ordercli foodora reorder <orderCode> --confirm --address-id <id>`
+
+Cloudflare / bot protection
+
+- Browser login: `ordercli foodora login --email you@example.com --password-stdin --browser`
+- Reuse profile: `--browser-profile "$HOME/Library/Application Support/ordercli/browser-profile"`
+- Import Chrome cookies: `ordercli foodora cookies chrome --profile "Default"`
+
+Session import (no password)
+
+- `ordercli foodora session chrome --url https://www.foodora.at/ --profile "Default"`
+- `ordercli foodora session refresh --client-id android`
+
+Deliveroo (WIP, not working yet)
+
+- Requires `DELIVEROO_BEARER_TOKEN` (optional `DELIVEROO_COOKIE`).
+- `ordercli deliveroo config set --market uk`
+- `ordercli deliveroo history`
+
+Notes
+
+- Use `--config /tmp/ordercli.json` for testing.
+- Confirm before any reorder or cart-changing action.

skills/peekaboo/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: peekaboo
+description: Capture and automate macOS UI with the Peekaboo CLI.
+homepage: https://peekaboo.boo
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "👀",
+        "os": ["darwin"],
+        "requires": { "bins": ["peekaboo"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/peekaboo",
+              "bins": ["peekaboo"],
+              "label": "Install Peekaboo (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Peekaboo
+
+Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI
+elements, drive input, and manage apps/windows/menus. Commands share a snapshot
+cache and support `--json`/`-j` for scripting. Run `peekaboo` or
+`peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata.
+Tip: run via `polter peekaboo` to ensure fresh builds.
+
+## Features (all CLI capabilities, excluding agent/MCP)
+
+Core
+
+- `bridge`: inspect Peekaboo Bridge host connectivity
+- `capture`: live capture or video ingest + frame extraction
+- `clean`: prune snapshot cache and temp files
+- `config`: init/show/edit/validate, providers, models, credentials
+- `image`: capture screenshots (screen/window/menu bar regions)
+- `learn`: print the full agent guide + tool catalog
+- `list`: apps, windows, screens, menubar, permissions
+- `permissions`: check Screen Recording/Accessibility status
+- `run`: execute `.peekaboo.json` scripts
+- `sleep`: pause execution for a duration
+- `tools`: list available tools with filtering/display options
+
+Interaction
+
+- `click`: target by ID/query/coords with smart waits
+- `drag`: drag & drop across elements/coords/Dock
+- `hotkey`: modifier combos like `cmd,shift,t`
+- `move`: cursor positioning with optional smoothing
+- `paste`: set clipboard -> paste -> restore
+- `press`: special-key sequences with repeats
+- `scroll`: directional scrolling (targeted + smooth)
+- `swipe`: gesture-style drags between targets
+- `type`: text + control keys (`--clear`, delays)
+
+System
+
+- `app`: launch/quit/relaunch/hide/unhide/switch/list apps
+- `clipboard`: read/write clipboard (text/images/files)
+- `dialog`: click/input/file/dismiss/list system dialogs
+- `dock`: launch/right-click/hide/show/list Dock items
+- `menu`: click/list application menus + menu extras
+- `menubar`: list/click status bar items
+- `open`: enhanced `open` with app targeting + JSON payloads
+- `space`: list/switch/move-window (Spaces)
+- `visualizer`: exercise Peekaboo visual feedback animations
+- `window`: close/minimize/maximize/move/resize/focus/list
+
+Vision
+
+- `see`: annotated UI maps, snapshot IDs, optional analysis
+
+Global runtime flags
+
+- `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>`
+- `--no-remote`, `--bridge-socket <path>`
+
+## Quickstart (happy path)
+
+```bash
+peekaboo permissions
+peekaboo list apps --json
+peekaboo see --annotate --path /tmp/peekaboo-see.png
+peekaboo click --on B1
+peekaboo type "Hello" --return
+```
+
+## Common targeting parameters (most interaction commands)
+
+- App/window: `--app`, `--pid`, `--window-title`, `--window-id`, `--window-index`
+- Snapshot targeting: `--snapshot` (ID from `see`; defaults to latest)
+- Element/coords: `--on`/`--id` (element ID), `--coords x,y`
+- Focus control: `--no-auto-focus`, `--space-switch`, `--bring-to-current-space`,
+  `--focus-timeout-seconds`, `--focus-retry-count`
+
+## Common capture parameters
+
+- Output: `--path`, `--format png|jpg`, `--retina`
+- Targeting: `--mode screen|window|frontmost`, `--screen-index`,
+  `--window-title`, `--window-id`
+- Analysis: `--analyze "prompt"`, `--annotate`
+- Capture engine: `--capture-engine auto|classic|cg|modern|sckit`
+
+## Common motion/typing parameters
+
+- Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press)
+- Human-ish movement: `--profile human|linear`, `--wpm` (typing)
+- Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth`
+
+## Examples
+
+### See -> click -> type (most reliable flow)
+
+```bash
+peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
+peekaboo click --on B3 --app Safari
+peekaboo type "user@example.com" --app Safari
+peekaboo press tab --count 1 --app Safari
+peekaboo type "supersecret" --app Safari --return
+```
+
+### Target by window id
+
+```bash
+peekaboo list windows --app "Visual Studio Code" --json
+peekaboo click --window-id 12345 --coords 120,160
+peekaboo type "Hello from Peekaboo" --window-id 12345
+```
+
+### Capture screenshots + analyze
+
+```bash
+peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
+peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
+peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"
+```
+
+### Live capture (motion-aware)
+
+```bash
+peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
+  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture
+```
+
+### App + window management
+
+```bash
+peekaboo app launch "Safari" --open https://example.com
+peekaboo window focus --app Safari --window-title "Example"
+peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
+peekaboo app quit --app Safari
+```
+
+### Menus, menubar, dock
+
+```bash
+peekaboo menu click --app Safari --item "New Window"
+peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
+peekaboo menu click-extra --title "WiFi"
+peekaboo dock launch Safari
+peekaboo menubar list --json
+```
+
+### Mouse + gesture input
+
+```bash
+peekaboo move 500,300 --smooth
+peekaboo drag --from B1 --to T2
+peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
+peekaboo scroll --direction down --amount 6 --smooth
+```
+
+### Keyboard input
+
+```bash
+peekaboo hotkey --keys "cmd,shift,t"
+peekaboo press escape
+peekaboo type "Line 1\nLine 2" --delay 10
+```
+
+Notes
+
+- Requires Screen Recording + Accessibility permissions.
+- Use `peekaboo see --annotate` to identify targets before clicking.

skills/sag/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: sag
+description: ElevenLabs text-to-speech with mac-style say UX.
+homepage: https://sag.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔊",
+        "requires": { "bins": ["sag"], "env": ["ELEVENLABS_API_KEY"] },
+        "primaryEnv": "ELEVENLABS_API_KEY",
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/sag",
+              "bins": ["sag"],
+              "label": "Install sag (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# sag
+
+Use `sag` for ElevenLabs TTS with local playback.
+
+API key (required)
+
+- `ELEVENLABS_API_KEY` (preferred)
+- `SAG_API_KEY` also supported by the CLI
+
+Quick start
+
+- `sag "Hello there"`
+- `sag speak -v "Roger" "Hello"`
+- `sag voices`
+- `sag prompting` (model-specific tips)
+
+Model notes
+
+- Default: `eleven_v3` (expressive)
+- Stable: `eleven_multilingual_v2`
+- Fast: `eleven_flash_v2_5`
+
+Pronunciation + delivery rules
+
+- First fix: respell (e.g. "key-note"), add hyphens, adjust casing.
+- Numbers/units/URLs: `--normalize auto` (or `off` if it harms names).
+- Language bias: `--lang en|de|fr|...` to guide normalization.
+- v3: SSML `<break>` not supported; use `[pause]`, `[short pause]`, `[long pause]`.
+- v2/v2.5: SSML `<break time="1.5s" />` supported; `<phoneme>` not exposed in `sag`.
+
+v3 audio tags (put at the entrance of a line)
+
+- `[whispers]`, `[shouts]`, `[sings]`
+- `[laughs]`, `[starts laughing]`, `[sighs]`, `[exhales]`
+- `[sarcastic]`, `[curious]`, `[excited]`, `[crying]`, `[mischievously]`
+- Example: `sag "[whispers] keep this quiet. [short pause] ok?"`
+
+Voice defaults
+
+- `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID`
+
+Confirm voice + speaker before long output.
+
+## Chat voice responses
+
+When the user asks for a "voice" reply (e.g., "crazy scientist voice", "explain in voice"), generate audio and send it:
+
+```bash
+# Generate audio file
+sag -v Clawd -o /tmp/voice-reply.mp3 "Your message here"
+
+# Then include in reply:
+# MEDIA:/tmp/voice-reply.mp3
+```
+
+Voice character tips:
+
+- Crazy scientist: Use `[excited]` tags, dramatic pauses `[short pause]`, vary intensity
+- Calm: Use `[whispers]` or slower pacing
+- Dramatic: Use `[sings]` or `[shouts]` sparingly
+
+Default voice for Clawd: `lj2rcrvANS3gaWWnczSX` (or just `-v Clawd`)

skills/session-logs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: session-logs
+description: Search and analyze your own session logs (older/parent conversations) using jq.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📜",
+        "requires": { "bins": ["jq", "rg"] },
+        "install":
+          [
+            {
+              "id": "brew-jq",
+              "kind": "brew",
+              "formula": "jq",
+              "bins": ["jq"],
+              "label": "Install jq (brew)",
+            },
+            {
+              "id": "brew-rg",
+              "kind": "brew",
+              "formula": "ripgrep",
+              "bins": ["rg"],
+              "label": "Install ripgrep (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# session-logs
+
+Search your complete conversation history stored in session JSONL files. Use this when a user references older/parent conversations or asks what was said before.
+
+## Trigger
+
+Use this skill when the user asks about prior chats, parent conversations, or historical context that isn't in memory files.
+
+## Location
+
+Session logs live under the active state directory:
+`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` (default: `~/.openclaw/agents/<agentId>/sessions/`).
+Use the `agent=<id>` value from the system prompt Runtime line.
+
+- **`sessions.json`** - Index mapping session keys to session IDs
+- **`<session-id>.jsonl`** - Full conversation transcript per session
+
+## Structure
+
+Each `.jsonl` file contains messages with:
+
+- `type`: "session" (metadata) or "message"
+- `timestamp`: ISO timestamp
+- `message.role`: "user", "assistant", or "toolResult"
+- `message.content[]`: Text, thinking, or tool calls (filter `type=="text"` for human-readable content)
+- `message.usage.cost.total`: Cost per response
+
+## Common Queries
+
+### List all sessions by date and size
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
+for f in "$SESSION_DIR"/*.jsonl; do
+  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
+  size=$(ls -lh "$f" | awk '{print $5}')
+  echo "$date $size $(basename $f)"
+done | sort -r
+```
+
+### Find sessions from a specific day
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
+for f in "$SESSION_DIR"/*.jsonl; do
+  head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
+done
+```
+
+### Extract user messages from a session
+
+```bash
+jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl
+```
+
+### Search for keyword in assistant responses
+
+```bash
+jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | rg -i "keyword"
+```
+
+### Get total cost for a session
+
+```bash
+jq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl
+```
+
+### Daily cost summary
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
+for f in "$SESSION_DIR"/*.jsonl; do
+  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
+  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
+  echo "$date $cost"
+done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r
+```
+
+### Count messages and tokens in a session
+
+```bash
+jq -s '{
+  messages: length,
+  user: [.[] | select(.message.role == "user")] | length,
+  assistant: [.[] | select(.message.role == "assistant")] | length,
+  first: .[0].timestamp,
+  last: .[-1].timestamp
+}' <session>.jsonl
+```
+
+### Tool usage breakdown
+
+```bash
+jq -r '.message.content[]? | select(.type == "toolCall") | .name' <session>.jsonl | sort | uniq -c | sort -rn
+```
+
+### Search across ALL sessions for a phrase
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
+rg -l "phrase" "$SESSION_DIR"/*.jsonl
+```
+
+## Tips
+
+- Sessions are append-only JSONL (one JSON object per line)
+- Large sessions can be several MB - use `head`/`tail` for sampling
+- The `sessions.json` index maps chat providers (discord, whatsapp, etc.) to session IDs
+- Deleted sessions have `.deleted.<timestamp>` suffix
+
+## Fast text-only hint (low noise)
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
+jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' "$SESSION_DIR"/<id>.jsonl | rg 'keyword'
+```

skills/sherpa-onnx-tts/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: sherpa-onnx-tts
+description: Local text-to-speech via sherpa-onnx (offline, no cloud)
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔉",
+        "os": ["darwin", "linux", "win32"],
+        "requires": { "env": ["SHERPA_ONNX_RUNTIME_DIR", "SHERPA_ONNX_MODEL_DIR"] },
+        "install":
+          [
+            {
+              "id": "download-runtime-macos",
+              "kind": "download",
+              "os": ["darwin"],
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-osx-universal2-shared.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "stripComponents": 1,
+              "targetDir": "runtime",
+              "label": "Download sherpa-onnx runtime (macOS)",
+            },
+            {
+              "id": "download-runtime-linux-x64",
+              "kind": "download",
+              "os": ["linux"],
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-linux-x64-shared.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "stripComponents": 1,
+              "targetDir": "runtime",
+              "label": "Download sherpa-onnx runtime (Linux x64)",
+            },
+            {
+              "id": "download-runtime-win-x64",
+              "kind": "download",
+              "os": ["win32"],
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-win-x64-shared.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "stripComponents": 1,
+              "targetDir": "runtime",
+              "label": "Download sherpa-onnx runtime (Windows x64)",
+            },
+            {
+              "id": "download-model-lessac",
+              "kind": "download",
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-high.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "targetDir": "models",
+              "label": "Download Piper en_US lessac (high)",
+            },
+          ],
+      },
+  }
+---
+
+# sherpa-onnx-tts
+
+Local TTS using the sherpa-onnx offline CLI.
+
+## Install
+
+1. Download the runtime for your OS (extracts into `$OPENCLAW_STATE_DIR/tools/sherpa-onnx-tts/runtime`, default `~/.openclaw/tools/sherpa-onnx-tts/runtime`)
+2. Download a voice model (extracts into `$OPENCLAW_STATE_DIR/tools/sherpa-onnx-tts/models`, default `~/.openclaw/tools/sherpa-onnx-tts/models`)
+
+Resolve the active state directory first:
+
+```bash
+STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+```
+
+Then write those resolved paths into the active OpenClaw config file (`$OPENCLAW_CONFIG_PATH`, default `~/.openclaw/openclaw.json`):
+
+```json5
+{
+  skills: {
+    entries: {
+      "sherpa-onnx-tts": {
+        env: {
+          SHERPA_ONNX_RUNTIME_DIR: "/path/to/your/state-dir/tools/sherpa-onnx-tts/runtime",
+          SHERPA_ONNX_MODEL_DIR: "/path/to/your/state-dir/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high",
+        },
+      },
+    },
+  },
+}
+```
+
+The wrapper lives in this skill folder. Run it directly, or add the wrapper to PATH:
+
+```bash
+export PATH="{baseDir}/bin:$PATH"
+```
+
+## Usage
+
+```bash
+{baseDir}/bin/sherpa-onnx-tts -o ./tts.wav "Hello from local TTS."
+```
+
+Notes:
+
+- Pick a different model from the sherpa-onnx `tts-models` release if you want another voice.
+- If the model dir has multiple `.onnx` files, set `SHERPA_ONNX_MODEL_FILE` or pass `--model-file`.
+- You can also pass `--tokens-file` or `--data-dir` to override the defaults.
+- Windows: run `node {baseDir}\\bin\\sherpa-onnx-tts -o tts.wav "Hello from local TTS."`

skills/skill-creator/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: skill-creator
+description: Create, edit, improve, or audit AgentSkills. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory (moving files to references/ or scripts/, removing stale content, validating against the AgentSkills spec). Triggers on phrases like "create a skill", "author a skill", "tidy up a skill", "improve this skill", "review the skill", "clean up the skill", "audit the skill".
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Codex's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Codex from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: Codex is already very smart.** Only add context Codex doesn't already have. Challenge each piece of information: "Does Codex really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Codex reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Codex for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Codex's process and thinking.
+
+- **When to include**: For documentation that Codex should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Codex determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Codex produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Codex to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Codex (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+Codex loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, Codex only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+    ├── aws.md (AWS deployment patterns)
+    ├── gcp.md (GCP deployment patterns)
+    └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, Codex only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+Codex reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 64 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+scripts/init_skill.py my-skill --path skills/public
+scripts/init_skill.py my-skill --path skills/public --resources scripts,references
+scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Optionally creates resource directories based on `--resources`
+- Optionally adds example files when `--examples` is set
+
+After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Codex to use. Include information that would be beneficial and non-obvious to Codex. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Codex instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.
+  - Include both what the Skill does and specific triggers/contexts for when to use it.
+  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Codex.
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+   Security restriction: symlinks are rejected and packaging fails when any symlink is present.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again

skills/slack/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: slack
+description: Use when you need to control Slack from OpenClaw via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
+metadata: { "openclaw": { "emoji": "💬", "requires": { "config": ["channels.slack"] } } }
+---
+
+# Slack Actions
+
+## Overview
+
+Use `slack` to react, manage pins, send/edit/delete messages, and fetch member info. The tool uses the bot token configured for OpenClaw.
+
+## Inputs to collect
+
+- `channelId` and `messageId` (Slack message timestamp, e.g. `1712023032.1234`).
+- For reactions, an `emoji` (Unicode or `:name:`).
+- For message sends, a `to` target (`channel:<id>` or `user:<id>`) and `content`.
+
+Message context lines include `slack message id` and `channel` fields you can reuse directly.
+
+## Actions
+
+### Action groups
+
+| Action group | Default | Notes                  |
+| ------------ | ------- | ---------------------- |
+| reactions    | enabled | React + list reactions |
+| messages     | enabled | Read/send/edit/delete  |
+| pins         | enabled | Pin/unpin/list         |
+| memberInfo   | enabled | Member info            |
+| emojiList    | enabled | Custom emoji list      |
+
+### React to a message
+
+```json
+{
+  "action": "react",
+  "channelId": "C123",
+  "messageId": "1712023032.1234",
+  "emoji": "✅"
+}
+```
+
+### List reactions
+
+```json
+{
+  "action": "reactions",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Send a message
+
+```json
+{
+  "action": "sendMessage",
+  "to": "channel:C123",
+  "content": "Hello from OpenClaw"
+}
+```
+
+### Edit a message
+
+```json
+{
+  "action": "editMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234",
+  "content": "Updated text"
+}
+```
+
+### Delete a message
+
+```json
+{
+  "action": "deleteMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Read recent messages
+
+```json
+{
+  "action": "readMessages",
+  "channelId": "C123",
+  "limit": 20
+}
+```
+
+### Pin a message
+
+```json
+{
+  "action": "pinMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Unpin a message
+
+```json
+{
+  "action": "unpinMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### List pinned items
+
+```json
+{
+  "action": "listPins",
+  "channelId": "C123"
+}
+```
+
+### Member info
+
+```json
+{
+  "action": "memberInfo",
+  "userId": "U123"
+}
+```
+
+### Emoji list
+
+```json
+{
+  "action": "emojiList"
+}
+```
+
+## Ideas to try
+
+- React with ✅ to mark completed tasks.
+- Pin key decisions or weekly status updates.

skills/songsee/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: songsee
+description: Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.
+homepage: https://github.com/steipete/songsee
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🌊",
+        "requires": { "bins": ["songsee"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/songsee",
+              "bins": ["songsee"],
+              "label": "Install songsee (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# songsee
+
+Generate spectrograms + feature panels from audio.
+
+Quick start
+
+- Spectrogram: `songsee track.mp3`
+- Multi-panel: `songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux`
+- Time slice: `songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg`
+- Stdin: `cat track.mp3 | songsee - --format png -o out.png`
+
+Common flags
+
+- `--viz` list (repeatable or comma-separated)
+- `--style` palette (classic, magma, inferno, viridis, gray)
+- `--width` / `--height` output size
+- `--window` / `--hop` FFT settings
+- `--min-freq` / `--max-freq` frequency range
+- `--start` / `--duration` time slice
+- `--format` jpg|png
+
+Notes
+
+- WAV/MP3 decode native; other formats use ffmpeg if available.
+- Multiple `--viz` renders a grid.

skills/sonoscli/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sonoscli
+description: Control Sonos speakers (discover/status/play/volume/group).
+homepage: https://sonoscli.sh
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🔊",
+        "requires": { "bins": ["sonos"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/sonoscli/cmd/sonos@latest",
+              "bins": ["sonos"],
+              "label": "Install sonoscli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Sonos CLI
+
+Use `sonos` to control Sonos speakers on the local network.
+
+## Quick start
+
+- `sonos discover`
+- `sonos status --name "Kitchen"`
+- `sonos play|pause|stop --name "Kitchen"`
+- `sonos volume set 15 --name "Kitchen"`
+
+## Common tasks
+
+- Grouping: `sonos group status|join|unjoin|party|solo`
+- Favorites: `sonos favorites list|open`
+- Queue: `sonos queue list|play|clear`
+- Spotify search (via SMAPI): `sonos smapi search --service "Spotify" --category tracks "query"`
+
+## Notes
+
+- If SSDP fails, specify `--ip <speaker-ip>`.
+- Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`.
+- If there is an error, check the troubleshooting section and offer advice if there is a decent match.
+
+## Troubleshooting
+
+### `sonos discover` - `no route to host`
+
+- On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)`
+  - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either
+  - The `sendto: no route to host` should stay consistent
+- Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway
+  - `node` if running via `launchd`
+  - `Terminal` if running the gateway directly in the terminal
+  - `Visual Studio Code` if running via terminal in VS Code
+- An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox
+
+### `sonos discover` - `bind: operation not permitted`
+
+- On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted`
+- Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)

skills/spotify-player/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: spotify-player
+description: Terminal Spotify playback/search via spogo (preferred) or spotify_player.
+homepage: https://www.spotify.com
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🎵",
+        "requires": { "anyBins": ["spogo", "spotify_player"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spogo",
+              "tap": "steipete/tap",
+              "bins": ["spogo"],
+              "label": "Install spogo (brew)",
+            },
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spotify_player",
+              "bins": ["spotify_player"],
+              "label": "Install spotify_player (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# spogo / spotify_player
+
+Use `spogo` **(preferred)** for Spotify playback/search. Fall back to `spotify_player` if needed.
+
+Requirements
+
+- Spotify Premium account.
+- Either `spogo` or `spotify_player` installed.
+
+spogo setup
+
+- Import cookies: `spogo auth import --browser chrome`
+
+Common CLI commands
+
+- Search: `spogo search track "query"`
+- Playback: `spogo play|pause|next|prev`
+- Devices: `spogo device list`, `spogo device set "<name|id>"`
+- Status: `spogo status`
+
+spotify_player commands (fallback)
+
+- Search: `spotify_player search "query"`
+- Playback: `spotify_player playback play|pause|next|previous`
+- Connect device: `spotify_player connect`
+- Like track: `spotify_player like`
+
+Notes
+
+- Config folder: `~/.config/spotify-player` (e.g., `app.toml`).
+- For Spotify Connect integration, set a user `client_id` in config.
+- TUI shortcuts are available via `?` in the app.