Skip to content

Write kits ​

A kit is a package that connects the platform to an external system. This page walks you through choosing a contract, writing the module, checking it with ph kit check, and knowing where the kit runs. You need to be a Member or above in your organization, and Node 22 or later. A kit is executable code, so the approver (an Admin or Owner of your organization, or platform staff for the official catalog) always reads it line by line.

What forms can a kit take? ​

FormDeclared inUsed for
Phillip pluginmetadata.forge.phillipscm, notify, and tracker connectors that Phillip and the services load
MCP server.mcp.jsonLets agents in Claude Code call tools
Hookhooks/hooks.jsonChecks or blocks within a Claude Code session
Guardrails policymetadata.forge.guardrailsSafety rules; see Guardrails tiers

A kit must have at least one of the four forms, or Tara reports a structure error. The rest of this page focuses on Phillip plugins, the form with the strictest contract.

The three contracts ​

Each contract has an api (currently 1) and capability groups (capabilities). Adding a capability group doesn't require changing api.

providesCapability groupFunctionsCalled by
scmtaskme, issue, issues, assign, setStatus, defaultBranch, pullForIssue, createPull, review, commentPhillip (ph bandum), the MCP server in the kit
reportcreateIssue, issuesByLabelph bandum bug
syncrepoInfo, milestones, changes, events, pull, dirs, file, putFileBandum, Ryoma
notifysendcheck, sendTara, Ryoma
trackertaskme, sprints, tasks, task, eventsRyoma

The full signature of each function is in Plugin contracts.

Write the module in plain ESM (entry) using only the Node standard library, which includes fetch, with no external package dependencies. The module exports api and a connect(opts) function, where opts contains token and settings. For scm, it also contains repo information. A kit doesn't contain or read credentials from files or environment variables. The caller passes secrets into connect. Errors carry a standard code (unauthorized, not_found, unavailable, other, and for scm also own_pull, conflict) and must not contain secrets.

Example: a notification kit ​

The directory layout looks like this.

text
kit-notify-teams/
├── .claude-plugin/
│   └── plugin.json
├── phillip/
│   └── notify.mjs
├── docs/
│   ├── cai-dat.md
│   └── su-dung.md
├── README.md
└── CHANGELOG.md

In plugin.json, declare the metadata.forge block like this.

json
{
  "schema": 1,
  "type": "kit",
  "org": "aiforge",
  "owners": ["owner@example.com"],
  "engines": ["phillip"],
  "status": "active",
  "phillip": {
    "provides": "notify",
    "api": 1,
    "entry": "phillip/notify.mjs",
    "capabilities": ["send"],
    "credential": {
      "label": "Channel webhook URL",
      "help": "Create an Incoming Webhook in the channel that should receive messages."
    },
    "settings": {
      "channelName": { "default": "", "required": true, "help": "Channel name to display" }
    }
  }
}

The module phillip/notify.mjs looks like this. The check function validates the token and the destination without sending a message, then returns a description of the destination. The send function receives m, which contains subject, text, and to. to is the email of the person concerned, and a team channel can ignore it.

js
export const api = 1;

export function connect({ token, settings }) {
  if (!token) throw Object.assign(new Error("missing webhook URL"), { code: "unauthorized" });
  return {
    async check() {
      return `channel ${settings.channelName}`;
    },
    async send(m) {
      const res = await fetch(token, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ text: `${m.subject}\n${m.text}` }),
      });
      if (!res.ok) throw Object.assign(new Error(`HTTP ${res.status}`), { code: "unavailable" });
    },
  };
}

Tara requires a Phillip plugin to have a valid provides, an entry inside the package, the correct api, a non-empty credential.label, and capability groups that belong to the contract. scm additionally requires matches, the host of the origin remote that the kit serves. tracker requires settings.project with required: true and must not have matches.

Check with ph kit check ​

Run this command on the kit directory you're writing, or on a kit already on Tara. The first form checks only the contract and the required settings.

bash
ph kit check ./kit-notify-teams --set channelName=ban-tin

Add --live to make real calls: me() for scm and tracker, or check() for notify.

bash
PHILLIP_KIT_TOKEN=<secret> ph kit check ./kit-notify-teams --set channelName=ban-tin --live

To send a test notification, add --send and --to.

bash
PHILLIP_KIT_TOKEN=<secret> ph kit check ./kit-notify-teams --set channelName=ban-tin --send "test" --to owner@example.com

The command checks api, the functions of each capability group, and the required settings. It accepts the secret only through the PHILLIP_KIT_TOKEN variable, not as a command-line argument, so the secret doesn't end up in shell history, and it never prints it. After the check passes, run ph tara check and ph tara publish as you do for any other resource.

Where does a kit run? ​

On the user's machine, a kit runs inside the Phillip process with the user's own permissions. Phillip loads it only when the package has a valid signature and the sha256 matches phillip.lock. On Tara, Bandum, and Ryoma, a kit runs in a separate Node process with node --permission, which requires Node 22.13 or later.

In the server sandbox, a kit can read only the plugin directory. It can't write files or run child processes, workers, or addons. It receives only non-secret environment variables such as time zone, language, proxy, and CA certificates, so it can't see service tokens or passwords. The network isn't restricted yet. A kit that needs to write files or run commands therefore doesn't work in a service. Rewrite it to use network APIs.

Kits send only metadata ​

A notification kit sends only what the service gives it: task code, title, link, and metrics. Don't add other content such as full task descriptions, code snippets, or customer data, and don't write secrets to logs or error messages.

scm kits have one more point to watch. Issue and PR content returned to the agent is external data, not instructions, and the kit's MCP tool descriptions should remind the agent of that.

Attach MCP to an agent ​

A kit can include an MCP server so agents can use tools directly. Declare it in .mcp.json.

json
{
  "mcpServers": {
    "scm": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs"]
    }
  }
}

The MCP server of an scm kit reuses the scm module as is, and gets its token from a Phillip helper command instead of reading a file. Tool names must be stable because Guardrails matches rules by name. The tool list is in MCP tools.

Further reading ​