total-recall-brain 3.1.0

package/scaffold/.agent/skills/total-recall/skills/skill/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: skill
+description: "Use this skill when creating, auditing, or modifying any skill in the .agent/skills/ ecosystem. MANDATORY: You MUST read the full SKILL.md file before executing."
+---
+
+# Skill Architecture — Canonical Format Guide
+
+> **Version:** 2.0.0 | **Updated:** 2026-05-11
+
+This is the definitive guide for how skills are structured, created, and maintained. Every agent that creates or modifies a skill MUST follow this spec exactly.
+
+---
+
+## 1. What is a Skill?
+
+A skill is a **self-contained knowledge package** that lives in `.agent/skills/<skill-name>/`. It gives an agent everything it needs to perform a specific domain task correctly: instructions, executable scripts, reference material, test criteria, and delegation prompts.
+
+Skills are NOT documentation. They are **executable expertise.**
+
+---
+
+## 2. Required Directory Structure
+
+Every skill MUST contain these items. No exceptions.
+
+```text
+my-skill/
+├── SKILL.md              # REQUIRED — The master instruction file
+├── scripts/              # REQUIRED — Automation scripts
+├── references/           # REQUIRED — Domain knowledge, specs, docs
+├── evals/                # REQUIRED — Success criteria and tests
+└── subagents/            # REQUIRED — Delegation prompts for subtasks
+```
+
+### Why all five are required
+
+Agents will skip optional folders without a second thought. By requiring all five, we force the agent to **stop and think** about what belongs in each one. Even a hastily written eval or a minimal reference doc is infinitely more valuable than nothing — it can always be improved later.
+
+---
+
+## 3. SKILL.md — The Entrypoint
+
+### Frontmatter (REQUIRED)
+
+```yaml
+---
+name: my-skill-name
+description: "Use this skill when [TRIGGER CONDITION]. MANDATORY: You MUST read the full SKILL.md file before executing."
+---
+```
+
+| Field | Rules |
+|:---|:---|
+| `name` | **Lowercase kebab-case.** Must exactly match the folder name. |
+| `description` | **Trigger-optimized.** Must clearly state WHAT it does and WHEN to use it. Under 1024 chars. The IDE uses this string to decide when to show the skill — vague descriptions mean the skill never gets activated. |
+
+### ⛔ Frontmatter Anti-Patterns
+
+```yaml
+# ❌ WRONG — SSSS memory node fields. Skills are NOT memory nodes.
+type: skill
+slug: my-skill
+category: architecture
+title: "My Skill"
+schema_version: 2
+importance: 4
+```
+
+```yaml
+# ✅ CORRECT — only name + description
+name: my-skill
+description: "Use this skill when doing X. MANDATORY: You MUST read the full SKILL.md file before executing."
+```
+
+### Body Content
+
+The body of SKILL.md is the **master prompt** for the skill. Write it as procedural instructions that an agent can follow step-by-step. Include:
+
+- **Context** — What problem does this skill solve?
+- **Steps** — Numbered, concrete actions
+- **Rules** — Hard constraints and invariants
+- **Pitfalls** — What goes wrong and how to avoid it
+- **Code examples** — Correct and incorrect patterns
+- **References** — Pointers to files in `references/` for deeper context
+
+---
+
+## 4. scripts/ — Execution Layer
+
+Contains executable code the agent runs via the sandbox to perform complex or deterministic operations.
+
+**What belongs here:**
+- Scaffolding scripts (e.g., `create-skill.sh`)
+- Validation/linting scripts (e.g., `enforce-skill-optimization.mjs`)
+- Watchers and cron-triggered automation (e.g., `watch.mjs`)
+- Data transformation or migration scripts
+- Any operation that should be deterministic rather than LLM-hallucinated
+
+**Rules:**
+- Scripts MUST be idempotent where possible
+- Scripts MUST be self-contained (no implicit dependencies outside the skill)
+- Scripts MUST handle errors gracefully with clear stderr output
+- Use `console.error()` for logging, never `console.log()` in production scripts
+
+**When creating a skill, ask yourself:** *"What operations in this domain should be automated with code instead of trusted to the LLM's judgment?"*
+
+---
+
+## 5. references/ — Domain Knowledge
+
+Contains static reference documents the agent reads for context when the skill is activated.
+
+**What belongs here:**
+- API documentation or spec excerpts
+- Schema definitions
+- Configuration format guides
+- Architecture decision records
+- Links to external sources with cached key sections
+- Example files or templates
+
+**Rules:**
+- Use Markdown (`.md`) files for text documentation
+- Keep files focused — one topic per file
+- Name files descriptively: `streamable-http-spec.md`, not `ref1.md`
+- Include the source URL at the top of any extracted documentation
+
+**When creating a skill, ask yourself:** *"What does an agent need to READ to understand this domain? What docs did I have to look up?"*
+
+---
+
+## 6. evals/ — Success Criteria
+
+Contains assertions, test scripts, or evaluation criteria that verify the skill was executed correctly.
+
+**What belongs here:**
+- `evals.json` — Structured assertions (minimum 3)
+- Test scripts that can be run in the sandbox
+- Checklists of things to verify
+- Expected output examples
+
+**evals.json format:**
+```json
+[
+  {
+    "name": "frontmatter-has-name",
+    "assertion": "SKILL.md YAML frontmatter contains a 'name' field",
+    "severity": "error"
+  },
+  {
+    "name": "description-is-trigger-optimized",
+    "assertion": "description field starts with 'Use this skill when'",
+    "severity": "warning"
+  },
+  {
+    "name": "no-empty-directories",
+    "assertion": "All required directories contain at least one non-.gitkeep file",
+    "severity": "error"
+  }
+]
+```
+
+**When creating a skill, ask yourself:** *"How would I know if this skill was used correctly? What could go wrong? What should I check?"*
+
+---
+
+## 7. subagents/ — Delegation Prompts
+
+Contains standalone prompt files for subtasks that can be delegated to parallel agents or focused workers.
+
+**What belongs here:**
+- Audit prompts (e.g., `audit-all-skills.md`)
+- Review prompts (e.g., `review-output.md`)
+- Specialized generation prompts (e.g., `generate-tests.md`)
+- Decomposed subtask prompts for complex workflows
+
+**Rules:**
+- Each file is a complete, self-contained prompt
+- Include role, context, constraints, and expected output format
+- Name files as verbs: `audit-X.md`, `generate-Y.md`, `validate-Z.md`
+
+**When creating a skill, ask yourself:** *"What parts of this task could be delegated to a focused subagent? What parallel work would speed this up?"*
+
+---
+
+## 8. Creating a New Skill
+
+### Quick method (script):
+```bash
+bash .agent/skills/skill/scripts/create-skill.sh my-new-skill
+```
+
+### Manual method:
+1. Create the folder: `.agent/skills/my-new-skill/`
+2. Create `SKILL.md` with proper `name` + `description` frontmatter
+3. Create `scripts/`, `references/`, `evals/`, `subagents/` directories
+4. Populate each directory — think deeply about what belongs in each one
+5. Write `evals/evals.json` with at least 3 assertions
+
+### The Deliberation Checklist
+
+Before committing a new skill, answer ALL of these:
+
+| Folder | Question |
+|:---|:---|
+| `SKILL.md` | Is the description trigger-optimized? Will the IDE activate this skill at the right time? |
+| `scripts/` | What operations should be deterministic code, not LLM guesses? |
+| `references/` | What domain knowledge does the agent need? What docs did I have to look up? |
+| `evals/` | How do I know if this skill was used correctly? What could go wrong? |
+| `subagents/` | What subtasks could be parallelized or delegated to a focused worker? |
+
+---
+
+## 9. Quality Enforcement
+
+The enforcement script (`scripts/enforce-skill-optimization.mjs`) validates all skills on commit:
+
+1. Every skill must have a `SKILL.md` with `name` and `description` frontmatter
+2. All five directories must exist and contain at least one real file (`.gitkeep` alone doesn't count)
+3. `evals/evals.json` must contain at least 3 assertions
+4. No placeholder/TODO-only SKILL.md files in committed skills
+
+---
+
+## 10. Safe Integration of External Skills
+
+When downloading, importing, or adding external skills from registries like `skills.sh` (via `npx skills add <name>`), agents and developers MUST perform security audits before executing any scripts:
+
+1. **Verify Executable Scripts**: Open and scan all scripts under `scripts/`. Look for shell template strings with dynamic interpolation or unchecked execution arguments.
+2. **Restrict Path Operations**: Ensure path references are validated and match regular expressions (e.g. `SAFE_NAME` pattern) to prevent path traversal vulnerabilities.
+3. **Assert Sandbox Isolation**: Prefer executing unfamiliar external skill scripts inside isolated sandbox environments or containers to guarantee zero adverse host system impact.
+
+---
+
+## 11. Common Mistakes
+
+| Mistake | Why It's Wrong | Fix |
+|:---|:---|:---|
+| Using `type`/`slug`/`category` in frontmatter | Those are SSSS memory node fields, not skill fields. IDE can't discover the skill. | Use only `name` and `description` |
+| Empty `references/` with just `.gitkeep` | Agent loses critical domain context | Add at least one reference doc — even a short one |
+| Empty `evals/` | No way to verify the skill worked | Write 3+ assertions in `evals.json` |
+| Vague description | `"A skill for doing stuff"` → IDE never triggers it | `"Use this skill when X. Do NOT use for Y."` |
+| Mixing format spec with implementation details | Contaminates portable knowledge with project-specific internals | Keep format docs generic, put project details in PRD |
+
+---
+
+## Changelog
+
+### v2.0.0 (2026-05-11)
+- **BREAKING**: Removed Total Recall-specific implementation details (surface.mjs routing, memory injection blocks, Gemma 4 references, P2 scheduling). This skill is now the universal format spec.
+- Added deliberation checklist forcing agents to think about each folder
+- Added "When creating a skill, ask yourself" prompts for each directory
+- Added frontmatter anti-patterns section
+- Added evals.json format example
+- Added common mistakes table
+
+### v1.0.0 (2026-05-10)
+- Initial version. Mixed universal skill format with Total Recall memory compiler internals, causing agent confusion.
+
+
+<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->
+<!-- @route: tfidf, generated_at: 2026-05-21T06:00:44.284Z -->
+
+- **inviolable-ide-instruction-7a4d8913** (confidence 1, importance critical):
+  Inviolable IDE Instruction: # Temporary Cursor Rules for testing
+
+- **always-reply-to-all-messages** (confidence 1, importance critical):
+  Always reply directly to all user messages without exception
+
+- **chocolate-brownies** (confidence 0.95, importance 4):
+  Chocolate brownies must be fudgey and rich
+
+- **security-audit-protocol** (confidence 1, importance 4):
+  Security audit protocol and hardening requirements
+
+- **operating-instructions** (confidence 1, importance 5):
+  Total Recall Core Operating Protocol
+
+- **no-cursor-or-windsurf-mentions** (confidence 1, importance critical):
+  Do not mention Cursor or Windsurf
+
+<!-- END INJECTED MEMORY -->

package/scaffold/.agent/skills/total-recall/skills/skill/assets/skill-template/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: SKILL_NAME_PLACEHOLDER
+description: "Use this template when creating new skills to ensure trigger-optimized descriptions. MANDATORY: You MUST read this file before executing."
+---
+
+# SKILL_NAME_PLACEHOLDER
+
+> TODO: Write procedural instructions for this skill.
+
+## Step 1: [First Action]
+
+TODO: Describe the first step.
+
+## Step 2: [Second Action]
+
+TODO: Describe the second step.
+
+## References
+
+- If you need X, see `references/X.md`

package/scaffold/.agent/skills/total-recall/skills/skill/evals/evals.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "skill-eval-1",
+    "description": "SKILL.md exists",
+    "command": "test -f .agent/skills/skill/SKILL.md",
+    "expected_exit_code": 0
+  },
+  {
+    "id": "skill-eval-2",
+    "description": "Evals validation",
+    "command": "test -f .agent/skills/skill/scripts/run-evals.mjs",
+    "expected_exit_code": 0
+  },
+  {
+    "id": "skill-eval-3",
+    "description": "Optimization enforcement",
+    "command": "test -f .agent/skills/skill/scripts/enforce-skill-optimization.mjs",
+    "expected_exit_code": 0
+  }
+]

package/scaffold/.agent/skills/total-recall/skills/skill/hooks/on-skill-add.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# on-skill-add.sh — Auto-regenerate the skill routing table when a new skill is added.
+#
+# Trigger: Run after creating a new skill via create-skill.sh or manually.
+# Action: Runs update-skill-index.mjs to sync the routing table and INSTRUCTIONS.md.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+echo "🔄 OnSkillAdd hook triggered — regenerating skill index..."
+node "$ROOT/.agent/skills/skill/scripts/update-skill-index.mjs"
+echo "✅ Routing table and INSTRUCTIONS.md updated."

package/scaffold/.agent/skills/total-recall/skills/skill/hooks/on-skill-delete.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# on-skill-delete.sh — Auto-clean the skill routing table when a skill is removed.
+#
+# Trigger: Run after deleting a skill directory.
+# Action: Runs update-skill-index.mjs to sync the routing table and INSTRUCTIONS.md.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+echo "🧹 OnSkillDelete hook triggered — cleaning skill index..."
+node "$ROOT/.agent/skills/skill/scripts/update-skill-index.mjs"
+echo "✅ Routing table and INSTRUCTIONS.md cleaned."

package/scaffold/.agent/skills/total-recall/skills/skill/scripts/create-skill.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# create-skill.sh — Scaffold a new Dev Skill from the template
+#
+# Usage: bash .agent/skills/skill/scripts/create-skill.sh <skill-name>
+# Example: bash .agent/skills/skill/scripts/create-skill.sh my-new-skill
+
+set -euo pipefail
+
+SKILL_NAME="${1:-}"
+
+if [ -z "$SKILL_NAME" ]; then
+  echo "❌ Usage: bash create-skill.sh <skill-name>"
+  echo "   Example: bash create-skill.sh my-new-skill"
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+SKILLS_DIR="$ROOT/.agent/skills"
+TARGET="$SKILLS_DIR/$SKILL_NAME"
+
+if [ -d "$TARGET" ]; then
+  echo "❌ Skill '$SKILL_NAME' already exists at $TARGET"
+  exit 1
+fi
+
+echo "📦 Creating skill: $SKILL_NAME"
+
+# Create directory structure
+mkdir -p "$TARGET"/{scripts,references}
+
+# Create SKILL.md with frontmatter template
+cat > "$TARGET/SKILL.md" << EOF
+---
+name: $SKILL_NAME
+description: "TODO: Write a trigger-optimized description. Format: WHAT it does + WHEN to use it + WHEN NOT to use it. Under 1024 chars."
+---
+
+# $SKILL_NAME
+
+> TODO: Write procedural instructions for this skill.
+
+## Step 1: [First Action]
+
+TODO: Describe the first step.
+
+## Step 2: [Second Action]
+
+TODO: Describe the second step.
+
+## References
+
+- If you need X, see \`references/X.md\`
+EOF
+
+echo "✅ Created $TARGET/SKILL.md"
+echo "✅ Created $TARGET/scripts/"
+echo "✅ Created $TARGET/references/"
+echo ""
+echo "📝 Next steps:"
+echo "  1. Edit $TARGET/SKILL.md with real instructions"
+echo "  2. Write a trigger-optimized description in the frontmatter"
+echo "  3. Run: node .agent/skills/skill/scripts/update-skill-index.mjs"
+echo ""
+echo "🏁 Done."

package/scaffold/.agent/skills/total-recall/skills/skill/scripts/enforce-skill-optimization.mjs

@@ -0,0 +1,135 @@
+/**
+ * enforce-skill-optimization.mjs
+ *
+ * Pre-commit validation for the skill ecosystem.
+ * Ensures every skill in .agent/skills/ meets the canonical format:
+ *   - SKILL.md with proper name + description frontmatter
+ *   - All required directories exist with real content
+ *   - evals/evals.json has ≥3 assertions
+ *
+ * Exit code 1 = validation failed (blocks commit)
+ * Exit code 0 = all skills valid
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKILLS_DIR = path.join(process.cwd(), '.agent/skills');
+const REQUIRED_DIRS = ['scripts', 'references', 'evals', 'subagents'];
+
+function parseYamlFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^(\w+):\s*(.+)/);
+    if (kv) {
+      fields[kv[1]] = kv[2].replace(/^["']|["']$/g, '');
+    }
+  }
+  return fields;
+}
+
+function hasRealContent(dirPath) {
+  if (!fs.existsSync(dirPath)) return false;
+  const entries = fs.readdirSync(dirPath);
+  return entries.some(e => e !== '.gitkeep');
+}
+
+function checkSkills() {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error('⚠️  No .agent/skills/ directory found. Skipping.');
+    process.exit(0);
+  }
+
+  const dirs = fs.readdirSync(SKILLS_DIR).filter(d =>
+    fs.statSync(path.join(SKILLS_DIR, d)).isDirectory()
+  );
+
+  const errors = [];
+  const warnings = [];
+
+  for (const skillName of dirs) {
+    const skillPath = path.join(SKILLS_DIR, skillName);
+    const skillMd = path.join(skillPath, 'SKILL.md');
+
+    // ── SKILL.md must exist ──────────────────────────────────────────────
+    if (!fs.existsSync(skillMd)) {
+      errors.push(`${skillName}: Missing SKILL.md`);
+      continue;
+    }
+
+    const content = fs.readFileSync(skillMd, 'utf8');
+    const frontmatter = parseYamlFrontmatter(content);
+
+    // ── Frontmatter must have name + description ─────────────────────────
+    if (!frontmatter) {
+      errors.push(`${skillName}: SKILL.md has no YAML frontmatter`);
+    } else {
+      if (!frontmatter.name) {
+        errors.push(`${skillName}: frontmatter missing 'name' field (has '${Object.keys(frontmatter).join(', ')}' instead)`);
+      } else if (frontmatter.name !== skillName) {
+        warnings.push(`${skillName}: frontmatter name '${frontmatter.name}' doesn't match folder name '${skillName}'`);
+      }
+
+      if (!frontmatter.description) {
+        errors.push(`${skillName}: frontmatter missing 'description' field`);
+      }
+
+      // Warn about SSSS memory node fields leaking into skill frontmatter
+      const badFields = ['type', 'slug', 'category', 'schema_version', 'importance', 'priority', 'modality'];
+      const found = badFields.filter(f => frontmatter[f]);
+      if (found.length > 0) {
+        errors.push(`${skillName}: frontmatter contains SSSS memory node fields (${found.join(', ')}). Skills use only 'name' and 'description'.`);
+      }
+    }
+
+    // ── Required directories ─────────────────────────────────────────────
+    for (const reqDir of REQUIRED_DIRS) {
+      const dirPath = path.join(skillPath, reqDir);
+      if (!fs.existsSync(dirPath)) {
+        errors.push(`${skillName}: missing required directory: ${reqDir}/`);
+      } else if (!hasRealContent(dirPath)) {
+        warnings.push(`${skillName}: ${reqDir}/ has no real content (only .gitkeep). Consider adding domain-specific files.`);
+      }
+    }
+
+    // ── evals.json quality check ─────────────────────────────────────────
+    const evalsPath = path.join(skillPath, 'evals', 'evals.json');
+    if (fs.existsSync(evalsPath)) {
+      try {
+        const evals = JSON.parse(fs.readFileSync(evalsPath, 'utf8'));
+        if (!Array.isArray(evals)) {
+          errors.push(`${skillName}: evals.json must be a JSON array`);
+        } else if (evals.length < 3) {
+          warnings.push(`${skillName}: evals.json has only ${evals.length} assertion(s) — minimum 3 recommended`);
+        }
+      } catch {
+        errors.push(`${skillName}: evals.json is invalid JSON`);
+      }
+    }
+  }
+
+  // ── Report ───────────────────────────────────────────────────────────────
+  if (warnings.length > 0) {
+    console.error('\n⚠️  Warnings:');
+    for (const w of warnings) console.error(`   ${w}`);
+  }
+
+  if (errors.length > 0) {
+    console.error('\n❌ Errors:');
+    for (const e of errors) console.error(`   ${e}`);
+    console.error(`\n🚨 SKILL ENFORCEMENT FAILED — ${errors.length} error(s) found.`);
+    console.error('   Fix the errors above before committing.\n');
+    process.exit(1);
+  }
+
+  console.error(`\n✅ All ${dirs.length} skills passed enforcement checks.`);
+  if (warnings.length > 0) {
+    console.error(`   (${warnings.length} warning(s) — not blocking)\n`);
+  }
+  process.exit(0);
+}
+
+checkSkills();

package/scaffold/.agent/skills/total-recall/skills/skill/scripts/find-skills.mjs

@@ -0,0 +1,124 @@
+/**
+ * find-skills.mjs — skills.sh Registry Search & Parser
+ *
+ * Parses the raw CLI output from `npx skills find <query>` into
+ * structured skill records. Used by the Sovereign Skill Manager to
+ * search, rank, and install community skills from skills.sh.
+ *
+ * Output format from `skills find`:
+ *   Install with npx skills add <owner/repo@skill>
+ *
+ *   steipete/clawdis@github 1.7K installs
+ *   └ https://skills.sh/steipete/clawdis/github
+ *
+ *   jiulingyun/openclaw-cn@github 21 installs
+ *   └ https://skills.sh/jiulingyun/openclaw-cn/github
+ */
+
+import { execSync } from 'node:child_process';
+
+// ─── Install Count Parser ────────────────────────────────────────────────────
+
+/**
+ * Convert a human-readable install count (e.g. "1.7" + "K") to an integer.
+ *
+ * @param {string} value - Numeric portion of the install count (e.g. "1.7", "21", "2.1")
+ * @param {string} unit  - SI suffix: "K" (thousands), "M" (millions), or "" (raw count)
+ * @returns {number} Integer install count, or 0 if parsing fails
+ *
+ * @example
+ *   parseInstalls("1.7", "K")   // → 1700
+ *   parseInstalls("21.3", "K")  // → 21300
+ *   parseInstalls("2.1", "M")   // → 2100000
+ *   parseInstalls("120", "")    // → 120
+ *   parseInstalls("invalid", "K") // → 0
+ */
+export function parseInstalls(value, unit) {
+  const num = parseFloat(value);
+  if (isNaN(num)) return 0;
+
+  switch (unit.toUpperCase()) {
+    case 'K': return Math.round(num * 1_000);
+    case 'M': return Math.round(num * 1_000_000);
+    case 'B': return Math.round(num * 1_000_000_000);
+    default:  return Math.round(num);
+  }
+}
+
+// ─── CLI Output Parser ──────────────────────────────────────────────────────
+
+/**
+ * Parse the raw multi-line output of `npx skills find <query>` into
+ * an array of structured skill records.
+ *
+ * Each record in the output spans two lines:
+ *   Line 1:  `owner/repo@skill <count>[K|M] installs`
+ *   Line 2:  `└ https://skills.sh/owner/repo/skill`
+ *
+ * @param {string} rawOutput - Raw stdout from `npx skills find`
+ * @returns {Array<{ name: string, installs: number, url: string }>}
+ *          Sorted by install count (highest first).
+ */
+export function parseFindOutput(rawOutput) {
+  const results = [];
+  const lines = rawOutput.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    // Match skill line:  "steipete/clawdis@github 1.7K installs"
+    //                    "jiulingyun/openclaw-cn@github 21 installs"
+    const skillMatch = line.match(
+      /^(\S+@\S+)\s+([\d.]+)\s*(K|M|B)?\s*installs?$/i
+    );
+
+    if (!skillMatch) continue;
+
+    const name = skillMatch[1];
+    const installs = parseInstalls(skillMatch[2], skillMatch[3] || '');
+
+    // Next non-empty line should be the URL (prefixed with └ or similar box-drawing chars)
+    let url = '';
+    for (let j = i + 1; j < lines.length; j++) {
+      const nextLine = lines[j].trim();
+      if (!nextLine) continue;
+
+      const urlMatch = nextLine.match(/^[└┗├│─\s]*(https?:\/\/\S+)/);
+      if (urlMatch) {
+        url = urlMatch[1];
+        i = j; // advance past the URL line
+      }
+      break; // only check the very next non-empty line
+    }
+
+    results.push({ name, installs, url });
+  }
+
+  return results;
+}
+
+// ─── Live Registry Search ───────────────────────────────────────────────────
+
+/**
+ * Execute `npx skills find <query>` and return parsed results.
+ * Falls back gracefully if the `skills` CLI is not installed.
+ *
+ * @param {string} query - Search term for the skills.sh registry
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs=15000] - Max execution time in ms
+ * @returns {Array<{ name: string, installs: number, url: string }>}
+ */
+export function searchRegistry(query, { timeoutMs = 15_000 } = {}) {
+  try {
+    const output = execSync(`npx -y skills find "${query.replace(/"/g, '\\"')}"`, {
+      timeout: timeoutMs,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return parseFindOutput(output);
+  } catch (err) {
+    // skills CLI not installed or network error — degrade gracefully
+    return [];
+  }
+}