apx-extensions · git:20261013.989b12a · 2026-10-13 · sha256 9ccfc066d017759e

apx-extensions git:20261013.989b12aA

Immutable. This exact content never changes and is served at /api/v1/blob/9ccfc066d017759e.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_ietnfvwlftziv75c/9ccfc066d017759ef2f884da55161becb576ea3850e47faf94992bd495d525d8.json

Then /plugin install apx-extensions@markdownregistry-ietnfvwlftziv75c in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: apx-extensions
description: Build and install an APX extension, one folder with an apx-extension.json that brings skills, MCP servers (including new tools you write), routine templates, keys the owner types once and an optional plugin. Use it when the owner asks for a new tool or capability APX does not have, to package skills or servers together, or for an APX extension or plugin.
---

# Extensions in APX

An extension is a folder APX can read without running anything: `apx-extension.json` plus the files it names. It
installs **off**; turning it on approves exactly those files. You build it, check it and install it with the
`apx extensions` command (through `shell`); the owner sees it in [Resources › Extensions](apx:resources/extensions).

## Pick the smallest thing first

| The owner wants | Make |
|---|---|
| An MCP server that already exists (npm, a URL) | `apx mcps add` (apx-mcps): no extension |
| Know-how for agents | A skill (apx-skills): no extension |
| A new tool that does not exist anywhere (wrap an API, a local script, a calculation) | An extension with its own MCP server |
| Skills, servers and routines that travel together or are shared | An extension |
| Code that watches APX's events or adds context to the owner's turns | An extension with a `plugin` |

## The folder

Build it in your temp folder (or in a project if the owner wants it kept in a repo):

```
northwind-crm/
  apx-extension.json
  skills/crm-lookup/SKILL.md   # each skill: a folder with a SKILL.md (frontmatter name + description)
  server.mjs                   # its own MCP server, if it brings new tools
  plugin.mjs                   # only with a plugin
```

## `apx-extension.json`

Unknown keys are refused.

```json
{
  "id": "northwind_crm",
  "name": "Northwind CRM",
  "version": "1.0.0",
  "description": "Look up customers and open deals in Northwind's CRM.",
  "skills": "skills",
  "mcp": {
    "crm": { "command": "node", "args": ["./server.mjs"], "env": { "API_KEY": "secret://api_key" } },
    "docs": { "url": "https://mcp.example.com/docs", "headers": { "Authorization": "Bearer secret://api_key" } }
  },
  "routines": [
    {
      "name": "Monday pipeline",
      "schedule": { "kind": "cron", "cron": "0 9 * * 1" },
      "prompt": "Use the crm-lookup skill to list deals that did not move last week. Answer SKIP if none."
    }
  ],
  "secrets": [{ "name": "api_key", "label": "CRM API key", "url": "https://example.com/settings/keys" }]
}
```

| Field | Rules |
|---|---|
| `id` | Lowercase letters, digits, `_` and `-`, starting with a letter or digit, at most 20. |
| `name`, `version` | Required. `description` up to 500 characters. |
| `skills` | A folder of skill folders, relative to the extension. |
| `mcp` | Servers by name (letters, digits, `_`; no `-`; at most 20); once on, each shows as `<id>-<name>`. `command` + `args` + `env`, or `url` + `headers`. A server starts in the extension's folder, so `"args": ["./server.mjs"]` works. |
| `secret://name` | One of the extension's own `secrets`, never the owner's variables and never a real value. |
| `routines` | Templates the owner adds from Routines. `schedule`: `{ "kind": "cron", "cron" }`, `{ "kind": "every", "minutes" }` (5 or more) or `{ "kind": "once", "at" }`. A routine that answers `SKIP` tells nobody. |
| `secrets` | Up to 10: `name` (same rule as servers), `label`, optional `url` where to get it. |
| `plugin` | See below. |

## A new tool: its own MCP server

`node_modules` is not copied when installing, so a server inside an extension must need no packages. Start from the
template that comes with this skill: `load_skill apx-extensions file=server-template.mjs`, save it as `server.mjs`,
replace its `TOOLS` (name, description, JSON schema of the arguments, `run`). It speaks MCP over stdio by itself,
reads keys from `process.env` (given by the manifest's `env` with `secret://`) and can use `fetch`. Try it before
installing:

```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node server.mjs
```

A tool's description says what it does and when to use it, in one or two sentences: that is all an agent sees.

## A plugin (only when files are not enough)

```json
"plugin": { "entry": "plugin.mjs", "observe": ["task.updated"], "context": false, "network": false }
```

```js
// plugin.mjs: runs in its own process; reads only its folder, writes only api.dataDir.
export default function activate(api) {
  api.on("task.updated", (event) => api.log(`task ${event.task?.id} changed`));
  api.context(async ({ thread, agent, text }) => ""); // only with "context": true; "" adds nothing
}
```

- `observe`: any of `thread.updated`, `message.created`, `run.updated`, `task.updated`, `notification.updated`.
- `api.secrets.<name>` holds its declared secrets; `api.fetch` reaches the internet only with `"network": true`, the
  local network only with `"local_network": true` as well, and never this computer. It cannot start processes or call
  APX. What `context` returns reaches agents as outside data.

## Check, install, turn on

```bash
apx extensions inspect <folder>        # what it would bring; nothing is installed
apx extensions install <folder>        # copied in, off
apx extensions                         # installed ones, on or off, and secrets missing
```

Turning it on is the owner's decision, because it approves what the folder runs: ask, or send them
[Resources › Extensions](apx:resources/extensions). With their OK: `apx extensions on <id>`. Its keys are typed by the
owner in that screen (or, if they gave you the value to store: `printf %s "$VALUE" | apx extensions secret <id>
<name>`).

Changing the folder after installing does nothing: install it again. Remove with `apx extensions rm <id>`.

## Before you hand it over

- `inspect` lists every skill, server, routine and secret you meant, and the server answers `tools/list`.
- No real token, email, phone or personal path in any file.
- Skills and descriptions in English; each skill's `description` says when to use it.
- Tell the owner what it brings, that it is installed off, and what they need to do to turn it on.