experience-and-transmission
Skill8 starsChanged 59 days agoMITView on GitHub
The artifact is correct and nobody can use, learn, or read it. Use when every component metric is green but the end-to-end experience is broken, when onboarding is too slow or documentation goes unread, when the observer is inside the system being studied (UX research, dogfooding), or when code is right but unreadable by the next maintainer.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- boundary-designSkill
- causal-auditSkill
- decision-bias-checkSkill
- estimationSkill
- evidence-synthesisSkill
- failure-forensicsSkill
- formal-correctnessSkill
- measurement-disciplineSkill
- narrative-sensemakingSkill
- normative-designSkill
- problem-reframingSkill
- representation-and-possibilitySkill
- structure-discoverySkill
- systems-leverageSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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 44
If no shape above matches, do not force a genius — use a built-in agent with the closest GENIUS: pattern (rules/agent-routes.json, INDEX.md …
- Distinctive: line 49
No contact with an actual recipient is possible or planned — this shape measures arrival, and with no receiving end there is nothing to …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Experience and Transmission
Problem shape: correctness is not the bottleneck — arrival is. The system passes its tests and fails its user, the documentation exists and is not read, the code runs and cannot be maintained, or the thing being studied changes because the studier is part of it. The deliverable is comprehension and use, measured on the receiving end rather than asserted on the producing end.
Relevant geniuses
| Agent | Use when |
| jobs | the product "works" per component metrics but the integrated experience is broken — treat the whole experience as the spec, hunt the seams, edit ruthlessly rather than add |
| vygotsky | onboarding is too slow or too overwhelming, or documentation exists and nobody reads it — locate the zone of proximal development, scaffold inside it, and plan the fading; diagnose the misconception rather than repeating the explanation |
| varela | the observer cannot be separated from the system studied (UX research where the experience is the product, dogfooding, introspective debugging) — run trained first-person observation and third-person measurement concurrently and report their mutual constraints |
| knuth | the program is correct and unreadable — literate programming, writing for the human reader first; and building the tool before using it when no adequate one exists. Entry point is transmission, not performance: for profiling and optimization work, knuth is routed via the performance path, not this shape |
Invocation
- Pick the best-fit agent above. If two or more fit, run
tools/genius-invoker.sh route "<problem>"and take the top ranked match. - Load it:
tools/genius-invoker.sh invoke <agent> "<problem>", then readagents/genius/<agent>.mdin full. - Apply the agent's
<workflow>step by step and answer in its<output-format>. The evidence must come from the receiving end — an observed user, a real ramp-up, a maintainer who was not the author. A claim that something "is clear" asserted by its own author does not satisfy this shape. - Typical chain: varela gathers first-person data without pretending the
observer is outside → jobs specifies the integrated experience from it →
vygotsky sequences the scaffolding that gets people there. Run via
tools/genius-invoker.sh compose varela jobs vygotsky -- "<problem>". - If no shape above matches, do not force a genius — use a built-in agent with the closest
GENIUS:pattern (rules/agent-routes.json, INDEX.md routing rule).
Refuse when
- No contact with an actual recipient is possible or planned — this shape measures arrival, and with no receiving end there is nothing to measure.
- The request is to make the experience feel better while a known defect behind it stays unfixed.
- First-person report is offered as the sole evidence with no third-person measurement alongside it (varela's constraint is mutual, not one-sided).
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.