agenticros 0.1.12 → 0.1.14

package/dist/util/skills.js

@@ -0,0 +1,361 @@
+/**
+ * Skill discovery, validation, and config-file mutation primitives.
+ *
+ * An AgenticROS skill is a Node package whose `package.json` carries
+ * `"agenticrosSkill": true` and exports a `registerSkill(api, config, context)`
+ * function from its `main` entry. The OpenClaw AgenticROS plugin loads them
+ * at gateway start by walking two arrays in its config:
+ *
+ *   - `skillPaths[]`     — absolute directories to scan (validate `package.json`)
+ *   - `skillPackages[]`  — npm-resolvable names (e.g. `agenticros-skill-find`)
+ *
+ * This module is the single place the CLI talks to those arrays. It also
+ * encapsulates discovery (where on disk users typically clone skill repos)
+ * and the `deriveSkillId` convention shared with `@agenticros/agenticros`'s
+ * skill-loader so menu / list output uses the same short ids the plugin
+ * surfaces (e.g. `followme`, `find`).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { getCliPaths } from "./paths.js";
+import { ensureStringArray, getAgenticrosPluginConfig, openclawConfigExists, openclawConfigPath, readOpenclawConfig, writeOpenclawConfig, } from "./openclaw-config.js";
+/**
+ * Apply the same short-id transform the OpenClaw plugin's skill-loader uses,
+ * so menu output and the plugin's `config.skills.<id>` keys line up exactly.
+ * `agenticros-skill-followme` → `followme`; scoped packages drop the scope.
+ */
+export function deriveSkillId(packageName) {
+    const lower = packageName.toLowerCase();
+    if (lower.startsWith("agenticros-skill-")) {
+        return lower.slice("agenticros-skill-".length);
+    }
+    return lower.replace(/^@[^/]+\//, "").replace(/[^a-z0-9]/g, "");
+}
+/**
+ * Inspect a directory and decide whether it's a valid AgenticROS skill clone.
+ * Returns a partial `SkillRef` (no `registeredAs`) or `undefined` when the
+ * directory is missing, lacks `package.json`, or doesn't opt in via the
+ * `agenticrosSkill: true` flag.
+ */
+export function inspectSkillDir(dir) {
+    const absDir = isAbsolute(dir) ? dir : resolve(dir);
+    if (!existsSync(absDir))
+        return undefined;
+    let stat;
+    try {
+        stat = statSync(absDir);
+    }
+    catch {
+        return undefined;
+    }
+    if (!stat.isDirectory())
+        return undefined;
+    const pkgPath = join(absDir, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (pkg.agenticrosSkill !== true)
+        return undefined;
+    const packageName = (pkg.name ?? "unknown").toString();
+    const mainRel = pkg.main ?? "index.js";
+    const entry = join(absDir, mainRel);
+    return {
+        id: deriveSkillId(packageName),
+        packageName,
+        dir: absDir,
+        entry,
+        built: existsSync(entry),
+    };
+}
+/**
+ * Return a deduped list of "places we should look for skill clones" — the
+ * directories whose children the CLI scans on `agenticros skills discover`.
+ *
+ * We include both the parent of the active repo / install dir (so siblings
+ * of `agenticros/` work, e.g. `../agenticros-skill-find`) and `$HOME` /
+ * `$HOME/Projects/` / `$HOME/Code/` so a vanilla clone-into-Projects flow
+ * is found without configuration.
+ */
+export function discoveryRoots(extra = []) {
+    const paths = getCliPaths();
+    const home = homedir();
+    const roots = [];
+    const push = (p) => {
+        if (!p)
+            return;
+        const abs = resolve(p);
+        if (!roots.includes(abs))
+            roots.push(abs);
+    };
+    if (paths.repoRoot)
+        push(dirname(paths.repoRoot));
+    push(dirname(paths.installDir));
+    push(home);
+    push(join(home, "Projects"));
+    push(join(home, "Code"));
+    push(join(home, "agenticros-skills"));
+    for (const e of extra)
+        push(e);
+    return roots.filter((r) => {
+        try {
+            return statSync(r).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Walk every directory in `roots`, returning a `SkillRef` for each child
+ * directory that passes `inspectSkillDir`. Used by both `discover` and
+ * `list` (which uses it to render orphaned-but-cloned skills).
+ */
+export function scanForSkills(extra = []) {
+    const out = [];
+    const seenDirs = new Set();
+    for (const root of discoveryRoots(extra)) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const child = join(root, name);
+            if (seenDirs.has(child))
+                continue;
+            seenDirs.add(child);
+            const info = inspectSkillDir(child);
+            if (info) {
+                out.push({ ...info, registeredAs: [] });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Pull skill arrays out of the OpenClaw config in a shape that's easy to
+ * mutate. The returned `paths` / `packages` arrays are filtered to strings
+ * (non-string elements are silently skipped in the view but preserved in
+ * the underlying arrays on disk).
+ */
+function loadOpenclawSkillsView() {
+    const cfg = readOpenclawConfig();
+    if (!cfg)
+        return undefined;
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const rawPaths = ensureStringArray(pluginCfg, "skillPaths");
+    const rawPkgs = ensureStringArray(pluginCfg, "skillPackages");
+    const paths = rawPaths.filter((x) => typeof x === "string");
+    const packages = rawPkgs.filter((x) => typeof x === "string");
+    return { cfg, pluginCfg, paths, packages };
+}
+/**
+ * Build a snapshot of the user's current skill state: what's registered,
+ * what's available-but-not-registered, and what registrations are broken.
+ * The single source of truth for the `agenticros skills` (list) view.
+ */
+export function listSkills() {
+    const view = loadOpenclawSkillsView();
+    const registered = [];
+    const brokenPaths = [];
+    const byId = new Map();
+    if (view) {
+        for (const p of view.paths) {
+            const info = inspectSkillDir(p);
+            if (info) {
+                const existing = byId.get(info.id);
+                if (existing) {
+                    if (!existing.registeredAs.includes("path"))
+                        existing.registeredAs.push("path");
+                    if (existing.entry === undefined) {
+                        existing.entry = info.entry;
+                        existing.built = info.built;
+                    }
+                }
+                else {
+                    const ref = { ...info, registeredAs: ["path"] };
+                    byId.set(info.id, ref);
+                    registered.push(ref);
+                }
+            }
+            else {
+                brokenPaths.push(p);
+            }
+        }
+        for (const name of view.packages) {
+            const id = deriveSkillId(name);
+            const existing = byId.get(id);
+            if (existing) {
+                if (!existing.registeredAs.includes("package"))
+                    existing.registeredAs.push("package");
+            }
+            else {
+                const ref = { id, packageName: name, registeredAs: ["package"] };
+                byId.set(id, ref);
+                registered.push(ref);
+            }
+        }
+    }
+    const available = scanForSkills().filter((s) => !byId.has(s.id));
+    return { registered, available, brokenPaths };
+}
+/**
+ * Add a skill to the OpenClaw plugin config by absolute directory path.
+ * Idempotent: re-adding an existing entry is a no-op and returns `ok: true`
+ * with an explanatory message. The directory must contain a valid
+ * `package.json` with `agenticrosSkill: true`.
+ */
+export function addSkillByPath(dir) {
+    const info = inspectSkillDir(dir);
+    if (!info) {
+        return {
+            ok: false,
+            message: `Not an AgenticROS skill directory: ${dir} (need package.json with "agenticrosSkill": true)`,
+        };
+    }
+    if (!openclawConfigExists()) {
+        return {
+            ok: false,
+            message: `OpenClaw config not found at ${openclawConfigPath()}. ` +
+                "Run `agenticros init` first to install the OpenClaw plugin.",
+        };
+    }
+    const cfg = readOpenclawConfig();
+    if (!cfg) {
+        return {
+            ok: false,
+            message: `Cannot parse OpenClaw config at ${openclawConfigPath()}.`,
+        };
+    }
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const paths = ensureStringArray(pluginCfg, "skillPaths");
+    if (paths.includes(info.dir)) {
+        return {
+            ok: true,
+            message: `Skill '${info.id}' already registered at ${info.dir}.`,
+            skill: { ...info, registeredAs: ["path"] },
+        };
+    }
+    paths.push(info.dir);
+    writeOpenclawConfig(cfg);
+    return {
+        ok: true,
+        message: `Registered skill '${info.id}' at ${info.dir} (${openclawConfigPath()} → skillPaths).`,
+        skill: { ...info, registeredAs: ["path"] },
+    };
+}
+/**
+ * Add a skill by npm package name (must be resolvable on the gateway's
+ * Node search path). Mainly intended for skills published to a registry —
+ * for local clones, prefer `addSkillByPath` so the absolute directory is
+ * recorded.
+ */
+export function addSkillByPackage(name) {
+    if (!openclawConfigExists()) {
+        return {
+            ok: false,
+            message: `OpenClaw config not found at ${openclawConfigPath()}. ` +
+                "Run `agenticros init` first to install the OpenClaw plugin.",
+        };
+    }
+    const cfg = readOpenclawConfig();
+    if (!cfg) {
+        return { ok: false, message: `Cannot parse OpenClaw config at ${openclawConfigPath()}.` };
+    }
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const packages = ensureStringArray(pluginCfg, "skillPackages");
+    if (packages.includes(name)) {
+        return {
+            ok: true,
+            message: `Skill package '${name}' already registered.`,
+            skill: { id: deriveSkillId(name), packageName: name, registeredAs: ["package"] },
+        };
+    }
+    packages.push(name);
+    writeOpenclawConfig(cfg);
+    return {
+        ok: true,
+        message: `Registered skill package '${name}' (${openclawConfigPath()} → skillPackages).`,
+        skill: { id: deriveSkillId(name), packageName: name, registeredAs: ["package"] },
+    };
+}
+/**
+ * Remove every registration that matches `idOrName` — either a derived skill
+ * id (e.g. `find`), a full package name (e.g. `agenticros-skill-find`), or an
+ * absolute path that appears in `skillPaths`. Both `skillPaths` (matched by
+ * resolving each path back through `inspectSkillDir`) and `skillPackages`
+ * are cleaned in a single pass.
+ */
+export function removeSkill(idOrName) {
+    const cfg = readOpenclawConfig();
+    if (!cfg) {
+        return {
+            ok: false,
+            message: `OpenClaw config not found or unparseable at ${openclawConfigPath()}.`,
+            removedPaths: [],
+            removedPackages: [],
+        };
+    }
+    const pluginCfg = getAgenticrosPluginConfig(cfg);
+    const rawPaths = ensureStringArray(pluginCfg, "skillPaths");
+    const rawPkgs = ensureStringArray(pluginCfg, "skillPackages");
+    const wanted = idOrName.trim();
+    const wantedAbs = isAbsolute(wanted) ? resolve(wanted) : undefined;
+    const removedPaths = [];
+    const keptPaths = rawPaths.filter((entry) => {
+        if (typeof entry !== "string")
+            return true;
+        if (wantedAbs && resolve(entry) === wantedAbs) {
+            removedPaths.push(entry);
+            return false;
+        }
+        const info = inspectSkillDir(entry);
+        if (info && (info.id === wanted || info.packageName === wanted)) {
+            removedPaths.push(entry);
+            return false;
+        }
+        return true;
+    });
+    const removedPackages = [];
+    const keptPkgs = rawPkgs.filter((entry) => {
+        if (typeof entry !== "string")
+            return true;
+        if (entry === wanted || deriveSkillId(entry) === wanted) {
+            removedPackages.push(entry);
+            return false;
+        }
+        return true;
+    });
+    if (removedPaths.length === 0 && removedPackages.length === 0) {
+        return {
+            ok: false,
+            message: `No registered skill matches '${idOrName}'.`,
+            removedPaths: [],
+            removedPackages: [],
+        };
+    }
+    pluginCfg["skillPaths"] = keptPaths;
+    pluginCfg["skillPackages"] = keptPkgs;
+    writeOpenclawConfig(cfg);
+    const parts = [];
+    if (removedPaths.length > 0)
+        parts.push(`${removedPaths.length} path(s)`);
+    if (removedPackages.length > 0)
+        parts.push(`${removedPackages.length} package(s)`);
+    return {
+        ok: true,
+        message: `Removed ${parts.join(" + ")} matching '${idOrName}' from ${openclawConfigPath()}.`,
+        removedPaths,
+        removedPackages,
+    };
+}
+//# sourceMappingURL=skills.js.map

package/dist/util/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/util/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticros",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "description": "AgenticROS - agentic AI for ROS-powered robots. Single CLI to launch real-robot or simulated demos, manage configuration, and inspect status.",
   "keywords": [

package/runtime/BUNDLE.json

@@ -1,5 +1,5 @@
 {
-  "packedAt": "2026-06-06T14:30:19.631Z",
+  "packedAt": "2026-06-08T20:06:42.131Z",
   "repo": "https://github.com/PlaiPin/agenticros",
   "note": "This directory is a snapshot of the agenticros monorepo source. `agenticros init` will copy it to ~/agenticros and run pnpm install + colcon build there.",
   "layout": {

package/runtime/README.md

@@ -56,34 +56,97 @@ Gemini CLI → @agenticros/gemini (function calling) → Core → ROS2 robots
 - `**docker/**` — Docker Compose and Dockerfiles for ROS2 + plugin images.
 - `**examples/**` — Example projects.
 
-## Requirements
+## Install
 
-- Node.js >= 20, pnpm >= 9
-- ROS2 (Jazzy or compatible) for building and running the ROS2 packages
-- OpenClaw gateway for the OpenClaw plugin
+You only need one command. The `agenticros` CLI handles everything else —
+installing the ROS 2 workspace, building the MCP server, registering the
+OpenClaw plugin, and wiring up your robot config.
 
-## Quick start
+```bash
+npx agenticros
+```
 
-1. **Install dependencies**
-  ```bash
-   pnpm install
-  ```
-2. **Build ROS2 workspace** (optional, if you need discovery/agent/follow_me nodes)
-  ```bash
-   cd ros2_ws
-   colcon build --packages-select agenticros_msgs agenticros_bringup agenticros_discovery agenticros_agent agenticros_follow_me
-   source install/setup.bash
-  ```
-3. **Type-check packages**
-  ```bash
-   pnpm typecheck
-  ```
-4. **Install and test the OpenClaw plugin**
-  Point the OpenClaw gateway at this repo’s `packages/agenticros` (or at a built package). Configure the plugin under `plugins.entries.agenticros.config` in your OpenClaw config file. Run `./scripts/setup_gateway_plugin.sh` from the repo root to register the plugin and print next steps. **Recommended:** OpenClaw **2026.3.11** or later — plugin routes work at [http://127.0.0.1:18789/plugins/agenticros/](http://127.0.0.1:18789/plugins/agenticros/) (config, teleop). For local dev without token auth, run `**node scripts/setup-openclaw-local.cjs`** then restart the gateway. **If URLs don't load** (e.g. gateway logs "missing or invalid auth" on older versions): run `**./scripts/use-openclaw-2026.2.26.sh`** as fallback. See **docs/openclaw-releases-and-plugin-routes.md**.
+That's it. Run it on any machine with **Node ≥ 20**, no `git clone` required.
+The first run launches the interactive menu:
+
+```text
+╔──────────────────────────────────────────────────╗
+║  AgenticROS - agentic AI for ROS-powered robots  ║
+╚──────────────────────────────────────────────────╝
+
+? What would you like to do?
+  Launch with real robot
+❯ Launch with simulation
+  First-time setup (workspace + OpenClaw plugin + API key)
+  Manage skills (2 registered, 0 available, 0 broken)
+  Stop everything
+  Doctor (health check)
+  Configure (API keys, namespace, transport)
+  Tail logs
+```
+
+Pick **First-time setup** once (workspace + OpenClaw plugin + API key, all
+idempotent), then choose how you want to run:
+
+| You want to … | Pick |
+|---|---|
+| Drive your **real robot** (RealSense + motors + MCP) | **Launch with real robot** |
+| Demo a **simulated 2-wheel AMR** in Gazebo + RViz | **Launch with simulation → AMR** |
+| Demo a **simulated 6-DOF arm** (UR5e-shaped, per-joint position control) | **Launch with simulation → 6-DOF arm** |
+
+Once a stack is up, point any of the supported agents — OpenClaw, Claude Code,
+Claude Desktop / Dispatch, or Gemini CLI — at the same robot and start talking
+to it. The CLI tracks what it spawned (pidfiles + logs under `/tmp/agenticros-*`),
+so **Stop everything** cleanly tears the demo down.
+
+Prefer scripted invocations? Every menu item maps to a direct command:
+
+```bash
+npx agenticros init             # one-time workspace + plugin + API key
+agenticros up real              # real robot stack
+agenticros up sim-amr           # simulated AMR (Gazebo + RViz, headless on Jetson)
+agenticros up sim-arm           # simulated 6-DOF arm
+agenticros mode <real|sim>      # swap the active config profile (namespace, transport)
+agenticros skills               # list / add / remove AgenticROS skills (see below)
+agenticros doctor               # coloured health check
+agenticros down                 # stop everything we started
+```
+
+Full CLI reference: **[packages/agenticros-cli/README.md](packages/agenticros-cli/README.md)**.
+
+### Requirements
+
+- **Node.js ≥ 20** (the only hard requirement — `npx agenticros` installs pnpm
+  itself if missing)
+- **ROS 2 Humble or Jazzy** if you plan to use the real-robot stack or any
+  simulation (the CLI sources `/opt/ros/<distro>/setup.bash` and runs
+  `colcon build` for you)
+- **OpenClaw gateway** only if you also want the OpenClaw web UI / chat /
+  teleop adapter
+
+### Contributing / building from source
+
+Hacking on the packages themselves? Clone and use the local checkout — the CLI
+auto-detects the workspace and uses live sources instead of the bundled snapshot:
 
-**With token auth:** Run `node scripts/agenticros-proxy.cjs 18790` and open [http://127.0.0.1:18790/plugins/agenticros/](http://127.0.0.1:18790/plugins/agenticros/). See **docs/teleop.md**.
+```bash
+git clone https://github.com/PlaiPin/agenticros && cd agenticros
+pnpm install && pnpm build
+./agenticros                    # repo-local CLI shim, same menu as `npx agenticros`
+```
 
-See `**docs/`** for robot setup, skills, teleop, and Docker.
+For the OpenClaw plugin specifically, point the gateway at this repo's
+`packages/agenticros` and configure under `plugins.entries.agenticros.config`.
+**Recommended:** OpenClaw **2026.3.11+** — routes work at
+[http://127.0.0.1:18789/plugins/agenticros/](http://127.0.0.1:18789/plugins/agenticros/)
+(config, teleop). For local dev without token auth:
+`node scripts/setup-openclaw-local.cjs` then restart the gateway. Older gateways
+needing token auth: run `node scripts/agenticros-proxy.cjs 18790` and open
+[http://127.0.0.1:18790/plugins/agenticros/](http://127.0.0.1:18790/plugins/agenticros/).
+See **[docs/openclaw-releases-and-plugin-routes.md](docs/openclaw-releases-and-plugin-routes.md)**
+and **[docs/teleop.md](docs/teleop.md)**.
+
+See **`docs/`** for robot setup, skills, teleop, simulation internals, and Docker.
 
 ## RViz2 and Gazebo (TurtleBot3 + rosbridge)
 
@@ -259,14 +322,67 @@ Add `{ "memory": { "enabled": true, "backend": "mem0" } }` to `~/.agenticros/con
 
 ## Skills
 
-AgenticROS **skills** are optional packages that add tools and behaviors to the plugin. They are loaded at gateway start.
+AgenticROS **skills** are optional packages that add tools and behaviors to the plugin (e.g. `follow_robot`, `find_object`). They are loaded at OpenClaw gateway start. **[AgenticROS Skills](https://github.com/agenticros/agenticros-skills)** is a curated list — use it to discover skills for your robot and to submit your own.
+
+### Managing skills with the CLI
+
+The `agenticros skills` command (and the **Manage skills** menu entry) does everything for you: it scans the usual locations for clones, edits `~/.openclaw/openclaw.json`, refreshes the plugin manifest's `contracts.tools` allowlist, and reminds you to bounce the gateway.
+
+```bash
+agenticros skills                       # list registered + cloned-but-unregistered
+agenticros skills discover              # interactive picker over candidates on disk
+agenticros skills add <path-or-name>    # register a clone (path) or npm package
+agenticros skills remove <id-or-name>   # unregister
+agenticros skills sync                  # refresh OpenClaw contracts.tools allowlist
+```
+
+A typical first-run looks like:
+
+```bash
+# clone whichever skills you want, anywhere near the repo
+cd ~/Projects
+git clone https://github.com/agenticros/agenticros-skill-followme
+git clone https://github.com/agenticros/agenticros-skill-find
+
+# build them (skills compile independently of the main workspace)
+cd agenticros-skill-followme && pnpm install && pnpm build && cd ..
+cd agenticros-skill-find     && pnpm install && pnpm build && cd ..
+
+# register both — short ids resolve against the discovered clones
+agenticros skills add followme
+agenticros skills add find
+agenticros skills sync                  # update contracts.tools
+systemctl --user restart openclaw-gateway.service
+```
+
+`agenticros skills` then shows them as registered, and `agenticros doctor` includes a skills health-check that flags any clone that hasn't been built or whose `skillPaths` entry no longer exists.
+
+Listing output:
+
+```text
+╔─────────────────────╗
+║  AgenticROS skills  ║
+╚─────────────────────╝
+
+› OpenClaw config: /home/you/.openclaw/openclaw.json
+
+Registered:
+  ● followme  agenticros-skill-followme
+      via path  →  /home/you/Projects/agenticros-skill-followme
+  ● find      agenticros-skill-find
+      via path  →  /home/you/Projects/agenticros-skill-find
+```
+
+### What the CLI writes
+
+- `~/.openclaw/openclaw.json` → `plugins.entries.agenticros.config.skillPaths[]` and `.skillPackages[]` (the only place the plugin actually reads from at gateway start).
+- `packages/agenticros/openclaw.plugin.json` → `contracts.tools` allowlist via `scripts/sync-skill-tools.mjs`. Required on OpenClaw **2026+**, which silently drops any tool a plugin registers but hasn't declared.
+
+Per-skill behaviour lives under `config.skills.<skillId>` (e.g. `config.skills.followme.depthTopic`). The CLI doesn't auto-write these — use `agenticros config set skills.find.confidence=0.5` or edit `~/.openclaw/openclaw.json` directly. See each skill's README for its options.
 
-**[AgenticROS Skills](https://github.com/agenticros/agenticros-skills)** is a curated list of skills — use it to discover skills for your robot and to submit your own via pull request.
+### Contract & writing your own skill
 
-- **Install**: In the OpenClaw config file, under `plugins.entries.agenticros.config`, set `**skillPackages`** (e.g. `["agenticros-skill-followme"]`) and ensure the package is installed where the gateway runs, or set `**skillPaths`** to directories containing skill packages. Restart the gateway after changes.
-- **Config**: Each skill reads its options from `**config.skills.<skillId>`** (e.g. `config.skills.followme`).
-- **Contract and creating a skill**: See **[docs/skills.md](docs/skills.md)** for the full contract, install steps, and how to build a third-party skill.
-- **Reference skill**: **[agenticros-skill-followme](https://github.com/your-org/agenticros-skill-followme)** — Follow Me (depth + optional Ollama), with tools `follow_robot`, `follow_me_see`, and `ollama_status`. Use its README as a template for new skills.
+A skill is a Node package with `"agenticrosSkill": true` in `package.json` and a `registerSkill(api, config, context)` export from `main`. See **[docs/skills.md](docs/skills.md)** for the full contract and **[agenticros-skill-followme](https://github.com/your-org/agenticros-skill-followme)** as a reference template.
 
 ## License
 

package/runtime/packages/agenticros/openclaw.plugin.json

@@ -23,7 +23,8 @@
       "memory_status",
       "follow_robot",
       "follow_me_see",
-      "ollama_status"
+      "ollama_status",
+      "find_object"
     ]
   },
   "configSchema": {
@@ -311,7 +312,10 @@
           },
           "backend": {
             "type": "string",
-            "enum": ["local", "mem0"],
+            "enum": [
+              "local",
+              "mem0"
+            ],
             "default": "local",
             "description": "local = JSON-on-disk, no deps; mem0 = semantic search via mem0ai (requires `pnpm add mem0ai`)."
           },