agentleFS
MichaelTarasov02MichaelTarasov02/Trail/skills/trail-distil/SKILL.md

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".

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
  1. Very specific:

    Write the rules in the language the repository's existing agent-rules file uses.

    line 17
  2. Distinctive:

    If not, keep looking for what the corrections were really about — the vague version is almost always three specific rules wearing one coat.

    line 83
  3. Distinctive:

    Read it first and match its structure.

    line 92

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. The rules worth adding — as a numbered list, ready to approve
  2. What they cost — anything that would constrain work the team may want to do
  3. What was deliberately not promoted, and why
  4. 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
SignalStrength
The same правило line three or more timesstrong — promote it
Twice, in different areas of the codestrong — the point is that it generalises
Twice in the same fileweak — 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 -rn

A 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.

PatternWhat it says
[agent] dominatesre-examine those first; several are defaults nobody chose
[operator] dominatesthe operator is deep in the detail — likely slower than it needs to be
[project] dominatesthe 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 ruleA 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/null

Read 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.