Agent Skills · Field Manual Install GitHub

Diverge. Record. Align.

You watch it diverge. You align it back. Both already happen a dozen times a day — and nothing writes any of it down. So the same correction gets made on Tuesday, and again on Thursday.

The missing part is the middle one. Watch a session below: the agent notices the turns and files them, without a word. Later, you read them together.

session · tuesday idle
00 records
Plate IThe leak

Two of the three already happen. Every day.

The agent diverges and you align it — sometimes bluntly, more often while you are still thinking, saying something half-formed that quietly turns the work. Neither half is the problem. The problem is that nothing between them survives the session, so tomorrow you spend the same minute teaching the same lesson.

01 · Tuesday “hmm — don't we already have something for that?”

The agent complies at once and the work continues. Nothing is written down, because nothing asked for it to be.

02 · The session ends

The transcript keeps what happened. It does not keep why the first way looked right — and that is the only part that would have stopped it happening again.

03 · Thursday “hmm — don't we already have…”

Same turn. Same correction. The cost is not the minute you spend; it is that you will spend it forever.

Plate IIThe mechanism
The three stages: diverge, record, align A conversation line forks where the user changes direction. A note drops from the fork into a tray. Later the tray's contents fan out into a hook, an AGENTS.md file and a global CLAUDE.md. STAGE 1 — DIVERGE where it was going WHERE YOU TOOK IT YOU SPOKE a redirect, or a hesitation STAGE 2 — RECORD THREE LINES · NO RULE written silently no pause, no question .agents/divergences/ they accumulate STAGE 3 — ALIGN A HOOK AGENTS.MD CLAUDE.MD you decide, in conversation the rule lives here — and nowhere else
Fig. 1 — The agent judges the moment and writes the note. You are not asked, and the conversation is not interrupted. Nothing is interpreted until Stage 3, when the whole pile is in view at once.

A record holds no rule. One moment is thin evidence.

Ask an agent to write the rule the instant it is corrected and it will write an absolute — drawn from one bad afternoon, and obeyed by every session after. So a record states only what happened: what the work was, what the agent did and why that looked right, and where you took it. Meaning is found later, where many records can disagree with each other.

Plate IIIAnatomy of a record
--- date: 2026-08-14 · session: 4f21c9 ---
Context. Fixing the timezone on invite emails. What I did and why. Reached for the timezone library I knew handled this cleanly. I never checked what the project already pulls in. What you wanted. “hmm, hold on — don't we already have a date library in here for billing?”

Context

Where the work was standing. One sentence — enough to place the moment months later.

…and why

The load-bearing half. A transcript keeps what the agent did; nothing anywhere keeps why it seemed right. Only the session that lived it can write this line.

What you wanted

Your words, quoted where they carry it. A paraphrase is already an interpretation, and it is the one most likely to drift from what you meant.

Plate IVThe alignment

Days later, the pile is worth reading.

Nothing has interrupted you since. Now you run /align, and it reads the records together — the only place a pattern can appear. It reports what it found, and you decide what becomes a rule and where that rule lives.

/align · .agents/divergences/ waiting

Two records are waiting, from the session at the top of this page.

Plate VWhat it looks for

Records are grouped by what they keep saying, not by the task they came from. Three shapes are worth finding, and they are not all rules.

A repeated move

The same wrong turn, in different tasks. This one is straightforwardly a rule.

→ becomes an instruction

A repeated gap

The same thing the agent kept not knowing. Worth more than a rule: it says what to establish before any work starts.

→ opens the file

A repeated misreading

Your words meant one thing to you and another to the agent. Not a rule at all — it is information about how you ask.

→ changes nothing in the repo

The rule lives at its destination and nowhere else. The record stays your own note, in your own half-formed words, and it stays out of git unless you decide otherwise. What the repository keeps is the line you agreed on.

Try it

Two commands.

One to fetch the skills, one inside the project you want them watching. Nothing to clone, nothing to build, no account anywhere.

macOS, Linux and Windows alike — these are markdown files, not a program. An experiment, and offered as one: run it for a week and see whether the records say anything you did not already know.

  1. 1

    Fetch the skills

    npx skills@latest add franciscohermida/skills

    Asks which skills you want and which agents to put them on — Claude Code, Codex, Cursor. Add -g to install them for every project on the machine.

  2. 2

    Open a project and point it at them

    /setup-divergences

    Writes one block into AGENTS.md and one line into .gitignore. That is the entire footprint — delete those two by hand and it is gone.

What lands in your project

Three markdown files — the skills — go wherever your agent keeps them. Nothing else runs. /setup-divergences then adds one block to AGENTS.md, one line to .gitignore, and creates .agents/divergences/ the first time a record is written.

The records are yours: plain markdown, ignored by git unless you decide otherwise, and never sent anywhere. Removing the block and the folder removes the whole thing.