The agent skills I wrote
Seven skills that carry what the project learned, so every agent run starts from it. What they hold, how they were built, and how they stay true.
A skill is a pack of instructions and reference files that an AI agent loads when a task needs it. Its short description is always visible to the agent; the body is read only when the task matches. I wrote seven. Together they hold 72 anti-patterns and 40 written lessons, each traced to a failure that really happened.
The seven
Platform change protocol
How any agent changes the order platform: the work-packet contract, what counts as done, release and hand-brake rules, and how two developers share one codebase.
ERP and warehouse data access
Read-only SQL and service-API rules: four answer states, probe columns before querying, run the ERP's own approval queries, never read a missing price as zero.
Locked-desktop deployment
Shipping to a no-admin, multi-session Windows host: per-person services, scheduled-task watchdogs, signed self-updating bundles, sealed credentials, and the shell traps found on the way.
Tool-building standard
A seven-point checklist before building, an acceptance triangle (offline tests, real requests, real data) and the 72 anti-patterns.
When to build an agent
Four tests before deploying one: an evaluation set exists, people give feedback as part of their work, its errors are visible, and their cost is bounded.
Rulebook update
A weekly update of the whole rule set, drafted with a source for every rule and installed as one package that checks itself.
Work-board integration
Atomic writes to a work-management board, validation before every write, strict matching, and detection for anything that would otherwise be dropped in silence.
Where they came from
July 2026, four skills. My instruction file had grown into one long document that every conversation carried. I split it by task: ERP queries, the work board, deployment, and building tools. The tool-building skill started with 20 anti-patterns.
August 2026, when to build an agent. Before building any agent, the same four tests: is there an evaluation set, does feedback come naturally, are errors visible, is their cost bounded.
September 2026, the platform protocol. Once coding agents worked in packets, they needed one place that said how packets, reports, releases and the shared codebase work.
October 2026, the rulebook update. The rules changed every week, so updating them became a skill of its own, run on a schedule.
How the rulebook stays true
The skills are one part of three sources of truth, and each has its own job:
- The rules: one instruction document plus the skills.
- The architecture: a separate document for how the platform is built.
- The code: what actually runs. Where a document says something the code does not do, one of them is wrong, and the same round fixes the wrong one.
A few rules keep it honest:
- Every rule carries its source: a dated decision of mine, or a measurement with the report it came from. A rule without a source is not written.
- One fact lives in one place. Every other place points to it.
- A replaced rule disappears from every document. Its history lives in a changelog, not in the text.
- Numbers that drift (counts, versions, names on a list) are never stored in a rule. They are read when needed.
- Candidate rules from the agents do not become rules until I decide.
Keeping the context small
What every session loads is paid for on every turn, so it stays small. Rules move to files that are read on demand, and every move leaves a pointer.
- The always-loaded instruction files went from 27.6k to 12.6k tokens.
- The context loaded at start-up went from 60.5k to 48.1k tokens.
- A read guard refuses to load any file over 30 KB whole. A document index of 502 headings across 23 files and a code map of 3,483 entries across 172 files point to the right lines instead.
How an update ships
Rule changes get the same proof as code.
- The chat model drafts the change, every line with its source.
- A move map lists where every rule went. A script proved 171 of 171 arrived, and an independent sample checked that the meaning survived.
- Changes are exact-text patches. Each old text must occur exactly once, or the patch is refused.
- One model, read-only, checks the draft against the running code once before it is installed.
- The install backs up every file it replaces and checks every file it writes by its SHA-256 hash.
Six of the 72 anti-patterns
- "Nothing found" from a probe that was never shown to find something.
- A failed query treated as an empty answer.
- A script that reports success without reading back what it wrote.
- Code that exists treated as code that has run in production.
- A page that hides a value the server still sends.
- One fact kept in two places, drifting apart.