trail-distil
Skill0 starsChanged 3 months agoMITView on GitHub
Turns repeated operator corrections into project rules an agent reads before working — reads the trail, finds what the operator has had to say more than once, and proposes additions to the repository's existing agent-rules file. Use after a stretch of work, when the same correction keeps recurring, or when onboarding an agent onto a repository that already has a trail. Reads .trail/, proposes edits to CLAUDE.md or the equivalent. Триггеры — "что мы повторяем", "вынеси в правила", "обнови claude.md", "чему научились", "distil the trail".
In this repository3 other files it gives its agents.
- trail-recordSkill
- trailSkill
- trail-whySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Write the rules in the language the repository's existing agent-rules file uses.
- Distinctive: line 83
If not, keep looking for what the corrections were really about — the vague version is almost always three specific rules wearing one coat.
- Distinctive: line 92
Read it first and match its structure.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Distil
The compounding step. A correction recorded once is history; the same correction recorded three times is a project rule that was never written down, and writing it down stops it recurring.
What this converts: the правило line in each CORRECTION entry — the thing the
operator had to say because the model assumed otherwise.
Language
Write the rules in the language the repository's existing agent-rules file uses. Where there is none, use the language the trail is written in.
Answer in the conversation, not only in the file
- The rules worth adding — as a numbered list, ready to approve
- What they cost — anything that would constrain work the team may want to do
- What was deliberately not promoted, and why
- Where they would go — the existing file, not a new one
Find the repetition, do not invent the rule
grep -rhA3 '^- CORRECTION' .trail/entries/ | grep '→ правило:' | sort | uniq -c | sort -rn
grep -rh '^- DECIDED \[agent\]' .trail/entries/ | sort | uniq -c | sort -rn| Signal | Strength |
The same правило line three or more times | strong — promote it |
| Twice, in different areas of the code | strong — the point is that it generalises |
| Twice in the same file | weak — it may be one quirk, not a rule |
Once, marked разовое | not a rule; leave it |
The threshold is repetition, not severity. A dramatic one-off correction is a story; a boring correction that recurs is what actually costs the team time, and it is the one worth a permanent line.
The ratio is a finding even when no rule crosses the threshold
Report this every run, before the rules:
grep -rho '^- DECIDED \[[a-z]*\]' .trail/entries/ | sort | uniq -c | sort -rnA trail dominated by [agent] decisions is the normal result and the uncomfortable
one. It means the model made most of the consequential choices and the operator saw the
outcome rather than the fork. That is not a failure of the work — it is what delegating to
an agent looks like — but it decides where a reviewer should spend their attention, and it
is invisible in every commit log ever written.
| Pattern | What it says |
[agent] dominates | re-examine those first; several are defaults nobody chose |
[operator] dominates | the operator is deep in the detail — likely slower than it needs to be |
[project] dominates | the repository's conventions are doing the deciding, which is healthy |
Measured on one trail of two sessions: seven [agent], three [project], two
[operator]. Nothing in the commit messages for those sessions distinguishes the twelve.
Never promote a rule from this ratio. It points at where to look; the rules still come only from repeated corrections.
A rule that cannot be checked is a wish
Promote a correction only if it can be stated as something an agent can verify it has obeyed:
| Not a rule | A rule |
| "be careful with migrations" | "never write a migration without stating how many existing rows change" |
| "match our style" | "copy the shape of the nearest file of the same kind before writing a new one" |
| "do not over-engineer" | "no abstraction with a single call site" |
The test: could someone reading only the rule tell whether a given change broke it? If not, keep looking for what the corrections were really about — the vague version is almost always three specific rules wearing one coat.
Append to what exists, never start a second file
ls CLAUDE.md AGENTS.md .cursorrules CONTRIBUTING.md .github/copilot-instructions.md 2>/dev/nullRead it first and match its structure. A second rules file splits the source of truth, and the half that gets read is decided by whichever tool the next person happens to use.
Where there is genuinely none, propose creating the one the repository's tooling already expects — and say which tool reads it, so the choice is not arbitrary.
Show the diff, never apply it silently
Project rules change how every future session behaves in this repository. That is a larger blast radius than most code changes, and it belongs to a person.
Предлагаю добавить в <file>:
+ <rule>
Основание: <n> коррекций — <entry>, <entry>, <entry>
Цена: <what this now forbids that someone may want>Every proposed rule cites the entries it came from. A rule with no provenance cannot be revisited when it turns out to be wrong, and rules that cannot be revisited accumulate until people start ignoring the file.
Non-goals
- Writing rules from opinion. Only from recorded, repeated corrections.
- Editing the rules file without approval.
- Promoting a single correction, however annoying it was.
- Rewriting existing rules. Propose additions; conflicts with an existing rule are reported as conflicts, and which wins is the operator's call.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

