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?
| Form | Declared in | Used for |
|---|---|---|
| Phillip plugin | metadata.forge.phillip | scm, notify, and tracker connectors that Phillip and the services load |
| MCP server | .mcp.json | Lets agents in Claude Code call tools |
| Hook | hooks/hooks.json | Checks or blocks within a Claude Code session |
| Guardrails policy | metadata.forge.guardrails | Safety 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.
provides | Capability group | Functions | Called by |
|---|---|---|---|
scm | task | me, issue, issues, assign, setStatus, defaultBranch, pullForIssue, createPull, review, comment | Phillip (ph bandum), the MCP server in the kit |
report | createIssue, issuesByLabel | ph bandum bug | |
sync | repoInfo, milestones, changes, events, pull, dirs, file, putFile | Bandum, Ryoma | |
notify | send | check, send | Tara, Ryoma |
tracker | task | me, sprints, tasks, task, events | Ryoma |
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.
kit-notify-teams/
├── .claude-plugin/
│ └── plugin.json
├── phillip/
│ └── notify.mjs
├── docs/
│ ├── cai-dat.md
│ └── su-dung.md
├── README.md
└── CHANGELOG.mdIn plugin.json, declare the metadata.forge block like this.
{
"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.
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.
ph kit check ./kit-notify-teams --set channelName=ban-tinAdd --live to make real calls: me() for scm and tracker, or check() for notify.
PHILLIP_KIT_TOKEN=<secret> ph kit check ./kit-notify-teams --set channelName=ban-tin --liveTo send a test notification, add --send and --to.
PHILLIP_KIT_TOKEN=<secret> ph kit check ./kit-notify-teams --set channelName=ban-tin --send "test" --to owner@example.comThe 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.
{
"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.