Manifest-driven ServiceNow development

Back in January I wrote about servicenow-skills the idea. This is servicenow-skills the thing that now lives on my laptop and does actual work.

A lot has changed. The part that surprised me the most is how little I “run scripts” anymore.

The moment it clicked

I was halfway through a Tuesday, rebuilding a catalog item for the third time in three different dev instances. Same variables, same UI policies, same client script, same three fields I always forget until the form gives me a red error.

At some point I opened a new file, typed out what the catalog item was supposed to be — the fields, the variables, the policies, the lot — and then walked away while the tool did the actual clicking. It took about eleven seconds.

I remember thinking: I’m not writing a script that makes a thing. I’m writing down what the thing is and handing it off.

That’s the whole shift. It sounds small. It wasn’t.

Chat, spec, manifest, go

The workflow the project settled into has five beats:

Chat → spec.md → manifest.ts → execute → validate → test.

The first two are me talking to Claude about what I actually want. The skill asks questions (every skill has its own question list, which is the part I’m most fond of), and out falls a spec.md — a plain-English description of the thing. Not code. Just: this is a catalog item called X, it has these variables, these are the rules, here’s who can see it.

Then the manifest. That’s a TypeScript file that names every piece of the thing and exactly where it should go. It’s the contract. Nothing runs until I’ve looked at it and said yes, that’s what I meant.

Then execute pushes it at the instance. validate asks the instance whether what’s there matches what I said. test runs a small harness against the thing I just built to make sure it behaves. All three of those are boring by design. Boring is the goal.

Why describing beats running

Scripts are instructions. Manifests are descriptions.

The difference shows up the second time you run the thing. A script that creates a record happily creates a second copy. A description says a catalog item named X exists and looks like this — and the tool figures out whether to make a new one or update the one that’s already there.

That’s the rule I care about most, and I bake it in everywhere: always update the existing one if it’s there, never blindly make a duplicate. It works whether it’s the first run or the hundredth. I can hand the same manifest to dev, test, and prod and not lie awake wondering which one is now subtly wrong.

I cannot overstate how much better this is than carting update sets around.

The shape of the thing now

Last time I counted there were around fifteen skills, each one owning a corner of the platform — script includes, business rules, catalog items, flows, ACLs, UI policies, notifications, REST messages, and so on. Between them they ship something like forty-plus CLI commands, which sounds like a lot until you realise most of them are variations on the same five verbs: schema, execute, validate, test, and a few diagnostic ones for when things go sideways.

I’m not going to list every skill. That’s what the repo is for. The shape I want to convey is: if I’m doing a thing on the platform, there’s probably a skill that already knows the shape of that thing and the questions worth asking about it.

(When there isn’t one, adding a new skill is now a weekend’s work instead of a rewrite. That wasn’t always true.)

Where sndev.io fits

The piece of this I didn’t appreciate until I started writing manifests is how much I lean on sndev.io as a reference layer. When I need to know what fields a sys_script_include actually takes, or which ones the API silently ignores on write, I’m not digging through sys_dictionary on a live instance anymore. I’m reading a clean, searchable version of the schema that someone already did the hard work of extracting.

It sounds mundane. It’s the thing that makes the rest of this writable at all. Manifests need an accurate model of the platform to describe, and sndev.io is where that model lives when I’m not in front of an instance.

The part that still feels weird

I’ve been doing ServiceNow work for years. For most of that time, “getting something done” meant opening a form and typing into it, or opening a background script and running a thing. The muscle memory is deep.

Manifest-driven work rewires that. I sit down, I talk through what I want, I look at the file, and then I let something else handle the clicking. The first week it felt like cheating. The second week it felt normal. The third week I started getting mildly annoyed on the rare occasions I had to open the UI at all.

I didn’t expect that. I thought the win would be speed. The actual win is that I care about the shape of the thing I’m building instead of the sixteen fields I had to fill in to get there.

That’s a better job. That’s the one I wanted.

-D