Extension Design

Design and audit Pi extensions safely (avoid workspace source imports).

rcarmo d9452be 1.2 KB Updated

File contents

Extension design notes

Use this skill when creating or reviewing extensions so imports keep working after reloads.

Avoid this pattern

Do not import from the workspace source tree (for example /workspace/piclaw/runtime/src/... or /workspace/.../node_modules). The running agent uses the installed package. Workspace paths can drift or break after reloads.

Use the installed package instead

Reference the installed dist paths, for example:

import { createBatchExecTool } from "/home/agent/.bun/install/global/node_modules/piclaw/dist/tools/context-tools.js";

Safety checklist

  1. Use installed dist paths (not workspace source).
  2. Avoid touching the DB before init.
  3. Wrap tool handlers in try/catch to avoid crashes.
  4. Guard filesystem access and saveToolOutput calls.
  5. Keep dependencies minimal and explicit.

Quick audit

rg -n "/workspace/piclaw/runtime/src|/workspace/.*/node_modules" /workspace/.pi/extensions

Update skel when changing extensions

cp /workspace/.pi/extensions/<name>.ts /workspace/piclaw/skel/.pi/extensions/<name>.ts

rcarmo/piclaw/tree/main/skel/.pi/skills/extension-design commit d9452be661

Frequently asked questions

npx skillmds@latest add rcarmo/extension-design