An agent works from written instructions, and the OpenCMS project showed that a good enough set of them lets an agent edit a large institutional website. This section is about what happens to such instructions after they ship: how they get corrected, who corrects them, and how the correction reaches the next person who uses them. The machinery described here is not tied to any one set of instructions. It works for every skill in the same way, and the pages of this section use the OpenCms skill as their running example because it is the one in daily use.
The problem
A skill is a written procedure an agent follows: a document, sometimes with helper scripts, that says how to do one kind of task. The OpenCms skill , the running example of this section, is one: it tells an agent how to edit pages on the university website, which steps are safe and which are not, and where the pitfalls lie.
A procedure for a complicated task is never right the first time. It was written against a system that changes — the software the skill drives gets upgraded, its documentation is rewritten, a helper tool changes its output — and it drifts. Some sentences are wrong. Some allow two readings, one of which fails. Some questions it does not answer at all.
The agent following the skill is the best witness to that drift. It knows which line it was reading when a command failed, and what that line led it to expect. Every place where the skill was wrong, ambiguous or missing is what we call friction. In an ordinary session, friction is lost: the agent finishes the task, the session ends, and the next agent hits the same line.
The solution
The solution is a loop that carries what the agent noticed back into the skill, with two people in it at fixed places: the user, who decides whether a finding leaves their machine, and the maintainer, who decides whether the skill changes. The maintainer’s work is itself mostly done by an agent, one that runs a maintenance skill under a person’s supervision, so that the person reads and decides while the agent reproduces and patches. The following diagram shows the loop:
While the agent works, it keeps a friction log: a running note of each place the skill let it down, with the command it ran and the output it got. Nothing leaves the machine on its own. At the end of the task the agent shows the log to the user, and only if the user asks does the agent send a reviewed, scrubbed version to a small hosted service, the report tracker.
A maintainer reads the tracker, reproduces each finding, and decides; in
practice the reading and reproducing is done by the maintainer’s agent, and
the person supervising it takes the decision. Some reports are wrong; some
describe the system the skill drives misbehaving rather than the skill; some
are real. The real ones become a change to the skill and a new release.
Every release carries a calendar version — a date plus a counter, of the
form YYYY.MM.DD.N — so a later report can say precisely which copy of the
instructions it was following, and a later agent can check whether the thing
it has hit was already fixed.
What you gain from the loop
Complicated tasks can be learned. A skill starts as a best effort and becomes a tested procedure, one reported failure at a time. Knowledge that would otherwise live in one person’s head — or in one lost session — ends up in the document.
The skill gets polished, not padded. Each report points at the exact sentence that failed. The maintainer corrects that sentence and leaves the parts that never bite alone.
The skill adapts. When the system, its documentation or a tool changes, the next session notices, files a report, and the skill catches up. The loop is the maintenance plan.
The skills in the loop so far both come from the OpenCMS project . The first is the published, generic OpenCms skill, which applies to every university site on the shared template. The second is the institute’s own site skill, an unpublished companion that knows one institute’s pages and habits, such as the semester rollover of the lecture pages and the team page. The site skill reuses the generic skill’s reporting rules, and a finding about the institute’s pages is filed against the site skill, not the generic one. The tracker itself knows nothing about either: it is a small web service that stores reports against whatever skill name and version they carry.
The report tracker is available to university members on TIK GitHub under AGPL-3.0-or-later.