Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

writing-tools-and-checks

Turns a script that keeps being written into a tool, and a mistake that keeps being made into a check, when one-off scripts pile up for the same question, a tool's options are only learnt by running it, a rule in the docs is broken a second time, a review finds the same kind of fault again, or a check passes without ever having been seen to fail. Looks for an existing tool first, gives a tool one question, its manual in its header, a --help that does nothing else, meaningful exit codes and the project's facts from one configuration; prefers making a mistake impossible in the architecture or the types over a lint rule, a check or text; proves every check by planting the fault it is for; runs checks that need no GPU with every commit and names the others beside the change that needs them. Use with any repository developed mostly by AI agents, and with renderers whose checks need a GPU, whenever a tool, a verify script, a lint rule or a rule of the rules file is written or changed.

HuberyLL · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add HuberyLL/ponlai --skill writing-tools-and-checks

About this skill


name: writing-tools-and-checks description: Turns a script that keeps being written into a tool, and a mistake that keeps being made into a check, when one-off scripts pile up for the same question, a tool's options are only learnt by running it, a rule in the docs is broken a second time, a review finds the same kind of fault again, or a check passes without ever having been seen to fail. Looks for an existing tool first, gives a tool one question, its manual in its header, a --help that does nothing else, meaningful exit codes and the project's facts from one configuration; prefers making a mistake impossible in the architecture or the types over a lint rule, a check or text; proves every check by planting the fault it is for; runs checks that need no GPU with every commit and names the others beside the change that needs them. Use with any repository developed mostly by AI agents, and with renderers whose checks need a GPU, whenever a tool, a verify script, a lint rule or a rule of the rules file is written or changed.

Writing tools and checks

Agents solve the same question again with a new script each time, and each script makes its own mistakes: a sleep where a readiness signal was needed, a lock not taken, an output nobody else can read. A rule written only as text is broken again by the next change whose author never read it. The method is one tool per question, documented where it is called, and every rule that can be checked turned into a check that has been seen to fail.

Rules most often broken without notice

  • Look for the tool before you write a script. If one almost fits, add an option to it; a second tool for the same question splits the fixes between two copies.
  • If a script is needed a second time, or by another task, make it a tool. A truly one-off script stays in the task's scratch folder, never in the tools folder.
  • --help prints the manual and exits before anything else runs: no lock, no browser, no server, no GPU. An agent that starts a tool to read its options must not start the work.
  • Wait on what the system under test reports (a ready or settled signal, a counter of rendered frames), never on a sleep or a fixed count: a fixed wait passes or fails by chance on a busy machine.
  • Prove a check by planting the fault it is for and seeing it fail. A check that has never been seen to fail may check nothing.
  • A list of known exceptions only shrinks. A new failure is fixed in the code, never added to the list, and an entry that no longer applies fails the check until it is removed.
  • Set a check's tolerance from the measured noise of the same thing compared with itself. Never pick it to make a failure pass.
  • A faster check keeps its guarantee: it still compares against the thing it promised (a fresh load, a reference), not against something cheaper that agrees with the change.

The project's facts: the binding

Steps marked "(binding: X)" need facts about the project: its index of tools, the manual's format and the --help helper, the shared modules and configuration a tool reads, its GPU lock and job runner, where checks run and how a rule is recorded. Read section X of docs/bindings/writing-tools-and-checks.md when you reach the step. If the project's AGENTS.md or CLAUDE.md names another file for this skill, that file wins.

No binding: find each fact in the project (its tools folder and any index of it, package.json's scripts, the checks its commit hooks run, a lint configuration, how its tools wait for a page) and ask the user for what you cannot find, above all whether anything else may use the GPU while a tool runs. When the work ends, offer to write what you found as the binding, one section per step.

Workflow

Copy this checklist and keep it up to date:

- [ ] 1. Find the tool that answers the question
- [ ] 2. Decide: an option, a tool or a one-off
- [ ] 3. Write the manual first
- [ ] 4. Build it on what exists
- [ ] 5. Prove it
- [ ] 6. Turn a mistake into a check
- [ ] 7. Register it

1. Find the tool that answers the question (binding: Index)

Write the question in one line ("does a grown page draw what a fresh load draws?"). Look it up in the project's index of tools by question, then read the candidate's manual with --help, never by running it. Search the tools folder for the key words of the question too: an index can lag.

2. Decide: an option, a tool or a one-off (binding: Index)

  • A tool already answers it, but nobody found it (the script was written again because the index and the manual did not name the question): change nothing in the code. Add the question to the tool's manual and to the index.
  • A tool answers a neighbouring question with the same inputs: add an option to it.
  • No tool, and the question has been asked before or will be by another task (a script written a second time, a local copy of one passed between tasks): write a tool.
  • The question is for this task alone: write a script in the task's scratch folder. It is not reviewed, kept or indexed.

If agents have been writing many one-off scripts, count them by question first, and build the tools for the most frequent questions. Before you change a slow tool, measure where it spends its time.

3. Write the manual first (binding: Manual)

The manual is the tool's header comment, written for a colleague who has never met the tool, in this order and each part once:

  1. One sentence: the question the tool answers. Indexes and maps are printed from this line.
  2. When to use it and what it guarantees: what it compares or measures, under which conditions, and its rules with their reasons.
  3. Usage, from the repository's root, and Options (or "none").
  4. What it prints and what files it writes.
  5. Whether it takes a lock, opens a browser or needs a GPU, and its rough cost.
  6. Its exit codes, and what a failure means.

Make --help print the purpose, Usage and Options from that header before any other

Read the complete source ↗