@atlassian/chippy 0.0.1-beta.1 → 0.0.1-beta.2

package/README.md

@@ -1,8 +1,8 @@
-![Chippy logo](.agents/skills/chippy/extension/icon-48.png)
+![Chippy logo](https://raw.githubusercontent.com/atlassian-labs/chippy/main/.agents/skills/chippy/extension/icon-48.png)
 
 # Chippy
 
-[![Atlassian license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+[![Atlassian license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](https://github.com/atlassian-labs/chippy/blob/main/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/atlassian-labs/chippy/blob/main/CONTRIBUTING.md)
 
 **A friend who helps you understand what’s happening, find the cause, and fix it.**
 
@@ -18,7 +18,7 @@ on the page and leave it a note.
 
 Chippy works with standard React and needs no patched packages. Development
 builds give the most detail; production builds show less, and every answer says
-what was available. See [React compatibility](docs/react-compatibility.md).
+what was available. See [React compatibility](https://github.com/atlassian-labs/chippy/blob/main/docs/react-compatibility.md).
 
 ## What you can ask
 
@@ -29,38 +29,43 @@ what was available. See [React compatibility](docs/react-compatibility.md).
 
 ## Install
 
-You need Node.js 22.12 or later and Chrome or another Chromium browser.
+Chippy has three parts:
 
-1. Install the agent skill:
+- The **agent skill** tells your coding agent how to run Chippy.
+- The **local helper** is a small server on `127.0.0.1:7823`. The agent starts
+  it when it needs it.
+- The **page runtime** runs inside the page and reads React.
+
+The skill and the helper are the same in every setup. You choose how the page
+runtime gets into the page; see [Connect a page](#connect-a-page).
+
+You need Node.js 22.20 or later, which the skills CLI requires.
+
+1. Install the agent skill with the [skills CLI](https://github.com/vercel-labs/skills):
 
    ```sh
-   npx @atlassian/chippy install
+   npx skills add atlassian-labs/chippy --skill chippy -g
    ```
 
-   This copies the skill to `~/.agents/skills/chippy` (run it again to update)
-   and prints the next steps with the exact paths for your machine. To install
-   it in a project instead, pass `--dir`, for example
-   `npx @atlassian/chippy install --dir .agents/skills/chippy`; the paths below
-   then start from that folder.
+   Choose your coding agents when it asks, or name them with `-a`, for example
+   `-a claude-code`. With `-g`, every project can use the skill, and its files
+   live in `~/.agents/skills/chippy`; each agent's skills folder links to that
+   copy. Leave out `-g` to install it in the current project's
+   `.agents/skills/chippy` instead. Run `npx skills update chippy` to update it.
 
-2. Load the browser extension: open `chrome://extensions`, turn on
-   **Developer mode**, choose **Load unpacked**, and select the `extension`
-   folder the installer printed (`~/.agents/skills/chippy/extension` by
-   default). The folder picker hides dot-folders, so paste the path instead of
-   browsing: press **Cmd+Shift+G** on macOS or **Ctrl+L** on Linux, or use the
-   address bar on Windows.
+2. Connect a page with one of the routes in [Connect a page](#connect-a-page).
 
-3. Open your app, click the Chippy extension icon, and enable Chippy for the
-   page's origin.
-
-4. Ask your agent to use Chippy on the page.
+3. Ask your agent to use Chippy on the page.
 
 The agent runs Chippy through the skill's `chippy.sh` script, which needs bash
 (macOS, Linux, or WSL on Windows). You don't start anything yourself: the agent
 starts a local helper on `127.0.0.1:7823` when it needs one. A sandboxed agent
 asks for permission to reach it; approve the prompt or allow `chippy.sh`. If
-your agent runs in a container or a remote machine, see
-[MCP setup](.agents/skills/chippy/references/mcp.md) for reaching the helper.
+your agent runs in a container or on a remote machine, the browser must reach
+the helper's port through an SSH tunnel, a published container port, or other
+forwarding your environment provides; Chippy does not set that up.
+[Local and wide binds](https://github.com/atlassian-labs/chippy/blob/main/docs/trust-boundary.md#local-and-wide-binds)
+lists what to set for each setup.
 
 **Optional: connect over MCP.** If your agent supports MCP, it can call Chippy
 as tools instead of running a script. Ask it:
@@ -69,27 +74,112 @@ as tools instead of running a script. Ask it:
 
 The agent adds the Chippy server to its own MCP configuration and checks the
 connection. Some agents need a restart before the new tools appear. To set it
-up yourself, see [MCP setup](.agents/skills/chippy/references/mcp.md).
+up yourself, see [MCP setup](https://github.com/atlassian-labs/chippy/blob/main/.agents/skills/chippy/references/mcp.md).
+
+## Connect a page
+
+Every route loads the same page runtime and talks to the same helper. The
+routes differ in what you set up, whether Chippy stays after a reload, and
+whether Chippy can record the initial page load.
+
+| Route | What you set up | After a reload | Records the initial load |
+| --- | --- | --- | --- |
+| [Browser extension](#browser-extension) | Load the extension once, then enable it for each site | Chippy loads again | Yes |
+| [Agent-driven browser](#agent-driven-browser) | Nothing. The agent opens its own Playwright browser | Chippy loads again | Yes, when the agent loads Chippy before the page |
+| [Local proxy](#local-proxy) | Nothing. The agent starts the proxy, and you open the proxy address | Chippy loads again | Yes |
+| [Storybook addon](#storybook-addon) | Add the addon to your Storybook configuration | Chippy remounts the story and stays | The story's mount |
+| [Console import](#console-import) | Paste one line into the page's console | Chippy is removed. Paste the line again | No |
+| [Your app's code](#your-apps-code) | Install the npm package and call `connectChippy()` | Call it again | No |
+
+"Records the initial load" means that the agent can reload the page and record
+the renders from the first commit. Every route records renders that happen
+after Chippy connects.
+
+### Browser extension
+
+Use the extension for day-to-day work in your own Chrome or Chromium browser.
+
+1. Open `chrome://extensions`, turn on **Developer mode**, and choose
+   **Load unpacked**. Select the skill's `extension` folder:
+   `~/.agents/skills/chippy/extension`, or `.agents/skills/chippy/extension`
+   in your project if you installed without `-g`. The folder picker hides
+   folders whose names start with a dot, so type the path instead of browsing.
+   On macOS, press **Cmd+Shift+G**, paste the path, press **Return**, and
+   choose **Select**. On Linux, press **Ctrl+L** and paste the path. On
+   Windows, paste it into the address bar. After `npx skills update`, click
+   **Reload** on the Chippy card in `chrome://extensions`.
+2. Open your app, click the Chippy extension icon, and enable Chippy for the
+   page's origin.
+
+### Agent-driven browser
+
+The agent opens a Playwright browser, loads Chippy into the page, and drives
+the page itself. No extension is needed. Use this route for repeatable flows,
+headless checks, and CI. Ask your agent to open the page with Chippy in
+Playwright; the skill has the setup steps.
+
+### Local proxy
 
-## Two ways to start
+The helper can sit in front of a dev server on your machine and add Chippy to
+the page before the page's own scripts run. No extension is needed, and this
+route works in any browser, including one that your agent drives. Ask your
+agent to start the Chippy proxy for your page, then open the address that it
+gives you on `127.0.0.1:7823`. The proxy forwards only to servers on this
+machine, and it adds Chippy only to the page address that the agent gave it.
+It removes the page's Content Security Policy headers, so it also works for
+pages that block the console import.
 
-- **From the agent:** ask it about the page. It finds components by name, text,
-  test ID, source file, or prop, reads their state, clicks through the page, and
-  records renders.
-- **From the page:** click the Chippy button in the page corner and drag a probe
-  marker (P1, or P2 to compare two elements) onto an element. Choose whether you
-  want it explained, investigated, or changed, and add a note. Then ask the agent
-  to read it, or to keep watching for new notes while you click around.
+### Storybook addon
 
-No extension? Once the agent has started the helper, paste this into the page's
-console:
+In Storybook 10.3 or later, add the addon to your Storybook configuration:
+
+```js
+export default {
+  addons: ['@atlassian/chippy/storybook'],
+};
+```
+
+The addon adds Chippy panels to Storybook and connects each story to your agent.
+When the agent reloads the page, Storybook remounts the current story instead of
+reloading the preview. See the
+[package documentation](https://github.com/atlassian-labs/chippy/blob/main/docs/npm-package.md#storybook)
+for build targets.
+
+### Console import
+
+Use this for a quick look at a page where you cannot install the extension.
+Once the agent has started the helper, paste this into the page's console:
 
 ```js
 import('http://127.0.0.1:7823/__chippy/inject.mjs')
 ```
 
-Repeat it after every reload. Sites with a strict Content Security Policy block
-it, and it can't record the initial page load; use the extension for that.
+A reload removes Chippy, so paste the line again after every reload or
+navigation. Sites with a strict Content Security Policy block the import.
+
+### Your app's code
+
+For pages that the extension cannot reach, such as an embedded browser, call
+`connectChippy()` from `@atlassian/chippy/browser` in the page. It loads the
+same runtime as the console import. See
+[Connect a browser page to an agent](https://github.com/atlassian-labs/chippy/blob/main/docs/npm-package.md#connect-a-browser-page-to-an-agent).
+
+## Ask the agent, or point at the page
+
+- **Ask the agent** about the page. It finds components by name, text, test ID,
+  source file, or prop, reads their state, clicks through the page, and records
+  renders.
+- **Point at the page:** click the Chippy button in the page corner and drag a
+  probe marker (P1, or P2 to compare two elements) onto an element. Choose
+  whether you want it explained, investigated, or changed, and add a note. Then
+  ask the agent to read it, or to keep watching for new notes while you click
+  around. The extension, the local proxy, and the Storybook addon show the
+  Chippy button. The console import does not.
+
+<p align="center">
+  <a href="assets/chippy-call.mp4"><img src="assets/chippy-call.svg" width="900" alt="Animated clip: the asks roll in and Jira keeps them in line, so you call a chippy. Chippy gives your coding agent a hand in the running app: it finds the component and source line for a button to move, reads live props and state to show why a button stays disabled, compares before and after, finds what set off a slow click, connects the page, React, and your code, and turns the page into an experimentation lab."></a>
+  <br><a href="assets/chippy-call.mp4">Watch with sound</a>
+</p>
 
 ## Evidence, then edits
 
@@ -99,20 +189,18 @@ side effects during render, say so and the agent uses read-only inspection
 instead. Chippy changes your source only when you ask it to, and checks the fix
 against the same page.
 
-## Use Chippy from your own code
+## Use Chippy without an agent
 
-Install `@atlassian/chippy` in your project when the extension is not the right fit:
+The `@atlassian/chippy` npm package also works with no agent, helper, or
+extension:
 
 - **Catch re-render regressions in tests.** Record which components rendered
-  during an interaction, and why, in a test or a script, with no agent, helper, or
-  extension.
-- **Connect pages the extension cannot reach**, such as an embedded browser or a
-  test runner, or connect from your app's startup code so Chippy sees the first
-  render.
-- **Add Chippy to Storybook** as an addon.
+  during an interaction, and why, in a test or a script. Install the recorder in
+  your app's entry module before React DOM loads, and it records from the first
+  commit.
 - **Ship your own build** with extra plugins for your stack.
 
-See the [package documentation](docs/npm-package.md) for setup.
+See the [package documentation](https://github.com/atlassian-labs/chippy/blob/main/docs/npm-package.md) for setup.
 
 ## How Chippy compares
 
@@ -171,19 +259,19 @@ change is verified.
 
 ## Learn more
 
-- [Agent skill](.agents/skills/chippy/SKILL.md) and its [references](.agents/skills/chippy/references/README.md)
-- [React compatibility](docs/react-compatibility.md)
-- [Plugins](docs/plugins.md) for app-specific knowledge
-- [Trust boundary](docs/trust-boundary.md): what page data Chippy sees and who can reach the helper
-- [Security policy](SECURITY.md)
-- [Changelog](CHANGELOG.md)
+- [Agent skill](https://github.com/atlassian-labs/chippy/blob/main/.agents/skills/chippy/SKILL.md) and its [references](https://github.com/atlassian-labs/chippy/blob/main/.agents/skills/chippy/references/README.md)
+- [React compatibility](https://github.com/atlassian-labs/chippy/blob/main/docs/react-compatibility.md)
+- [Plugins](https://github.com/atlassian-labs/chippy/blob/main/docs/plugins.md) for app-specific knowledge
+- [Trust boundary](https://github.com/atlassian-labs/chippy/blob/main/docs/trust-boundary.md): what page data Chippy sees and who can reach the helper
+- [Security policy](https://github.com/atlassian-labs/chippy/blob/main/SECURITY.md)
+- [Changelog](https://github.com/atlassian-labs/chippy/blob/main/CHANGELOG.md)
 
-To build, test, or change Chippy, see [Contributing](CONTRIBUTING.md) and the
-[code of conduct](CODE_OF_CONDUCT.md).
+To build, test, or change Chippy, see [Contributing](https://github.com/atlassian-labs/chippy/blob/main/CONTRIBUTING.md) and the
+[code of conduct](https://github.com/atlassian-labs/chippy/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 Copyright (c) 2026 Atlassian US., Inc.
-Apache 2.0 licensed, see [LICENSE](LICENSE) file.
+Apache 2.0 licensed, see [LICENSE](https://github.com/atlassian-labs/chippy/blob/main/LICENSE) file.
 
 [![With ❤️ from Atlassian](https://raw.githubusercontent.com/atlassian-internal/oss-assets/master/banner-cheers.png)](https://www.atlassian.com)

package/bin/chippy.mjs

@@ -1,121 +1,79 @@
 #!/usr/bin/env node
-// Installs the Chippy agent skill from this package and prints the next steps,
-// or packs a custom build with extra plugins (see pack.mjs).
-//   npx @atlassian/chippy install [--dir <path>] [--force]
+// Packs a custom Chippy build with extra plugins (see pack.mjs). The agent
+// skill is installed with the skills CLI, not by this package.
 //   npx @atlassian/chippy pack [--config <file>]
-import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const HEALTH_URL = 'http://127.0.0.1:7823/__chippy/health';
-
-export function defaultSkillDir() {
-  return join(homedir(), '.agents', 'skills', 'chippy');
-}
-
-function isChippySkill(directory) {
-  const skill = join(directory, 'SKILL.md');
-  return existsSync(skill) && /^name:\s*chippy\s*$/m.test(readFileSync(skill, 'utf8'));
-}
-
-// Copies the bundled skill to `target`. An existing Chippy skill is replaced;
-// any other existing directory is left alone unless `force` is set.
-export function installSkill({ source = join(PACKAGE_ROOT, 'lib', 'mcp-skill'), target = defaultSkillDir(), force = false } = {}) {
-  const destination = resolve(target);
-  if (!isChippySkill(source)) throw new Error(`Bundled skill not found at ${source}; build the package first`);
-  if ([homedir(), dirname(homedir()), '/', resolve('.')].includes(destination)) {
-    throw new Error(`Choose a dedicated skill directory, not ${destination}`);
-  }
-  if (existsSync(destination) && !isChippySkill(destination) && !force) {
-    throw new Error(`${destination} exists and is not a Chippy skill; pass --force to replace it`);
+export const SKILL_INSTALL_COMMAND = 'npx skills add atlassian-labs/chippy --skill chippy -g';
+
+const COMMAND_OPTIONS = { pack: ['--config'] };
+const HELP = new Set(['--help', '-h', 'help']);
+const VERSION = new Set(['--version', '-v']);
+
+export function parseArgs(argv) {
+  const args = { command: argv[0], config: 'chippy.config.mjs', help: false, version: false };
+  if (HELP.has(args.command)) return { ...args, command: undefined, help: true };
+  if (VERSION.has(args.command)) return { ...args, command: undefined, version: true };
+  if (args.command === 'install') return args;
+  const allowed = COMMAND_OPTIONS[args.command] ?? [];
+  const value = (i) => {
+    if (i >= argv.length || argv[i].startsWith('-')) throw new Error(`${argv[i - 1]} needs a value`);
+    return argv[i];
+  };
+  for (let i = 1; i < argv.length; i++) {
+    if (HELP.has(argv[i])) args.help = true;
+    else if (VERSION.has(argv[i])) args.version = true;
+    else if (!allowed.includes(argv[i])) throw new Error(`Unknown option for ${args.command}: ${argv[i]}`);
+    else if (argv[i] === '--config') args.config = value(++i);
   }
-  mkdirSync(dirname(destination), { recursive: true });
-  rmSync(destination, { recursive: true, force: true });
-  cpSync(source, destination, { recursive: true });
-  return destination;
+  return args;
 }
 
-export function mcpConfig(skillDir) {
-  return { mcpServers: { chippy: { command: 'node', args: [join(skillDir, 'scripts', 'chippy-mcp.cjs')] } } };
-}
+function usage(name) {
+  return `Usage: npx ${name} pack [--config <file>]
+       npx ${name} --version
 
-async function helperStatus() {
-  try {
-    const response = await fetch(HEALTH_URL, { signal: AbortSignal.timeout(1000) });
-    return response.ok ? 'running' : `responded ${response.status}`;
-  } catch {
-    return 'not running (the MCP server or `chippy.sh start` starts it on demand)';
-  }
+pack     Builds a custom skill and extension with extra plugins from a config
+         file (default chippy.config.mjs). See the package README.
+
+Install the Chippy agent skill with the skills CLI:
+  ${SKILL_INSTALL_COMMAND}
+`;
 }
 
-function parseArgs(argv) {
-  const args = { command: argv[0], dir: undefined, force: false, config: 'chippy.config.mjs' };
-  for (let i = 1; i < argv.length; i++) {
-    if (argv[i] === '--force') args.force = true;
-    else if (argv[i] === '--dir') args.dir = argv[++i];
-    else if (argv[i] === '--config') args.config = argv[++i];
-    else throw new Error(`Unknown option: ${argv[i]}`);
-  }
-  return args;
+// The skill used to be installed by this package; point earlier instructions
+// at the skills CLI instead of failing with a bare usage message.
+function installMoved() {
+  return `This package no longer installs the Chippy skill. Install it with the skills CLI:
+  ${SKILL_INSTALL_COMMAND}
+Drop -g to install it in the current project only.
+`;
 }
 
 async function main(argv) {
-  const { name } = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+  const { name, version } = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
   const args = parseArgs(argv);
-  if (args.command === 'pack') {
-    await pack(args.config);
+  if (args.version) {
+    process.stdout.write(`${version}\n`);
     return;
   }
-  if (args.command !== 'install') {
-    process.stdout.write(`Usage: npx ${name} install [--dir <path>] [--force]
-       npx ${name} pack [--config <file>]
-
-install  Installs the Chippy agent skill (default ${defaultSkillDir()}).
-pack     Builds a custom skill and extension with extra plugins from a config
-         file (default chippy.config.mjs). See the package README.
-`);
-    process.exitCode = args.command === undefined || args.command === '--help' ? 0 : 2;
+  if (args.command === 'install') {
+    process.stderr.write(installMoved());
+    process.exitCode = 1;
     return;
   }
-  const skillDir = installSkill({ target: args.dir ?? defaultSkillDir(), force: args.force });
-  process.stdout.write(`Installed the Chippy skill to ${skillDir}
-
-1. Install the browser extension: open chrome://extensions, turn on Developer
-   mode, choose Load unpacked, and select this folder:
-   ${join(skillDir, 'extension')}${folderPickerHint(skillDir)}
-   Without the extension, once your agent has started the helper, run this in
-   the page's console:
-   import('http://127.0.0.1:7823/__chippy/inject.mjs')
-
-2. Enable Chippy for your page's origin in the extension popup, then ask your
-   agent to use Chippy on the page. The agent runs
-   ${join(skillDir, 'scripts', 'chippy.sh')}
-
-Optional: connect over MCP if your agent supports it. Ask your agent:
-  Connect Chippy over MCP by following ${join(skillDir, 'references', 'mcp.md')}
-Or add this server to your agent's MCP configuration yourself:
-${JSON.stringify(mcpConfig(skillDir), null, 2).replace(/^/gm, '  ')}
-
-Helper: ${await helperStatus()}
-`);
-}
-
-// The skill lives in a dot-folder, which folder pickers hide by default.
-const FOLDER_PICKER_HINT = {
-  darwin: 'The folder is hidden in Finder: press Cmd+Shift+G in the picker and paste the path.',
-  win32: 'Paste the path into the picker\'s address bar.',
-  linux: 'The folder is hidden: press Ctrl+L in the picker and paste the path.',
-};
-
-function folderPickerHint(skillDir) {
-  if (!skillDir.split(/[\\/]/).some((part) => part.startsWith('.'))) return '';
-  return `\n   ${FOLDER_PICKER_HINT[process.platform] ?? FOLDER_PICKER_HINT.linux}`;
+  if (args.help || !COMMAND_OPTIONS[args.command]) {
+    process.stdout.write(usage(name));
+    process.exitCode = args.help || args.command === undefined ? 0 : 2;
+    return;
+  }
+  await pack(args.config);
 }
 
 async function pack(configPath) {
-  // Loaded on demand: install must not depend on the packer.
   const { loadPackConfig, packChippy } = await import('./pack.mjs');
   const result = await packChippy(await loadPackConfig(resolve(configPath)));
   process.stdout.write(`Packed Chippy:

package/bin/pack.mjs

@@ -8,6 +8,7 @@ import {
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ownsDirectory } from './skill-dir.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const BUILTIN_PLUGINS = [
@@ -18,14 +19,32 @@ const RUNTIME_BUNDLES = ['extension/avalanche.iife.js', 'extension/avalanche.es.
 const BUILD_CONFIG_CONSUMERS = ['extension/background.js', 'extension/panel-settings.js'];
 const PLUGIN_ID = /^[a-z][a-z0-9-]*$/;
 const CHROME_VERSION = /^\d+(\.\d+){0,3}$/;
+const CONFIG_KEYS = {
+  '': ['plugins', 'defaultPlugins', 'extension', 'skill', 'outDir'],
+  'plugins[]': ['id', 'entry', 'label'],
+  extension: ['name', 'version', 'description', 'key'],
+  skill: ['overlay'],
+};
 
 function fail(message) {
   throw new Error(`chippy pack: ${message}`);
 }
 
+// A misspelled key would otherwise build silently without the setting.
+function rejectUnknownKeys(value, keys, path) {
+  if (!value || typeof value !== 'object') return;
+  for (const key of Object.keys(value)) {
+    if (!keys.includes(key)) fail(`unknown config key ${path ? `${path}.` : ''}${key}; expected one of ${keys.join(', ')}`);
+  }
+}
+
 /** Validates a pack config and resolves its paths against `baseDir`. */
 export function normalizePackConfig(config, baseDir) {
   if (!config || typeof config !== 'object') fail('the config must export an object');
+  rejectUnknownKeys(config, CONFIG_KEYS[''], '');
+  rejectUnknownKeys(config.extension, CONFIG_KEYS.extension, 'extension');
+  rejectUnknownKeys(config.skill, CONFIG_KEYS.skill, 'skill');
+  (config.plugins ?? []).forEach((plugin, index) => rejectUnknownKeys(plugin, CONFIG_KEYS['plugins[]'], `plugins[${index}]`));
   const plugins = (config.plugins ?? []).map((plugin, index) => {
     if (!plugin || typeof plugin !== 'object') fail(`plugins[${index}] must be { id, entry, label? }`);
     if (!PLUGIN_ID.test(plugin.id ?? '')) fail(`plugins[${index}].id must match ${PLUGIN_ID}`);
@@ -150,6 +169,7 @@ export async function packChippy(config, { source = join(PACKAGE_ROOT, 'lib', 'm
   const { plugins, defaultPlugins, extension, overlay, outDir } = config;
   const code = await bundlePlugins(plugins, defaultPlugins);
   const skillDir = join(outDir, 'chippy');
+  if (!ownsDirectory(skillDir)) fail(`${skillDir} exists and is not a Chippy skill; choose another outDir`);
   rmSync(skillDir, { recursive: true, force: true });
   mkdirSync(outDir, { recursive: true });
   cpSync(source, skillDir, {

package/bin/skill-dir.mjs

@@ -0,0 +1,15 @@
+// Ownership checks for the directories Chippy's CLI replaces. A directory is
+// Chippy's to replace when it is empty or holds a Chippy skill; anything else
+// belongs to someone else and is never deleted.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function isChippySkill(directory) {
+  const skill = join(directory, 'SKILL.md');
+  return existsSync(skill) && /^name:\s*chippy\s*$/m.test(readFileSync(skill, 'utf8'));
+}
+
+export function ownsDirectory(directory) {
+  return !existsSync(directory) || readdirSync(directory).length === 0 || isChippySkill(directory);
+}
+