The Rules We Wrote for the Agent, Not the Human

Pixelkiln ships two sets of instructions now: one for you, and one for whatever’s driving the CLI on your behalf.

While double-checking a fact for the last post, we ended up looking at the sync history for Pixelkiln’s agent skill, mostly out of curiosity about whether it had gone stale. It hadn’t. There was already a commit mirroring today’s 0.48.0 release into it, cut by a scheduled job that checks Pixelkiln’s public releases every hour, seven minutes past the hour, for anything new.

That skill hasn’t come up in either of the last two posts, and it should have. It isn’t documentation. It’s a second, separate set of rules, written specifically for an agent operating Pixelkiln on someone’s behalf, and it says no to some things a human operator would do without a second thought.

A README is for a person. This is for something else

SKILL.md follows the Agent Skills spec: a short block of working rules an agent reads before touching the tool, separate from anything aimed at a human. Pixelkiln’s version opens by naming what it’s for: treat generated pixel art as build output, report the cost before submission, stop for human review, record the source and output hashes. Then it gets specific.

What it won’t let an agent do

The rules read like a list of ways an agent could technically get the job done while quietly making things worse. A few, verbatim from the source:

• “Submit paid work only when the user has authorized generation. Always pass an explicit –budget no higher than the authorized estimate.”
• “Leave visual selection to the local pixelkiln pick review page unless the user explicitly provides a selection rule. Closing it applies nothing.”
• “Never inspect, print, or commit provider credentials.”
• “Do not regenerate recoverable work. Follow the exact zero-cost action printed by plan: poll, pick, fetch, or restore.”
• “Never commit .env.local or .pixelkiln/ cache data.”

None of these are exotic. They’re the specific mistakes that are easy to make when something can act fast and doesn’t get tired: closing a review page and assuming the defaults applied, regenerating instead of restoring because restoring means reading one more command’s output first, paying for a whole new object because reading the lockfile felt like more work than just asking the API again.

The smallest workflow it reaches for

For ordinary work, the skill tells an agent to prefer four commands, in order, over anything more elaborate:

pixelkiln doctor --dry-run
pixelkiln plan
pixelkiln gen --budget <approved-provider-units>
pixelkiln audit --check

pixelkiln doctor --dry-run
pixelkiln plan
pixelkiln gen --budget <approved-provider-units>
pixelkiln audit --check

doctor catches structural problems before plan has to. plan is the free step that says what a run would actually cost, and for what’s already sitting around unclaimed, what’s free to recover instead. gen spends only what the human approved. audit closes the loop by measuring the result instead of trusting it. The staged commands underneath that pipeline, submit, poll, pick, and fetch, exist for resuming a job or debugging one phase, not for a normal run; the skill is explicit that plan‘s printed next step is the one to follow, not a reason to start improvising with the individual stages.

The cheaper move, written down as a rule

Some of the rules are just the project’s own cost lessons, encoded as instructions instead of left as things you’d only know from reading the changelog. Before drawing an east-facing animation loop from scratch, the skill tells an agent to check whether mirroring the west-facing one already covers it, since a mirror is a free horizontal flip and a fresh loop is a real generation. Before drawing a character base from a text prompt, it says to ask whether the user already has a south-facing reference sprite, since referencing one costs 1 generation on the pro-flash engine at 64px against the price of drawing blind. Both are the same idea the whole project runs on: check what already exists before paying to make more of it.

A lean router, not an essay

The whole file is 127 lines. It stays that short by refusing to explain any one provider inline. Instead it routes: “read only the reference needed for the current decision,” then a plain list of which file answers which question, PixelLab configuration and account operations in one, Retro Diffusion’s USD budgets and animation limits in another, a self-hosted ComfyUI workflow in a third, Scenario’s two-part credentials and compute-unit ceilings in a fourth, plus separate references for revisions, quality profiles, and mixed-provider setups. An agent working a PixelLab-only project never has to load the ComfyUI reference at all.

It also carries an honesty check that matches how the providers actually stand today: describe Scenario as experimental, since only one model profile is live-tested; don’t call Retro Diffusion production-ready until representative multi-candidate, tileset, GIF, and spritesheet runs actually pass. The skill is telling an agent not to oversell the same providers the last post was careful not to oversell either.

It doesn’t live in one place

The skill’s source of truth is skills/pixelkiln/SKILL.md inside the Pixelkiln repo, and it ships three ways from there. It’s in the npm package (skills is in package.json‘s files allowlist, right alongside dist and docs). It’s readable straight off GitHub. And it’s mirrored into a separate personal skills marketplace, gfargo/skills, bundled into a “games” plugin alongside a card-game library for the terminal.

That mirroring isn’t a manual copy-paste chore. A scheduled workflow in gfargo/skills polls Pixelkiln’s public releases hourly, compares the latest tag against a stored version marker, and syncs the skill and bumps the plugin version whenever they differ, all without needing a token that could write back to Pixelkiln itself. Installing it looks like this:

npx skills add gfargo/skills --skill pixelkiln

npx skills add gfargo/skills --skill pixelkiln

or, as a Claude Code plugin:

/plugin marketplace add gfargo/skills

/plugin install games@gfargo-skills

/plugin marketplace add gfargo/skills

/plugin install games@gfargo-skills

Same release automation from the last post, quietly doing a second job it wasn’t originally asked to do.

The provider-specific reference docs the skill points agents to, for PixelLab, ComfyUI, Scenario, and Retro Diffusion, are probably where the next round of this needs to happen; the core rules read solid, but they’ve had less real usage against an actual autonomous agent than the CLI itself has had against a human. If you’ve written rules like these for something you’ve built, I’d be curious how you decided what to hard-block versus just flag.