Atomic can help you create packages. Ask it to bundle your extensions, skills, prompt templates, or themes.

​

Atomic Packages

​

Table of Contents

• Atomic Packages
  • Table of Contents
  • Install and Manage
  • Package Sources
    • npm
    • git
    • Local Paths
  • Creating an Atomic Package
    • Gallery Metadata
  • Package Structure
    • Convention Directories
  • Dependencies
  • Package Filtering
  • Enable and Disable Resources
  • Scope and Deduplication

​

Install and Manage

Security: Atomic packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.

atomic install npm:@foo/bar@1.0.0
atomic install git:github.com/user/repo@v1
atomic install https://github.com/user/repo  # raw URLs work too
atomic install /absolute/path/to/package
atomic install ./relative/path/to/package

atomic remove npm:@foo/bar
atomic list                     # show installed packages from settings
atomic update                   # update Atomic only
atomic update --all             # update Atomic, update packages, and reconcile pinned git refs
atomic update --extensions      # update packages and reconcile pinned git refs only
atomic update --models          # force-refresh authenticated provider model catalogs
atomic update --self            # update Atomic only
atomic update --self --force    # reinstall Atomic even if current
atomic update npm:@foo/bar      # update one package
atomic update --extension npm:@foo/bar

atomic -e npm:@foo/bar
atomic -e git:github.com/user/repo

​

Package Sources

​

npm

npm:@scope/pkg@1.2.3
npm:pkg

• Versioned specs are pinned and skipped by package updates (atomic update --extensions, atomic update --all).
• User installs use the configured npm-compatible package-manager command (npm by default) and resolve from the managed Atomic npm area.
• Project installs go under .atomic/npm/ (legacy .pi/npm/ remains a compatibility fallback).
• Set npmCommand in settings.json to pin npm package lookup and install operations to a specific wrapper command such as mise or asdf.

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

​

git

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• Without git: prefix, only protocol URLs are accepted (https://, http://, ssh://, git://).
• With git: prefix, shorthand formats are accepted, including github.com/user/repo and git@github.com:user/repo.
• HTTPS and SSH URLs are both supported.
• SSH URLs use your configured SSH keys automatically (respects ~/.ssh/config).
• For non-interactive runs (for example CI), you can set GIT_TERMINAL_PROMPT=0 to disable credential prompts and set GIT_SSH_COMMAND (for example ssh -o BatchMode=yes -o ConnectTimeout=5) to fail fast.
• Refs are pinned tags or commits. atomic update --extensions and atomic update --all do not move them to newer refs, but they do reconcile an existing clone to the configured ref.
• Use atomic install git:host/user/repo@new-ref to update settings and move an existing package to a new pinned ref.
• Cloned to ~/.atomic/agent/git/<host>/<path> (global) or .atomic/git/<host>/<path> (project; legacy .pi/git/ remains a compatibility fallback).
• When reconciliation changes the checkout, Atomic resets and cleans the clone, then runs the configured npm-compatible install command if package.json exists.

# git@host:path shorthand (requires git: prefix)
atomic install git:git@github.com:user/repo

# ssh:// protocol format
atomic install ssh://git@github.com/user/repo

# With version ref
atomic install git:git@github.com:user/repo@v1.0.0

​

Local Paths

/absolute/path/to/package
./relative/path/to/package

​

Creating an Atomic Package

{
  "name": "my-package",
  "keywords": ["atomic-package"],
  "atomic": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"],
    "workflows": ["./workflows"]
  }
}

​

Gallery Metadata

{
  "name": "my-package",
  "keywords": ["atomic-package", "pi-package"],
  "atomic": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

• video: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
• image: PNG, JPEG, GIF, or WebP. Displayed as a static preview.

​

Package Structure

​

Convention Directories

• extensions/ loads .ts and .js files
• skills/ recursively finds SKILL.md folders and loads top-level .md files as skills
• prompts/ loads .md files
• themes/ loads .json files
• workflows/ loads workflow SDK files (.ts, .js, .mjs, .cjs); workflow/ is also accepted as a singular alias. Workflow files should import { workflow } from "@bastani/workflows", import Type from typebox, and export the workflow({ ... }) result. TypeScript package authors do not need a hand-authored .d.ts, a declare module shim, or a tsconfig paths alias for the SDK import — the SDK types ship with @bastani/atomic. A package that also imports @bastani/atomic picks them up automatically; a pure workflow-only package adds one opt-in line (compilerOptions.types: ["@bastani/atomic/workflows/ambient"] or a /// <reference types="@bastani/atomic/workflows/ambient" /> directive). See the workflow SDK typing guidance under Programmatic Usage in the workflows guide.

​

Dependencies

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "atomic": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

​

Package Filtering

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"],
      "workflows": ["workflows/*.ts"]
    }
  ]
}

• Omit a key to load all of that type.
• Use [] to load none of that type.
• !pattern excludes matches.
• +path force-includes an exact path.
• -path force-excludes an exact path.
• Filters layer on top of the manifest. They narrow down what is already allowed.

​

Enable and Disable Resources

​

Scope and Deduplication

• npm: package name
• git: repository URL without ref
• local: resolved absolute path