@lincoln504/pi-research 1.5.2 → 1.5.3

package/README.md

@@ -37,7 +37,7 @@ As a [Pi](https://github.com/earendil-works/pi) Coding Agent extension:
 pi install npm:@lincoln504/pi-research
 ```
 
-Standalone, as an [agent skill](docs/AGENT-SKILL.md) for Claude Code, Codex, and OpenClaw:
+Standalone, as an [agent skill](docs/AGENT-SKILL.md) for Claude Code, Codex, and other skills-compatible agents:
 
 ```bash
 npm install -g @lincoln504/pi-research
@@ -57,7 +57,7 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 ### Use cases
 
 - Researching for your pi. Plug and play with no API key needed.
-- Researching from Claude Code, Codex, OpenClaw, or another coding agent while a cheaper or local model drives the run so it doesn't spend your main agent's budget.
+- Researching from Claude Code, Codex, or another coding agent while a cheaper or local model drives the run so it doesn't spend your main agent's budget.
 - Keeping a persistent and searchable knowledge store of findings, scoped globally or per project.
 - Building agent systems that find and read web content or populating a dataset of web sources.
 

package/{skills → agent-skill}/pi-research/README.md

@@ -3,8 +3,8 @@
 A portable [Agent Skill](https://agentskills.io/specification) that gives any
 coding agent multi-agent web research by driving the
 [pi-research](https://github.com/Lincoln504/pi-research) engine. It is the same
-engine the `pi` extension uses, packaged as a skill so Claude, Cursor,
-Codex, OpenClaw, and other Agent-Skills-compatible tools can use it.
+engine the `pi` extension uses, packaged as a skill so Claude, Codex, and other
+Agent-Skills-compatible tools can use it.
 
 ### What it exposes
 
@@ -50,9 +50,9 @@ node "<skill_dir>/scripts/run.mjs" status  # verify detection
 ### Install the skill
 
 Recommended. From the pi extension, run `/research-config` and choose
-Install in External Agents. It detects Claude, Codex, and OpenClaw and
-symlinks this skill into each one that is installed. Remove from External Agents
-removes those symlinks.
+Install in External Agents. It detects the supported agents set up on this machine
+and symlinks this skill into each one. Remove from External Agents removes those
+symlinks.
 
 Uninstalling the npm package does **not** remove them: npm 7 and newer do not run a
 package's own `preuninstall` script (verified against npm 11). Use Remove from
@@ -60,9 +60,6 @@ External Agents first, or run `node scripts/cleanup.cjs` from the package direct
 otherwise the symlinks, `~/.pi/research/state` and the `~/.cache/pi-research` model
 cache are all left behind.
 
-Cursor is not auto-installed — it has no global skills directory and only reads
-project-level `.cursor/skills/`. Symlink it per-project instead (see the table).
-
 Manual. Or symlink this `pi-research/` directory into your agent's skills folder:
 
 | Agent | Location |
@@ -71,7 +68,6 @@ Manual. Or symlink this `pi-research/` directory into your agent's skills folder
 | Claude (project)   | `<project>/.claude/skills/pi-research/` |
 | Codex CLI (personal) | `~/.codex/skills/pi-research/` |
 | Codex CLI (project)  | `<project>/.codex/skills/pi-research/` |
-| Cursor (project-only) | `<project>/.cursor/skills/pi-research/` |
 | OpenClaw (personal) | `~/.openclaw/skills/pi-research/` |
 
 Then ask your agent to pi-research something — its skill system matches the

package/{skills → agent-skill}/pi-research/SKILL.md

@@ -2,15 +2,16 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.5.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.5.3", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 
 # pi-research skill
 
-Run via your shell tool — the **Bash** tool in Claude Code, the **`exec`** tool in
-OpenClaw. `<SKILL_DIR>` is this skill's own directory: substitute the absolute path
-your harness reports for this skill (in OpenClaw, `{baseDir}` resolves to it).
+Run via your shell tool — the **Bash** tool in Claude Code, whatever equivalent
+your harness exposes elsewhere. `<SKILL_DIR>` is this skill's own directory:
+substitute the absolute path your harness reports for this skill (some harnesses
+expose it as `{baseDir}`).
 
 ```
 node "<SKILL_DIR>/scripts/run.mjs" research  "<query>" --depth 1

package/{skills → agent-skill}/pi-research/scripts/run.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// skills/pi-research/scripts/run.ts
+// agent-skill/pi-research/scripts/run.ts
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, constants as osConstants } from "node:os";

package/dist/cli.mjs

@@ -10157,7 +10157,8 @@ function resolveSkillSourceDir(explicit) {
     if (!start) continue;
     let dir = start;
     for (let i = 0; i < 8; i++) {
-      candidates.push(path18.join(dir, "skills", SKILL_NAME));
+      candidates.push(path18.join(dir, SKILL_SOURCE_DIR, SKILL_NAME));
+      candidates.push(path18.join(dir, LEGACY_SKILL_SOURCE_DIR, SKILL_NAME));
       const parent = path18.dirname(dir);
       if (parent === dir) break;
       dir = parent;
@@ -10169,7 +10170,7 @@ function resolveSkillSourceDir(explicit) {
     } catch {
     }
   }
-  throw new Error("Could not locate the bundled research skill (skills/pi-research/SKILL.md). Set PI_RESEARCH_SKILL_DIR to its path.");
+  throw new Error("Could not locate the bundled research skill (agent-skill/pi-research/SKILL.md). Set PI_RESEARCH_SKILL_DIR to its path.");
 }
 function getManifestPath(opts) {
   return path18.join(homeDir(opts), ".pi", "research", "installed-skills.json");
@@ -10213,7 +10214,7 @@ function isOwnedSymlink(targetPath, expectedSource) {
     if (!st.isSymbolicLink()) return false;
     const dest = path18.resolve(path18.dirname(targetPath), fs16.readlinkSync(targetPath));
     if (expectedSource && path18.resolve(expectedSource) === dest) return true;
-    return /[/\\]pi-research[/\\]skills[/\\]pi-research$/.test(dest);
+    return OWNED_SYMLINK_DEST.test(dest);
   } catch {
     return false;
   }
@@ -10564,20 +10565,28 @@ function copyDir(src, dest) {
     fs16.copyFileSync(src, dest);
   }
 }
-var HARNESSES, SKILL_NAME, PACKAGE_NAME, SKILL_AGENT_TARGETS, manifestTmpSeq, isTarget;
+var HARNESSES, SKILL_NAME, PACKAGE_NAME, SKILL_SOURCE_DIR, LEGACY_SKILL_SOURCE_DIR, OWNED_SYMLINK_DEST, SKILL_AGENT_TARGETS, manifestTmpSeq, isTarget;
 var init_skill_installer = __esm({
   "src/skill-install/skill-installer.ts"() {
     "use strict";
     HARNESSES = [
       { id: "claude", label: "Claude", baseDir: ".claude", skillsDir: path18.join(".claude", "skills"), confidence: "confirmed" },
       { id: "openclaw", label: "OpenClaw", baseDir: ".openclaw", skillsDir: path18.join(".openclaw", "skills"), confidence: "confirmed", note: "OpenClaw reads ~/.openclaw/skills as a managed skill root and accepts symlinked skill folders (docs.openclaw.ai/tools/skills)." },
-      { id: "pi", label: "pi", baseDir: ".pi", skillsDir: path18.join(".pi", "skills"), confidence: "confirmed" },
-      { id: "cursor", label: "Cursor", baseDir: ".cursor", skillsDir: path18.join(".cursor", "skills"), confidence: "partial", note: "Cursor project-level skills are documented; the global ~/.cursor/skills path is community-reported." },
+      // pi's own skill root is under its agent dir (~/.pi/agent/skills), NOT ~/.pi/skills.
+      // Listed for DETECTION only — pi is never an install target (see SKILL_AGENT_TARGETS):
+      // the host already exposes research as a native tool, so a skill there would just
+      // duplicate it through a slower subprocess.
+      { id: "pi", label: "pi", baseDir: ".pi", skillsDir: path18.join(".pi", "agent", "skills"), confidence: "confirmed" },
       { id: "codex", label: "OpenAI Codex CLI", baseDir: ".codex", skillsDir: path18.join(".codex", "skills"), confidence: "unverified", note: "Codex skills support is emerging; path not confirmed by official docs." },
       { id: "agents", label: "Cross-tool (~/.agents/skills)", baseDir: ".agents", skillsDir: path18.join(".agents", "skills"), confidence: "unverified", note: "Proposed Universal Agents convention; not yet a ratified standard." }
     ];
     SKILL_NAME = "pi-research";
     PACKAGE_NAME = "@lincoln504/pi-research";
+    SKILL_SOURCE_DIR = "agent-skill";
+    LEGACY_SKILL_SOURCE_DIR = "skills";
+    OWNED_SYMLINK_DEST = new RegExp(
+      `[/\\\\]${SKILL_NAME}[/\\\\](?:${SKILL_SOURCE_DIR}|${LEGACY_SKILL_SOURCE_DIR})[/\\\\]${SKILL_NAME}$`
+    );
     SKILL_AGENT_TARGETS = ["claude", "codex", "openclaw"];
     manifestTmpSeq = 0;
     isTarget = (id) => SKILL_AGENT_TARGETS.includes(id);

package/docs/AGENT-SKILL.md

@@ -1,9 +1,9 @@
 ## Agent Skill
 
 pi-research ships as a portable [Agent Skill](https://agentskills.io/specification)
-so any skills-compatible coding agent (Claude, OpenAI Codex CLI, OpenClaw, and
-others using the same `SKILL.md` directory model) can run web research through the
-pi-research software.
+so any skills-compatible coding agent using the same `SKILL.md` directory model —
+Claude, OpenAI Codex CLI and others — can run web research through the pi-research
+software.
 
 ### Install
 
@@ -18,7 +18,7 @@ every coding agent detected on this machine:
 
 ```bash
 npm install -g @lincoln504/pi-research   # the engine (puts `pi-research` on PATH)
-pi-research skill install                # link the skill into Claude, Codex, OpenClaw
+pi-research skill install                # link the skill into every detected agent
 ```
 
 `skill install` targets only agents already set up under `$HOME`, never overwrites a
@@ -49,7 +49,7 @@ disabled"); or run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
 agent
   │  shells out (Bash / exec)
   ▼
-run.mjs  —  zero-dep launcher (skills/pi-research/scripts/)
+run.mjs  —  zero-dep launcher (agent-skill/pi-research/scripts/)
   │  locates the installed engine, or fails fast with guidance
   ▼
 pi-research engine  —  the CLI (dist/cli.mjs)
@@ -70,19 +70,23 @@ is missing. It exposes four subcommands: `research "<query>"` (live research),
 
 ### Installation flow
 
-The skill source lives at `skills/pi-research/` inside the package. Installing means
-linking that directory into each agent's skills folder.
+The skill source lives at `agent-skill/pi-research/` inside the package. Installing
+means linking that directory into each agent's skills folder.
+
+> The directory is deliberately **not** named `skills/`: `pi` treats a package-root
+> `skills/` directory as one of its own resource roots and will load what it finds
+> there, which would shadow the extension's native research tool with a slower
+> subprocess copy of itself.
 
 One-click (recommended). From the `pi` extension, run `/research-config` →
 Install in External Agents. The installer:
 
 1. Detects which target agents are present under `$HOME` — currently Claude
-   (`~/.claude/skills`), OpenClaw (`~/.openclaw/skills`, OpenClaw's managed
-   skill root, which accepts symlinked skill folders), and OpenAI Codex CLI
-   (`~/.codex/skills` — unlike the other two, this path is not confirmed by
-   Codex's official docs; Codex skills support is still emerging).
-2. Symlinks `skills/pi-research/` into each present agent, never overwriting an
-   unrelated skill already in that slot.
+   (`~/.claude/skills`), OpenAI Codex CLI (`~/.codex/skills` — this path is not
+   confirmed by Codex's official docs; Codex skills support is still emerging)
+   and OpenClaw (`~/.openclaw/skills`).
+2. Symlinks `agent-skill/pi-research/` into each present agent, never overwriting
+   an unrelated skill already in that slot.
 3. Records what it created in a manifest, so Remove from External Agents
    removes only its own links. Stale links are also garbage-collected on startup.
 
@@ -99,29 +103,12 @@ do exactly the same from the CLI — same agent detection, same manifest, same
 never-clobber-a-foreign-skill guarantee — for people who installed the engine with
 `npm install -g` and never open the interactive extension.
 
-**OpenClaw without `pi`**
-
-If you run OpenClaw but not the `pi` extension, register the skill with OpenClaw's
-own CLI after installing the engine — OpenClaw copies the `SKILL.md` folder into its
-managed skill root and reads it on the next session:
-
-```bash
-npm install -g @lincoln504/pi-research
-openclaw skills install "$(npm root -g)/@lincoln504/pi-research/skills/pi-research" --global
-```
-
-OpenClaw drives the skill through its `exec` tool, gated on `node` being on `PATH`
-(`metadata.openclaw.requires.bins`). A bare `openclaw skills install git:…` is *not*
-used here: OpenClaw expects `SKILL.md` at a repo root, whereas this package nests it
-under `skills/pi-research/` — install the engine from npm and point OpenClaw at that
-folder, as above.
-
-Cursor is intentionally excluded from the one-click flow — it has no global skills
-directory and reads only project-level `.cursor/skills/`. Link it per project:
-
-```bash
-ln -s "$(npm root -g)/@lincoln504/pi-research/skills/pi-research" .cursor/skills/pi-research
-```
+An agent with its own skill-registration CLI can be pointed at the shipped folder
+instead of symlinking it. Install the engine, then register
+`$(npm root -g)/@lincoln504/pi-research/agent-skill/pi-research` with that agent —
+it holds `SKILL.md` at its root, which is the layout such tools expect. Agents that
+copy rather than link pick up engine upgrades on the next `skill install`, not
+automatically.
 
 Manual. Symlink the directory into any agent's skills folder yourself:
 
@@ -130,7 +117,6 @@ Manual. Symlink the directory into any agent's skills folder yourself:
 | Claude | `~/.claude/skills/pi-research/` | `<project>/.claude/skills/pi-research/` |
 | OpenAI Codex CLI | `~/.codex/skills/pi-research/` | `<project>/.codex/skills/pi-research/` |
 | OpenClaw | `~/.openclaw/skills/pi-research/` | `<workspace>/skills/pi-research/` |
-| Cursor | — (no global dir) | `<project>/.cursor/skills/pi-research/` |
 
 ### Prerequisites
 
@@ -146,6 +132,6 @@ node "<skill_dir>/scripts/run.mjs" status   # verify the engine is detected
 ![One-command health and readiness check](https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/06-health-check.gif)
 
 Once installed, ask the agent to research something — its skill system activates
-pi-research automatically. The in-package readme (`skills/pi-research/README.md`) and
-`skills/pi-research/references/configuration.md` carry the same detail for anyone
-browsing the skill directly.
+pi-research automatically. The in-package readme (`agent-skill/pi-research/README.md`)
+and `agent-skill/pi-research/references/configuration.md` carry the same detail for
+anyone browsing the skill directly.

package/docs/ARCHITECTURE.md

@@ -4,7 +4,7 @@ pi-research is a pi TUI extension for multi-agent web research. It runs inside t
 process, registers its tools and commands, and manages its own browser worker pool,
 service registry, and local knowledge store. One engine backs every front-end: besides
 the pi extension it is exposed as a standalone CLI, a portable agent skill (the same
-skill any skills-aware host runs, including OpenClaw) and a programmatic SDK
+skill any skills-aware host runs) and a programmatic SDK
 (`src/sdk.ts`).
 
 ```

package/docs/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.3] - 2026-08-22
+
+### Fixed
+
+- **The shipped agent skill moved from `skills/` to `agent-skill/` inside the package, so `pi` can no longer load it as one of its own agent skills.** `pi` reserves four package-root resource directory names (`extensions`, `skills`, `prompts`, `themes`) and convention-scans any of them a package's `pi` manifest does not explicitly declare. This package declares `extensions` only, so its root-level `skills/` was scanned and `SKILL.md` registered as a pi agent skill — a slower subprocess duplicate of the extension's own native `research` tool, plus a redundant `/skill:pi-research` command. Nothing fired on a plain install, a plain update, or `npm install`ing the package into a project (pi never scans project `node_modules`, and a settings entry written as a plain string takes the manifest-only path). The trap was `pi config`: toggling **any** pi-research resource rewrites the settings entry from a string into an object, after which pi resolves each resource type separately and falls back to the convention scan for the undeclared `skills` — permanently, since the TUI's revert-to-string branch is unreachable, and irrespective of whether the toggle *enabled* or *disabled* the extension. Renaming the directory removes the scanned path entirely, which needs no `pi.skills` manifest key and so cannot mislabel the package as a skill provider in the pi.dev gallery (`agent-skill/`, `package.json`).
+- **Ownership detection now recognises both the current and the pre-1.5.3 skill source directories, so existing installs survive the move.** Installed links are symlinks into the package, and three of the four ownership call sites pass no expected source — they match the link destination's shape instead. Accepting only the new name would have stranded every link created before this release (reconcile refusing to re-point it, uninstall refusing to remove it, `skill status` reporting a foreign skill); accepting only the legacy name would have made each link unmanageable the moment it was successfully re-pointed, a failure that looks like a clean migration until the *next* upgrade. `reconcileSkillInstalls` runs on every CLI invocation and every extension activation, so a pre-1.5.3 link is re-pointed automatically with no user action. Both failure directions are pinned by a new regression suite, and the false-positive guard for lookalike paths (`…/pi-researcher/…`) is retained (`src/skill-install/skill-installer.ts`, `scripts/cleanup.cjs`, `test/unit/skill-install/legacy-source-dir-migration.test.ts`).
+- The installer's `pi` harness entry pointed at `~/.pi/skills`, but pi's skill root is `~/.pi/agent/skills` — the entry had never matched anything. Corrected to the real path. It remains detection-only and is deliberately not an install target: pi already exposes research natively, so a skill there would only add a slower duplicate (`src/skill-install/skill-installer.ts`).
+
+### Changed
+
+- **Cursor is no longer documented or defined as a harness.** It was never an install target — it exposes no personal/global skills directory, so the one-click flow could not serve it — and its only presence was manual per-project symlink instructions plus an unused entry in the harness table. Nothing installed to it, so there is no behavioural change (`src/skill-install/skill-installer.ts`, `docs/AGENT-SKILL.md`, `agent-skill/pi-research/README.md`).
+- **OpenClaw is de-emphasised throughout the documentation**, becoming one supported agent among others rather than a separately-branded integration: its dedicated install section, per-harness prose and README callouts are gone, and it now appears only where the supported-agent set is enumerated factually. Support is unchanged — it remains a first-class install target with its `SKILL.md` preflight metadata intact, and existing installs are untouched. (Removing it from the target list was considered and rejected: uninstall and status are both target-filtered, so a formerly-supported harness would have become permanently unremovable through any user-facing command while reconcile kept maintaining the orphan.) The generic copy-install route it used is still documented, without naming a specific agent (`README.md`, `docs/`, `agent-skill/pi-research/`).
+- **npm `keywords` trimmed from 25 to 13**, dropping the entries that blurred what pi actually loads from this package (`skills`, `agent-skills`, plus generic SEO filler: `ai-research`, `research`, `scraping`, `browser-automation`, `stealth-browser`, `camoufox`, `duckduckgo`, `llm-tools`, `web-access`, `agent`). Retained: the pi-ecosystem flags (`pi`, `pi-package` — load-bearing for pi.dev gallery inclusion — `pi-extension`, `pi-coding-agent`), the harnesses the standalone skill genuinely targets (`agent-skill`, `claude-code`, `codex`, `openclaw`), and the core function words (`web-research`, `deep-research`, `web-search`, `web-scraping`, `knowledge-store`). Cosmetic only: pi never reads npm keywords — resource loading is driven entirely by the `pi` manifest keys, and the pi.dev type chips derive from those same keys (`package.json`).
+
 ## [1.5.2] - 2026-08-22
 
 ### Fixed

package/docs/CONFIGURATION.md

@@ -1,6 +1,6 @@
 ## Configuration
 
-Every front-end (the pi extension, the standalone CLI / agent skill that OpenClaw
+Every front-end (the pi extension, the standalone CLI / agent skill that Claude Code
 and other skills-aware hosts run, and the SDK) shares one configuration
 model. This document covers the
 settings exposed in the `/research-config` TUI first, then the complete
@@ -159,7 +159,7 @@ Diagnostics & platform
 | `CAMOUFOX_INSTALL_DIR` | _(user cache)_ | camoufox-js's own variable, and the only one that can relocate the browser. Sets where pi-research looks the binary up, and is exported to the postinstall fetch and to browser workers. **Not effective on the currently pinned camoufox-js (0.10.x), which hardcodes its cache directory and honours no variable** — so relocating the browser is unsupported until that pin can advance (see ARCHITECTURE.md). |
 | `PLAYWRIGHT_BROWSERS_PATH` | _(user cache)_ | Alias for the above, accepted for compatibility and exported onward as `CAMOUFOX_INSTALL_DIR`. Same caveat: on the pinned camoufox-js it moves only where pi-research looks, not where the download lands, so setting it reports the browser missing from the custom path after a successful install. |
 | `XDG_CACHE_HOME` | `~/.cache` | Standard XDG variable. When set, every `~/.cache/pi-research/...` path below is rooted at `$XDG_CACHE_HOME/pi-research/...` instead. |
-| `PI_RESEARCH_BIN` (alias `PI_RESEARCH_PATH`) | _(auto)_ | Agent-skill launcher only: explicit path to the pi-research engine binary when auto-resolution (PATH → local install → npx) should be bypassed. See [skills/pi-research/references/configuration.md](../skills/pi-research/references/configuration.md). |
+| `PI_RESEARCH_BIN` (alias `PI_RESEARCH_PATH`) | _(auto)_ | Agent-skill launcher only: explicit path to the pi-research engine binary when auto-resolution (PATH → local install → npx) should be bypassed. See [agent-skill/pi-research/references/configuration.md](../agent-skill/pi-research/references/configuration.md). |
 | `PLAYWRIGHT_INSTALL_DEPS` | _(unset)_ | Linux only. Set `true` during `npm install` to also install system libraries via `npx playwright install-deps` (same as `npm run install:system-deps`). |
 | `PI_RESEARCH_STRICT_SETUP` | _(unset)_ | Read by the bundled `scripts/setup.cjs` during `npm install`. Set `1`/`true` to make a failed browser download fail the install instead of deferring it to first use. |
 | `PI_RESEARCH_CONFIG_DIR_NAME` | `.pi` | Override the host config-directory name under your home dir (advanced; e.g. set to share another harness's config root). |
@@ -196,8 +196,8 @@ layered over the shared base, so they can be configured independently. Exactly t
 exist:
 
 - `~/.pi/research/pi.env` — the pi extension
-- `~/.pi/research/cli.env` — the standalone CLI / agent skill (the surface OpenClaw
-  and other skills-aware hosts run)
+- `~/.pi/research/cli.env` — the standalone CLI / agent skill (the surface
+  skills-aware hosts run)
 
 The overlay files do not exist by default; create the one you need by hand. There is
 intentionally no `sdk.env`: the SDK is a library configured from code (see

package/docs/PI-EXTENSION.md

@@ -78,7 +78,7 @@ environment-variable list live in [CONFIGURATION.md](CONFIGURATION.md).
 ### Coding-agent skill installer
 
 The `/research-config` menu can install the `pi-research` skill into your other
-coding agents (Claude, Codex, OpenClaw) so they can run web research through the
+coding agents detected on this machine so they can run web research through the
 CLI, and remove it again — with exact, manifest-tracked cleanup. See
 [AGENT-SKILL.md](AGENT-SKILL.md) for the full installation flow.
 

package/docs/SDK.md

@@ -141,7 +141,7 @@ exit code is the part you can rely on.
 
 Treat any code ≥ 128 as a cancellation; `pi-research --help` lists the full set, and
 the agent-facing contract is the exit-code table in
-[`SKILL.md`](../skills/pi-research/SKILL.md).
+[`SKILL.md`](../agent-skill/pi-research/SKILL.md).
 
 These are deliberately not the `70` runtime-error code and never carry
 `retryable: true` — a cancel is a completed intention, not a fault to retry. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -20,8 +20,8 @@
     "dist/thread-worker.mjs",
     "dist/webgpu-probe.mjs",
     "dist/prompts/",
-    "skills/",
-    "!skills/pi-research/scripts/run.ts",
+    "agent-skill/",
+    "!agent-skill/pi-research/scripts/run.ts",
     "!src/.env",
     "!src/.env.local",
     "!src/.env.*.local",
@@ -53,27 +53,15 @@
     "pi-package",
     "pi-extension",
     "pi-coding-agent",
+    "agent-skill",
     "claude-code",
-    "openclaw",
     "codex",
-    "agent-skills",
-    "agent-skill",
-    "skills",
-    "web-search",
+    "openclaw",
     "web-research",
     "deep-research",
-    "ai-research",
-    "research",
+    "web-search",
     "web-scraping",
-    "scraping",
-    "browser-automation",
-    "stealth-browser",
-    "camoufox",
-    "duckduckgo",
-    "knowledge-store",
-    "llm-tools",
-    "web-access",
-    "agent"
+    "knowledge-store"
   ],
   "author": "Lincoln Deen",
   "contributors": [
@@ -105,7 +93,7 @@
     "build": "node scripts/build.cjs all",
     "prepublishOnly": "node scripts/build.cjs all && node scripts/verify-package.cjs manifest",
     "prepare": "node scripts/prepare.cjs",
-    "version": "node scripts/sync-skill-version.cjs && git add skills/pi-research/SKILL.md",
+    "version": "node scripts/sync-skill-version.cjs && git add agent-skill/pi-research/SKILL.md",
     "postinstall": "node scripts/setup.cjs",
     "preuninstall": "node scripts/cleanup.cjs",
     "cleanup": "node scripts/cleanup.cjs",

package/scripts/build.cjs

@@ -12,7 +12,7 @@
  * Targets (dispatch by argv, or build all when no/`all` arg):
  *   worker   -> src/infrastructure/browser/thread-worker.mjs  (browser worker)
  *   cli      -> dist/cli.mjs (+ dist/prompts, dist/thread-worker.mjs, dist/webgpu-probe.mjs)
- *   skill    -> skills/pi-research/scripts/run.mjs  (skill launcher, shebang)
+ *   skill    -> agent-skill/pi-research/scripts/run.mjs  (skill launcher, shebang)
  *
  * Note: `packages: 'external'` already externalizes every bare/`node:` import,
  * so the old `--external:node:*` flag was redundant — output is identical.
@@ -114,10 +114,10 @@ const TARGETS = {
     copyPrompts();
   },
   skill: () => {
-    const entry = p('skills', 'pi-research', 'scripts', 'run.ts');
-    const outfile = p('skills', 'pi-research', 'scripts', 'run.mjs');
+    const entry = p('agent-skill', 'pi-research', 'scripts', 'run.ts');
+    const outfile = p('agent-skill', 'pi-research', 'scripts', 'run.mjs');
     // The published package ships the BUILT run.mjs and deliberately excludes its
-    // run.ts source (package.json "files": "!skills/pi-research/scripts/run.ts"),
+    // run.ts source (package.json "files": "!agent-skill/pi-research/scripts/run.ts"),
     // yet it also ships prepare.cjs + build.cjs — and `prepare` runs `build.cjs all`.
     // On any install that executes prepare against the shipped tree (npm install
     // <dir>, file:, npm link, pi install <dir>) this target had no entry point and

package/scripts/cleanup.cjs

@@ -28,9 +28,14 @@ const projectRoot = path.join(__dirname, '..');
  * coding-agent harnesses, so `npm uninstall` is symmetric with the in-app
  * installer (the /research-config "Install Skill in Coding Agents" action).
  * Reads the manifest written by the installer and removes ONLY entries we still
- * own (a symlink pointing into a pi-research skills dir, or a copy carrying our
- * package marker). Foreign directories are never touched. Best-effort; never
+ * own (a symlink pointing into a pi-research skill source dir, or a copy carrying
+ * our package marker). Foreign directories are never touched. Best-effort; never
  * throws (preuninstall must not fail the uninstall).
+ *
+ * The ownership regex below duplicates src/skill-install/skill-installer.ts's:
+ * preuninstall runs as a plain CJS script with no access to the built module.
+ * Both accept the current `agent-skill/` source dir AND the pre-1.5.3 `skills/`
+ * one, so a link created by an older version is still recognised and removed.
  */
 function removeInstalledSkills() {
   const manifestPath = path.join(os.homedir(), '.pi', 'research', 'installed-skills.json');
@@ -58,7 +63,7 @@ function removeInstalledSkills() {
     try {
       if (lst.isSymbolicLink()) {
         const dest = path.resolve(path.dirname(p), readlinkSync(p));
-        owned = /[/\\]pi-research[/\\]skills[/\\]pi-research$/.test(dest);
+        owned = /[/\\]pi-research[/\\](?:agent-skill|skills)[/\\]pi-research$/.test(dest);
       } else {
         const md = readFileSync(path.join(p, 'SKILL.md'), 'utf-8');
         owned = md.includes('@lincoln504/pi-research');

package/scripts/prepare.cjs

@@ -10,7 +10,7 @@
  * Artifacts built:
  *   - dist/thread-worker.mjs       (browser worker, via build:worker)
  *   - dist/cli.mjs (+ dist/prompts, dist/webgpu-probe.mjs)  (pi-research CLI binary, via build:cli)
- *   - skills/pi-research/scripts/run.mjs  (skill launcher, via build:skill)
+ *   - agent-skill/pi-research/scripts/run.mjs  (skill launcher, via build:skill)
  */
 
 'use strict';

package/src/cli.ts

@@ -2,7 +2,7 @@
  * pi-research — standalone CLI
  *
  * A thin, dependency-free command line over the pi-research programmatic SDK
- * (src/sdk.ts). It lets any tool — Claude, Cursor, a shell script, CI — run
+ * (src/sdk.ts). It lets any tool — Claude, Codex, a shell script, CI — run
  * multi-agent web research without the pi CLI or TUI.
  *
  *   pi-research research "<query>" [--depth N] [--model provider/id]

package/src/skill-install/skill-installer.ts

@@ -49,8 +49,11 @@ export interface HarnessDef {
 export const HARNESSES: readonly HarnessDef[] = [
   { id: 'claude', label: 'Claude', baseDir: '.claude', skillsDir: path.join('.claude', 'skills'), confidence: 'confirmed' },
   { id: 'openclaw', label: 'OpenClaw', baseDir: '.openclaw', skillsDir: path.join('.openclaw', 'skills'), confidence: 'confirmed', note: 'OpenClaw reads ~/.openclaw/skills as a managed skill root and accepts symlinked skill folders (docs.openclaw.ai/tools/skills).' },
-  { id: 'pi', label: 'pi', baseDir: '.pi', skillsDir: path.join('.pi', 'skills'), confidence: 'confirmed' },
-  { id: 'cursor', label: 'Cursor', baseDir: '.cursor', skillsDir: path.join('.cursor', 'skills'), confidence: 'partial', note: 'Cursor project-level skills are documented; the global ~/.cursor/skills path is community-reported.' },
+  // pi's own skill root is under its agent dir (~/.pi/agent/skills), NOT ~/.pi/skills.
+  // Listed for DETECTION only — pi is never an install target (see SKILL_AGENT_TARGETS):
+  // the host already exposes research as a native tool, so a skill there would just
+  // duplicate it through a slower subprocess.
+  { id: 'pi', label: 'pi', baseDir: '.pi', skillsDir: path.join('.pi', 'agent', 'skills'), confidence: 'confirmed' },
   { id: 'codex', label: 'OpenAI Codex CLI', baseDir: '.codex', skillsDir: path.join('.codex', 'skills'), confidence: 'unverified', note: 'Codex skills support is emerging; path not confirmed by official docs.' },
   { id: 'agents', label: 'Cross-tool (~/.agents/skills)', baseDir: '.agents', skillsDir: path.join('.agents', 'skills'), confidence: 'unverified', note: 'Proposed Universal Agents convention; not yet a ratified standard.' },
 ] as const;
@@ -58,6 +61,31 @@ export const HARNESSES: readonly HarnessDef[] = [
 const SKILL_NAME = 'pi-research';
 const PACKAGE_NAME = '@lincoln504/pi-research';
 
+/**
+ * Directory inside this package that holds the shipped skill.
+ *
+ * Deliberately NOT `skills/`: pi treats a package-root `skills/` directory as a
+ * resource root and convention-scans it whenever its manifest omits a `skills`
+ * key, so the old name made pi load this skill — a slower duplicate of the
+ * extension's own native research tool — as soon as anything rewrote the
+ * package's settings entry into object form (which `pi config` does on any
+ * toggle). The name must stay outside pi's reserved resource types
+ * (extensions, skills, prompts, themes).
+ */
+const SKILL_SOURCE_DIR = 'agent-skill';
+/** Pre-1.5.3 location. Still recognised so existing installs stay manageable. */
+const LEGACY_SKILL_SOURCE_DIR = 'skills';
+
+/**
+ * Shape an owned symlink's destination must have: `…/pi-research/<dir>/pi-research`
+ * where `<dir>` is the current or the legacy source directory. Kept in sync with
+ * the duplicate in scripts/cleanup.cjs, which runs on preuninstall without this
+ * module available.
+ */
+const OWNED_SYMLINK_DEST = new RegExp(
+  `[/\\\\]${SKILL_NAME}[/\\\\](?:${SKILL_SOURCE_DIR}|${LEGACY_SKILL_SOURCE_DIR})[/\\\\]${SKILL_NAME}$`,
+);
+
 /**
  * This package's version, used to stamp manifest entries so a stale COPY can be
  * detected and refreshed. Read from the SKILL.md we are about to install rather
@@ -77,18 +105,17 @@ function readSkillVersion(sourceDir: string): string | null {
 }
 
 /**
- * The coding agents the in-app installer (the /research-config TUI) targets:
- * Claude, Codex, and OpenClaw. Each loads skills from a home-directory
- * `~/.<agent>/skills/` path — OpenClaw reads `~/.openclaw/skills` as a managed
- * skill root that accepts symlinked skill folders — so a single global symlink
- * works. Every target is gated on the agent's config dir already existing (see
- * skillInstallCandidates), so a tool that isn't set up is never offered and we
+ * The coding agents the in-app installer (the /research-config TUI) targets. Each
+ * loads skills from a home-directory `~/.<agent>/skills/` path, so a single global
+ * symlink works. Every target is gated on the agent's config dir already existing
+ * (see skillInstallCandidates), so a tool that isn't set up is never offered and we
  * never create its home dir.
  *
- * Cursor is deliberately excluded: it has no personal/global skills directory —
- * Cursor only loads skills from a project-level `.cursor/skills/`, so a global
- * `~/.cursor/skills` symlink would never be read. `pi` (the host itself) and the
- * speculative `~/.agents` convention are likewise excluded from the one-click flow.
+ * `pi` (the host itself) and the speculative `~/.agents` convention are excluded:
+ * pi already exposes research as a native tool, and a skill in either root would
+ * only add a slower duplicate. Agents that expose no personal/global skills
+ * directory — only project-level ones — cannot be served by a global symlink and
+ * are likewise not targeted.
  */
 export const SKILL_AGENT_TARGETS = ['claude', 'codex', 'openclaw'] as const;
 
@@ -166,7 +193,11 @@ function homeDir(opts?: { home?: string }): string {
  * Locate the bundled skill source directory (the one containing SKILL.md).
  * Robust across both the bundled CLI (dist/cli.mjs) and unbundled test runs:
  * honors PI_RESEARCH_SKILL_DIR, then walks up from this module and from cwd
- * looking for `skills/pi-research/SKILL.md`.
+ * looking for `agent-skill/pi-research/SKILL.md`.
+ *
+ * The legacy `skills/` location is still probed, after the current one, so a
+ * mixed tree (an older package still on disk beside a newer one) resolves rather
+ * than throwing. It is deliberately second: the current layout always wins.
  */
 export function resolveSkillSourceDir(explicit?: string): string {
   const candidates: string[] = [];
@@ -181,7 +212,8 @@ export function resolveSkillSourceDir(explicit?: string): string {
     if (!start) continue;
     let dir = start;
     for (let i = 0; i < 8; i++) {
-      candidates.push(path.join(dir, 'skills', SKILL_NAME));
+      candidates.push(path.join(dir, SKILL_SOURCE_DIR, SKILL_NAME));
+      candidates.push(path.join(dir, LEGACY_SKILL_SOURCE_DIR, SKILL_NAME));
       const parent = path.dirname(dir);
       if (parent === dir) break;
       dir = parent;
@@ -193,7 +225,7 @@ export function resolveSkillSourceDir(explicit?: string): string {
       if (fs.existsSync(path.join(c, 'SKILL.md'))) return path.resolve(c);
     } catch { /* next */ }
   }
-  throw new Error('Could not locate the bundled research skill (skills/pi-research/SKILL.md). Set PI_RESEARCH_SKILL_DIR to its path.');
+  throw new Error('Could not locate the bundled research skill (agent-skill/pi-research/SKILL.md). Set PI_RESEARCH_SKILL_DIR to its path.');
 }
 
 export function getManifestPath(opts?: { home?: string }): string {
@@ -251,7 +283,7 @@ function upsertEntry(manifest: Manifest, entry: ManifestEntry): void {
 // Ownership checks (never delete what isn't ours)
 // ---------------------------------------------------------------------------
 
-/** A symlink we own points at the skill source (our package's skills/pi-research). */
+/** A symlink we own points at the skill source (our package's agent-skill/pi-research). */
 function isOwnedSymlink(targetPath: string, expectedSource?: string): boolean {
   try {
     const st = fs.lstatSync(targetPath);
@@ -259,11 +291,17 @@ function isOwnedSymlink(targetPath: string, expectedSource?: string): boolean {
     const dest = path.resolve(path.dirname(targetPath), fs.readlinkSync(targetPath));
     if (expectedSource && path.resolve(expectedSource) === dest) return true;
     // Fallback: own it only if it points at OUR package layout, i.e. the dest
-    // ends in `pi-research/skills/pi-research`. Requiring `pi-research` to be the
-    // immediate parent segment of `skills/pi-research` avoids the substring false
-    // positive where a foreign path like `/home/pi-researcher/.../skills/pi-research`
-    // (note: pi-researcher) would otherwise be misclassified as owned and deleted.
-    return /[/\\]pi-research[/\\]skills[/\\]pi-research$/.test(dest);
+    // ends in `pi-research/<source-dir>/pi-research`. Requiring `pi-research` to be
+    // the immediate parent segment avoids the substring false positive where a
+    // foreign path like `/home/pi-researcher/.../skills/pi-research` (note:
+    // pi-researcher) would otherwise be misclassified as owned and deleted.
+    //
+    // BOTH the current and legacy source-dir names are accepted. Three of this
+    // function's four call sites pass no expectedSource and rely on this branch
+    // alone, so dropping the legacy name would strand every link created before
+    // 1.5.3: reconcile would stop re-pointing it, uninstall would refuse to
+    // remove it, and status would report it as a foreign skill.
+    return OWNED_SYMLINK_DEST.test(dest);
   } catch { return false; }
 }