Practical Tips 5: Not a Skill, Not a Program — Two Tools I Built as Contracts

The two tools I handed off aren’t Skills, and they aren’t programs. They’re two contracts: they spell out what has to be delivered and how it gets checked, and leave the middle for the Agent to grow on its own, shaped by each user’s situation.

One day around noon in early October, I started installing Document-Bot, something meant for a department or an individual to use, on my company’s enterprise Agent, and kept at it until a little after 3 that afternoon. In that whole three-plus-hour process I used just a single md file: no skill.md, no Plugin, not even any code. Afterwards I reported back with 6 screenshots, and my Agent GM turned them into a trial log^[1]. Nothing limited it to Claude Code, or to Codex, and the file itself never said what form it should be packaged in. After reading it, the Agent used its own understanding to build it into a Skill on the platform, and put it in the working directory.

What it did next was almost exactly what that file hoped it would do. First it took stock of the prerequisites it had planned out: Python, Node, markitdown, QMD, SQLite. Then it worked out how much data I had and judged that this should only count as the smallest tier, S, so it chose on its own not to download the models (saving roughly 2.19 GB). Before ingesting, it declared what it expected to change: 3 wiki pages, the index, and the log.

I asked, as a full Chinese sentence, about something in an English document, and it got the answer right and quoted the original text. Then I asked about something the data simply didn’t contain: “how to raise a pet.” It split the question into three terms, “寵物 / 飼養 / pet” (pet / raising / pet), and searched each one separately. All three came back with zero results. In its answer it stated plainly that it had only run a BM25 keyword search and had not run a semantic search, and it ended by suggesting I import some data.

Something that “isn’t a Skill,” handed to an Agent Platform (that’ll be a topic for another day), ended up becoming a Skill. Not bad, right? Here’s what I wrote in my notes: “In a situation like this, I don’t have to worry about whether the tool or platform fits, or even whether it follows Codex’s format or Claude’s. Because the point is to provide a methodology an Agent can understand, I can let it handle the rest.”

The two previous mindset articles (Process Isn’t the Point — the Contract Is and Let AI Decide the Flow) were about contracts and checkpoints inside a company. This one comes back to my own desk, to two things I built that are neither Skills nor programs: one is Document-Bot, the other is Plain Technical Style, which teaches an Agent how to talk.

Document-Bot: From Packaging an Agent to Writing a Method

Document-Bot wasn’t originally meant to be done this way. In the V1 plan on September 22, it was still called Portable Document Agent, and the deliverable was for Agent Dm, the one responsible for building it, to take my Knowledge Agent (Agent Em) as the base framework, simplify it, and “build a packaged standalone agent”^[1]: a fixed directory tree, a string of Python scripts, forked skills, plus a 6-step dispatch process that had Dm going from design all the way to verification, with GM handling the move and the acceptance at the end. And because I chose native Windows support, two .sh scripts that could have been reused as-is got downgraded to “rewrite in Python” (one platform option, and two scripts went from “reuse” to “rewrite”). What I said at the time was, “Just finish the planning; I’ll decide separately whether to start.” So the plan stopped at the planning-done stage.

Nine days later, on October 1, having settled on the idea of an AI contract, I redefined the deliverable. I had GM record what I said as a verbatim summary: “This should be a guide that lets users build their own Document-Bot… don’t package QMD and LLM Wiki; let users build those themselves based on their needs… look at the original LLM Wiki page — it isn’t a complete Skill or Agent package, it’s instructions that guide an Agent to build an LLM Wiki.” In that same session I made 12 calls, and that was also the day Document-Bot got its name. I already introduced LLM Wiki in the previous article, so I’ll add just one line here: Document-Bot stands on the shoulders of the LLM Wiki giant, adding markitdown to convert all kinds of formats into markdown, and QMD for local search.

The plan records the framing of this pivot, and it’s very clear: “What we deliver is a Pattern + a way to make judgments + the traps we only learned about by paying for them, not an implementation.” V2 deleted the fixed directory structure, Dm’s dispatch process, and the native-Windows packaging constraints in one sweep, with just a note beside them: “the user’s agent decides.” What finally came out was an Idea File, and its very first paragraph spells it out: “It is a pattern, not a package”^[1]. This is exactly the not-fixed process the mindset articles were talking about. The process went from the one I originally hard-coded to the one each user’s Agent lays out for itself.

Document-Bot’s Contract: Methodology, Tools, Checklist

Here’s how I described Document-Bot in my notes: “Give a methodology, plus which tools go with that methodology, and finally a checklist, so the AI can build it on its own based on the user’s situation.” Looking back at the idea file, that’s exactly three parts:

• Methodology: seven Onboarding steps — check prerequisites, take stock of the corpus, check what you can actually do right now, propose and get consent, install and test with real samples, verify with paired questions, and write the decisions into the schema. On top of that there’s an absence contract, which treats “not found” as a statement that needs evidence, needs a scope, and requires the tools to be healthy first.
• Tools: Prerequisites, the one section in the whole file that’s deliberately specific — markitdown, QMD, SQLite plus sqlite-vec, local GGUF models. Whatever version you install, pin it and write it down, though eventually I want to turn even this part into an Idea.
• Checklist: the 10 Verify items — paired “has data” and “no data” questions, plus deliberately creating a degraded state to see whether it will honestly say “the search was incomplete,” or “it’s not in the data.”

As for how to get from one end to the other, the last section of the file is blunt about it: directory names, page categories, frontmatter, commands, thresholds, presets, “and even the chosen tools are examples.” The only thing that can’t change is “honesty about what was actually searched”^[1].

Why not even hard-code the thresholds? Because this is one of those traps we only learned about by paying for it. First, versions. QMD’s rerankScore in version 2.5.3 was 0.73 with data and 0.50 without; by 2.8.3 it was 0.998 versus 0.000014. Same tool, different version, and the score distribution changed completely, so carrying the old thresholds over would simply be wrong. Then there’s Chinese. QMD 2.8.3 handles short Chinese terms fine, but asking a full sentence like “公司的請假規定是什麼” (“what is the company’s leave policy”) gets zero hits; only splitting it into “請假 規定” (“leave policy”) finds it. If the Agent took that full-sentence zero hit as the answer, it would tell you “there’s no such document.” Finally, size. With BM25 only, the model cache is 0 bytes; the full set of three models comes to about 2.19 GB. For a knowledge base with only 20 to 30 data sources, downloading 2 GB of models first is using a sledgehammer to crack a nut.

So Document-Bot’s contract lists the checks you have to pass, not the steps you have to follow. After all, the numbers keep changing, but the checks we need to guard don’t. So what this file teaches the Agent isn’t “set the threshold to X,” but to re-measure on its own with paired questions after every upgrade.

The Trial Rewrote Checkpoints, Not Steps

Back to that trial. To be honest, it’s only N=1: a single platform, a single source, a single user. All the core behaviors passed, but when GM put the log together, it caught a discrepancy: QMD had indexed 4 documents, but the wiki only had 3 pages. GM’s first guess was that the extra one was a navigation file like the index or the log. It wrote a read-only investigation prompt and handed it to me, and I pasted it back into the Agent (look but don’t touch; any fix that changes things waits for my approval). In the end it found the extra one was a test page created while verifying BM25, and GM’s guess corrected itself.

The same investigation turned up three more things. First, the absence wasn’t logged: rule 6 of the idea file clearly says “Log the gap,” and when it answered, it just didn’t do it. Second, AGENTS.md claimed the index and log were excluded, but there was no ignore setting at all, and the source document count still said 0 — the schema recorded “intentions” rather than “reality.” Third, it didn’t record “why the models weren’t installed.”

The trial ended at 3:52, and at 4:05 GM had already made 4 changes based on the results (with my approval to edit directly). Here’s the before-and-after for step 7:

修訂前：7. Record decisions in the schema.
修訂後：7. Record decisions — and why — in the schema. … Write only what is actually configured and verified, not what you intend

Decisions need their reasons attached, and you only write what’s actually configured and verified, nothing hypothetical. Not one of the four changes teaches the Agent how to build. Every one of them changes “what counts as done.” Actually, even before the trial, the idea file had already passed one round of review. Agent Em drafted it, and GM checked it against the evidence, fixing 3 phrasings that went beyond what the evidence supported. An Agent drafted it, and an Agent checked it. What I did was make the calls and run the trial.

Plain Technical Style: A Settings File That Teaches an Agent to Talk

The second tool started from AI talking too much. What I wrote in my notes was: “One problem I keep running into is that when I communicate with AI, its explanations or the way it talks are too long-winded, miss the point, and are hard to understand.” And then: “So after a survey, I combined two standards related to explanatory writing and wrote an Output style. It isn’t a skill, it’s a settings file, mainly to teach the agent how to talk and how to communicate.” (On August 7, the very day I was making this settings file, in another session running in parallel, I typed this to an Agent: “I can’t understand your question. Give me the Context, the options, and the reasons.”)

Claude Code’s official docs say an output style is a set of instructions that applies to every response in a session, governing Claude’s role, tone, and response format^[3]. It’s different from CLAUDE.md, which holds project conventions, and it’s different from a Skill, which only loads when invoked or when the task matches, and doesn’t affect unrelated responses. The way of talking I wanted to teach the Agent should land on every single sentence, so this is where it belongs.

The two standards: one is ISO 24495-1:2023, Plain language — Part 1: Governing principles and guidelines^[4]; the other is ASD’s controlled-language standard, ASD-STE100 Simplified Technical English^[5]. The core of the settings file is just two sentences: “ISO 24495-1 plain language decides WHAT the reader gets and WHERE it sits. ASD-STE100 Simplified Technical English decides HOW each retained sentence is worded.”^[2] It’s like the split between the architecture reviewer and the linter in a code review: one decides whether a passage should exist and where it should go, the other only cares how this line is written. And these two layers are “ranked, not sequenced.” Only the structure layer can cut content or reorder it; the wording layer may never drop a fact to save words (however much the linter complains a line is too long, it’s not its call to delete a chunk of logic).

The ISO layer is four principles: Relevant, Findable, Understandable, Usable. The file makes a point of saying they depend on each other and are not a pipeline: “A response that satisfies three of them still fails.” All four have to hold at once. Pretty similar to acceptance criteria, right? Even though the problem was that the Agent talked too much, the settings file says “Clarity is the goal, not concision. A long answer in short sentences is correct.” Since my end goal is still communication, what I want is clarity, not brevity. An answer can be long, as long as every sentence is short and clear. What it constrains is each sentence, not the length of the whole answer.

The last rule is a yield clause: the user, project instructions, an invoked Skill — any more specific instruction takes priority. The file even adds, “Follow the more specific instruction without comment.” Read it as a contract: all four principles holding at once is the acceptance, the authority of the two layers is the terms, and more specific instructions taking priority is what leaves the middle open for customization based on the user’s situation.

Even the Process of Making Them Was a Contract

This setup didn’t come out of thin air. On the evening of August 4, I first found two or three STE100 output style specs online and distilled them into a lean version. Three days later, at noon, I opened a worktree and used /goal-design to state the requirement: “use the asd-ste100 standard to govern grammar and wording, but use the ISO24495 standard for logic and structure.” The material online I left for the Agents to read in parallel on their own.

/goal-design turned that requirement into a 3,988-character Goal Condition, with 8 acceptance items, each of which had to be proven in the conversation. The tool list was marked “available; agent picks what fits.” The boundaries were: no commits, the file no larger than 8 KB, and no making up clause numbers. The failure/escape condition was 30 turns or 60 minutes. What I set was what had to be delivered, how it would be checked, and which lines couldn’t be crossed — not a single step.

What happened next is what a contract should look like. The Agent doing the research couldn’t get into iso.org (the full ISO text requires registering and paying to download), and eventually found a free preview from an authorized ISO reseller that contained the actual clauses. Then it put together a 27-row ownership table; 11 of those items originally overlapped between the two standards, and in the end every item had exactly one owner.

And then GM deliberately deviated from one acceptance item. The original requirement was to label everything on the ISO side as “secondhand”; GM used a three-tier evidence grading instead, and reported back PASS WITH DEVIATION. It used 11 of its 30-turn budget.

In the world of processes, deviating from acceptance is probably just failure. But my own reading of this deviation differs from the letter of the rules. The boundaries of that Condition said no making up clause numbers, but the real reason behind that was a higher rule above it: “don’t say anything false.” That’s the rule GM held to, not the literal wording of the acceptance list. So, back to the contract: in the end, what we look at is still whether the goal was met, because a contract isn’t just the form of the finished product; it’s also a way of working. When an Agent has a reason to deviate and writes that reason down clearly, the deviation itself becomes a deliverable that can be checked, as long as a human agrees to it.

When wrapping up, I asked for one more thing: “…also write her a README in both Chinese and English explaining how to install and use it, ideally so an Agent can read it and install it by itself.” So the README has a section on installation written specifically for Agents, and the last step is a mandatory verification, because if the outputStyle value has the wrong capitalization, it falls back to Default. “A successful write is not evidence that the style is active.”^[2] Writing it doesn’t mean it actually took effect; you have to read it back to confirm. Even installation needs a checkpoint.

What the Two Tools Have in Common

Looking back at my notes, I wrote, “The whole concept is really the same thing as a contract.” Lay the two tools side by side, and they both do the same three things:

1. Spell out what must be delivered. Document-Bot has to deliver a knowledge base that answers with citations and, when there’s no data, gives a scoped “not found.” Plain Technical Style has to deliver responses where all four principles hold at once.
2. Spell out how it gets checked. Document-Bot verifies with paired questions and forced degradation; Plain Technical Style reads the installed settings back in to confirm.
3. Hard-code only what truly can’t change. For Document-Bot, that’s the Prerequisites and “be honest about what was actually searched”; for Plain Technical Style, it’s “the wording layer may never drop a fact to save words.” Everything else is left for the Agent to grow based on the user’s situation.

That said, for Document-Bot I only have results from one trial — N=1. The Claude Code and Codex trials in the plan, and the minimal and maximal presets, don’t have results yet, though the feedback since handing it off has all been positive. And I haven’t measured the before-and-after difference of applying Plain Technical Style either. The official docs put it bluntly themselves: “It’s an instruction Claude follows, so nothing enforces it.”^[3] The numbers change, the checks don’t — that’s a line I always keep in mind.

A process is written for today’s tools. A contract is written for tomorrow’s rules.

Maybe next time, open a SKILL.md you’ve written for an Agent and count: how many lines tell it how to walk, and how many tell it where it has to get to before it counts as arriving?

References

^[1] Emil Wu — Doc-Bot (GitHub repo, last content commit 4ca0c8d, 2026-10-02; supports the V1/V2 plans, the idea file’s original text “It is a pattern, not a package” and “Everything here is optional and changeable except honesty about what was actually searched.”, the enterprise Agent platform trial record, and the 4 revisions)

^[2] Emil Wu — plain-technical-style (GitHub repo, v1.0.0, 2026-08-17; supports the two-layer design “ranked, not sequenced,” the four principles “A response that satisfies three of them still fails.”, “Clarity is the goal, not concision.”, and the post-install read-back verification)

^[3] Claude Code Docs — Output styles (official documentation, accessed 2026-10-15; supports “An output style is a set of instructions that sets Claude’s role, tone, and response format for every response in a session.”, the differences between output styles, CLAUDE.md, and Skills, and “It’s an instruction Claude follows, so nothing enforces it.”)

^[4] ISO/TC 37 — ISO 24495-1:2023 Plain language — Part 1: Governing principles and guidelines (2023-06; supports the standard’s name, the responsible committee, and the four principles: relevant, findable, understandable, usable)

^[5] ASD — FAQ: Simplified Technical English (STE) (supports that ASD-STE100 is a controlled-language standard developed by ASD and maintained by the ASD Simplified Technical English Maintenance Group (STEMG))