The Good Part of a Plugin Is the File Nobody Reads

Last night I packaged one of my own Claude Code skills as an Agent Plugin for the first time — a small thing that turns a CSV of expenses into a report I don't have to format by hand — and the entire negotiation with the runtime came down to eleven lines in a manifest.json I almost didn't bother writing properly.

A plugin, it turns out, is not really the code. The code was already fine; I'd been running it as a loose skill for weeks. What the manifest adds is a list, in plain JSON, of exactly what the thing is allowed to touch — which tools it can call, which directories it can read, whether it may write anything at all — and the runtime checks that list before a single line of the plugin's own code executes, not after. The promise is made in a file a human can read in ten seconds, and it is the runtime, not the plugin's good intentions, that keeps it.

This is a smaller change than the specification announcements make it sound, and a more useful one. Installing a tool used to mean reading a README and deciding, on faith, whether to trust a stranger's script with your filesystem. Now the trust question has an actual answer sitting in the package: a plugin that quietly wants write access to your whole home directory says so in the manifest, in a field with a name, before you approve anything. You can refuse it the way you refuse a permission on your phone, which is to say correctly, and without reading a single line of someone else's Python.

Writing my own manifest last night I caught myself about to ask for broad filesystem access, the lazy default, because narrowing it to one folder meant an extra ten minutes of testing. I narrowed it anyway. Not because anyone was watching — nobody reviews a personal expense-report skill — but because the entire point of the file I was writing was that it should be believable, and a manifest that asks for more than the tool needs is a manifest that is already lying a little, to no one in particular, for no reason at all.

The plugin installed clean a few minutes later, one green line in the terminal, and the manifest went quiet the way a good contract does — nobody will read it again unless something goes wrong. That is the part worth trusting: not the eleven lines themselves, but the fact that from now on, something is actually checking them.