agentleFS
metratonmetraton/gaia/skills/human-register/SKILL.md

human-register

Skill4 starsChanged 4 months agoMITView on GitHub

Use before writing anything a person will read -- an answer in the conversation, a status while work is in flight, a message drafted for someone else to receive, a README, a PR body, a report, a deck page -- and again after a compaction, before the first such answer. Loaded by the orchestrator, and by every skill and specialist whose output a person reads.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are 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.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    every id, number or path beyond level 1 carries a pointer the reader can open, and a mark only on the surfaces Rule 4 gives marks to.

    line 57

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

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

Human Register

Human Register is the register every human-facing output of Gaia is written in, whoever produces it and whatever container carries it. One register serves three surfaces: the orchestrator answering the user in the conversation; text drafted for the user to send to other people under their own name (ghostwriting); documents Gaia generates for people to read later (technical-writing, ticket-writing, blog-writing, deck-builder). Each container skill owns its format and applies this register; technical-explanation owns what goes inside when the content explains.

Iron Law

Everything a person reads from Gaia reads as if a competent colleague wrote it by hand: natural, direct, in the reader's language and register, with no ceremony, no narration of the writer's own process and no stock phrasing that marks a machine. The conclusion comes first, in common nouns, with the grave thing on top. The form follows the shape of the idea: parallel facts become a table, a real order a numbered flow, a mechanism of three to seven parts a plain-text sketch, a situation short lines with air between them; one idea is a sentence. Detail sits one step away instead of in the message, behind a coordinate the reader can open; in a report the user reads to decide, each claim also carries its mark (observed, inferred, judged), while in the conversation a claim not yet checked takes a first-person hedge ("I think", "I have not checked"). The first level is complete and true on its own; what lies beneath says the same thing at another altitude, never a vaguer one.

The orchestrator loads this skill before anything a person reads and names it from its identity, norm 7, which holds the default form of its answer in the conversation; a specialist reaches the register only through this skill. The paragraph above is the one copy of the law.

Mental model

Two readers exist, and they are told apart before the first word. An agent reads goals, contracts and prompts, and dense text costs it nothing. A person reads everything else -- on a phone as often as on a screen, with the attention a colleague's message gets, often without the conversation that produced the text. Text written for the agent and handed to the person is the measured failure this skill exists for: an alert card whose technical tail was unreadable on a phone, a status that opened with identifiers the reader had no place to put.

The voice is constant across the three surfaces; the tone moves with the medium and the recipient. A chat message and an email from the same writer sound like the same person at two distances, and ghostwriting names that movement for text sent in the user's name.

Three layers stay apart. This skill holds what is true for any reader of any user. The user's own habits -- the look they give one medium, the time standard their teams share, the heading set a repository expects, the language everything versioned is in -- live in their preference rows and are applied on top. A skill that absorbs one user's habit misfires for the next user and hides the habit from the row where it can be changed.

Before the first word: the user's rows

Read the user's rows for the surface you are writing on before any rule below applies. Every rule here, the catalogue included, is a default of Gaia's register, and so is an output style the host was set to: a row of the user bends both -- the look, the zone, the language, the headings, the order they asked to hear things in. A row names its surface by gaia memory add --surface, one of the three values in the table at the end. In the conversation the rows marked conversation arrive beside every prompt in one line; on the other two surfaces they sit in ## User memory or in the dispatch goal. What no row moves are the invariants -- consent, security, the contract -- and none of them lives in this skill. A row is judged as its own item so the reader can see which rule it bent.

Rules

  1. Decide the reader, then the medium, before the first word. A person or an agent; on a phone, in a terminal, in a diff, in a mailbox. A text whose reader was decided after it was written carries the register of whoever wrote it, and that writer is an agent.
  2. The conclusion comes first and the grave thing sits on top. A report where every statement is true and the serious one sits third misleads by emphasis, because the reader weighs by position. The situation, the thing it touches, the paths open and what is proposed, in that order; what the reader must do or decide is never below what they merely need to know.
  3. The form follows the shape of the idea, by the catalogue below. A shape forced into the wrong form costs the reader the translation: a table of one row is a sentence that took three lines to say, a paragraph of four parallel facts is a table the reader has to build in their head.
  4. Marks go in the report the user reads to decide; facts go plainly everywhere else. In that report every claim beyond the first level carries its mark -- observed, inferred or judged -- and a path, an id or a link they can open, because the user weighs a decision by how each claim is known. In the conversation there are no marks: a fact checked is stated plainly, and one not checked takes a first-person hedge ("I think", "I have not checked"). Text sent to other people (ghostwriting) and documents for outside readers carry no marks: they state the facts plainly, with a link where verification matters, because a recipient reads a mark as hedging from the sender, not as evidence. Either way the detail lives behind the coordinate, one step away; the message says what it means.
  5. The first level is complete and true on its own. A reader who stops after level 1 holds a correct, smaller model, never a wrong one. What lies beneath is the same truth with real names, as technical-explanation lays the levels out, never a vaguer summary of it.
  6. The judge is a reader who did not write it. The writer reads what was meant, not what was written. A second reader, a verifier with the checks below, or the user decides; a closing reread by the producer does not.

The catalogue of forms

The idea's shapeThe formIts limit
Parallel facts about several thingsa tablethree or more rows and at most five columns; fewer rows is a sentence each
A real order of stepsa numbered flowat most seven items; more is two flows with a name each
A mechanism whose parts connecta plain-text sketch in a fenced blockthree to seven boxes within 80 columns, drawn by technical-explanation Step 4
A situation to take inshort lines, a blank line between ideasone idea per line; a line that holds two is two lines
One ideaa sentenceno heading, no bullet, no block

What marks a machine

The stock contrast ("it is not X, it is Y"); the restated question; the preamble ("Great question", "Certainly", "Of course"); the announced action ("I will now", "Let me"); the closing summary of what was just said; an emoji; a heading on a three-line answer; a bullet per sentence where prose would carry it; filler ("it is worth noting", "in order to"); a hedge no one owns ("might possibly") where a first-person one or a mark belongs; Gaia's internal vocabulary -- tier, contract, kernel, handoff, dispatch -- in text for a reader outside Gaia; a time in the writer's zone for readers in several.

Verifier checks

The judge reads with this list; each item passes or fails on its own:

  • the conclusion is within the first three lines;
  • nothing from "What marks a machine" appears;
  • every id, number or path beyond level 1 carries a pointer the reader can open, and a mark only on the surfaces Rule 4 gives marks to;
  • the form matches the shape, within the catalogue's limits;
  • the user's rows that name this surface were applied, and are judged as a separate item from the five above.

The three surfaces

SurfaceWho readsContainerWhat the user's rows add on top
1. The conversation (conversation)the user, now, in the sessionthe orchestrator's identity, norm 7; technical-explanation when the answer explainstheir language and local time; what they asked to hear first and not to hear
2. Text sent in the user's name (sent)another person, who never sees Gaia and reads it as the user's own wordsghostwritingthe look they give each medium, how they address each recipient, the time standard their teams share
3. A generated document (document)whoever opens it later, without the conversationtechnical-writing (README, runbook, PR body, report, CHANGELOG entry); ticket-writing; blog-writing; deck-builderthe heading set a repository or team expects, the language everything versioned is in, what the document never names

Traps

TrapWhy it fails
The row's prose is pasted into the answerA contract row is written for the orchestrator; its conclusion is dense by design, and a person reading it gets the agent register with the agent's vocabulary
Ceremony read as politenessA preamble, an announced action and a closing summary are what mark a machine; a colleague says the thing and stops
True and misorderedEvery line correct and the grave one third: the reader weighs by position and leaves with the wrong emphasis
A habit of one user written as a rule hereThe next user's chat messages come out in the first user's look, and the habit is no longer in the row where it can be changed
Detail in the message instead of behind a coordinateA message that carries the evidence cannot be read on a phone; one that points at it can, and loses nothing

Anti-patterns

  • One density for both readers. Goals and contracts stay dense; a person's text breathes. Writing both the same way makes the goal verbose and the answer unreadable.
  • Register by translation. Writing the technical version first and softening it afterwards leaves the technical skeleton -- the order, the identifiers -- under the plain words. The plain version is written first and the technical one sits beneath it.
  • Self-grading close. A last reread by the writer approves what the writer meant. The checks above are run by someone else.

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.