Session ritual skills

I added a new category to akakika-skills: session rituals. Three plain-Markdown skills that give a working session with a coding agent a shape — an opening move, a closing trace, and one thing learned. spread makes the agent show its options before touching anything. butterfly-effect traces backward from the outcome and keeps only the moments that actually caused it. til makes the agent teach me exactly one thing the session used. None of them write code. They shape the session around the code.

The friction

Long agent sessions have three quiet problems.

At the start, "fix this" is ambiguous, and the agent silently picks one interpretation — often the biggest one. I wanted a typo fixed and it rewrote half the file. Not out of malice. It just guessed, and the guess was expensive.

At the end, the summary is a chronological list where the moment that actually mattered is buried between routine steps. The session produced something great and a summary I could not use. A week later I could not have told you why it worked.

And all session long, terms fly past that I work around instead of learning, because the work gets done either way. I ship real software without a formal CS background, so every session is full of vocabulary I quietly route around — the same snowball I wrote about with WAWE, just smaller and more frequent.

None of these are bugs. They are defaults. The session works, but it leaks understanding.

The idea

Treat the session itself as a thing with a shape: an opening move, a closing trace, and a takeaway. Each ritual is one small SKILL.md with hard rules, because soft suggestions get ignored by both agents and me.

• spread — before improving anything, list 3–5 concrete interventions on the exact input, lightest to heaviest touch, then stop and wait for the pick. No input, no run. No generic capability lists.
• butterfly-effect — at session close, walk backward from the outcome and apply a counterfactual test to every step: delete it mentally — does the result still happen? Keep only the 2–4 forks that survive. It refuses short sessions; an empty trace is more honest than a forced one.
• til — teach exactly one concept from this session, in plain English, two paragraphs max. Never a list. Ends with a greppable TIL: footer line.

What it does

• spread turns "fix this" into a menu: real operations on the actual material, one line each on scope and risk, zero work until a level is chosen
• butterfly-effect writes a small note — 2–4 fork entries, each with "what happened / what it enabled / if not this" — plus a human-only link_reasoning field the agent is permanently banned from filling
• til picks the term I kept dodging, the concept behind a fixed mistake, or the flag that quietly did real work — and explains it so it can be searched
• All three are plain SKILL.md files: they work with Claude Code, Codex, Cursor, and anything else that reads the format

Why I built it

I kept noticing the same three leaks, and each one needed a different size of fix.

The rewrite-everything problem is a scope problem, so the fix is a menu: make the agent name its options and their cost before it does anything. The useless-summary problem is a causality problem, so the fix is a trace: walk backward from the outcome and keep only what actually caused it. The vocabulary problem is a learning problem, so the fix is one thing: make the agent teach me a single concept in plain English, on purpose, every session.

I wrote each as rules the agent has to follow rather than advice it can skip. That is the difference between a skill that works and a preference it quietly ignores.

How it works

Each skill is a folder with one SKILL.md — YAML frontmatter with a trigger description, then the rules. Drop them in your agent's skills directory (or run the repo's install.sh, which symlinks everything).

Then it is three words you already know:

1. "spread" — hand over something to improve; the agent shows its options before touching a thing
2. "run the butterfly" (or "close the session") — at the end of a long session; the agent writes the causal trace note
3. "til" — whenever you want the one-thing lesson; the agent teaches it so you can find it later

The butterfly note saves wherever you keep session notes, named butterfly-YYYY-MM-DD-<slug>.md.

The whole point is that the session leaks less. You pick the move, you see the causes, you keep the lesson — without adding a single extra tool to your stack.

Where it is now

All three are live in the repo under skills/session-rituals/, bringing it to 40 skills in 9 categories. They came out of my personal skills folder, de-branded and cleaned to the repo's bar. I use all three weekly; til is the one I would save from a fire.

Try it

Grab the skills, or just read the three SKILL.md files — each is short enough to take the idea from without installing anything. If you work with a coding agent and want the session to stop leaking understanding, these are the smallest fix I have found.