plain-numbers
Skill3 starsChanged 3 months agoMITView on GitHub
Writes and reviews numbers for readers who were not in the work, so a manager, client, or stakeholder reads each figure the way it was measured. Use when writing or checking a status update, weekly or check-in page, results summary, dashboard, report, or slide that carries percentages, counts, or other metrics. Not for code docs, agent instructions, marketing copy without metrics, or a chat reply to the person who did the work.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- api-designSkill
- backend-craftSkill
- meilisearchSkill
- design-coreSkill
- design-datavizSkill
- design-flowsSkill
- design-formsSkill
- design-product-uiSkill
- design-researchSkill
- design-reviewSkill
- design-slidesSkill
- design-systemsSkill
- design-webSkill
- agent-syncSkill
- build-autonomous-agentsSkill
- coding-disciplineSkill
- completion-gateSkill
- deliver-dependency-upgradesSkill
- documentation-and-adrsSkill
- grill-harness-with-docsSkill
- learn-agentic-engineeringSkill
- pnpmSkill
- scaffold-harnessSkill
- scaffold-monorepoSkill
- shift-left-securitySkill
- start-gateSkill
- update-harnessSkill
- write-a-skillSkill
- frontend-craftSkill
- ansible-automationSkill
- gitea-actionsSkill
- gitea-teaSkill
- manage-infrastructure-as-codeSkill
- multi-stage-dockerfileSkill
- secure-linux-web-hostingSkill
- integrate-product-complianceSkill
- product-craftSkill
- run-product-engineeringSkill
- playwright-best-practicesSkill
- testing-strategiesSkill
- writing-coreSkill
- writing-editorialSkill
- writing-engineeringSkill
- writing-marketingSkill
- writing-productSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
Put each caveat in its own sentence.
- Distinctive: line 41
Check the figures against the source data before writing prose around them.
- Very specific: line 45
Run it before the text goes out, and after any change to a number or its framing.
- Very specific: line 59
When a person or the reader test misreads something real, add a case to evals.md (input text, the misreading, the fixed text) and read the …
≈ “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
Plain Numbers
A figure is read without its author. The reader supplies the meaning, so a number with no stated meaning gets the most flattering or the most familiar one. This Skill makes the text carry the meaning, and proves it with a reader who knows nothing else.
Write
Name the reader first (for example "a manager at the client who joins the meeting"). Then apply to every number:
- One idea per sentence. Meaning first, then the number with its raw counts: "The prepared answer matched what the desk did in 85 of 227 requests (37%)." A statement about change names its baseline (from what) and, where known, its target (to what): "still at today's level", never "has not changed yet".
- State what it does not mean when a likely misreading exists. A match rate is not fewer requests; a sample share is not a population share.
- State how numbers on one page relate: part of, extra to, or a different set. Name the set each comes from ("26 of 43, part of the 85, not extra").
- Define each term a cold reader cannot know on first use, or use an everyday word instead. Names for internal tools, processes, and jargon count.
- Put each caveat in its own sentence. An aside in brackets is skipped.
- State the goal once. Use a measurable bound instead of a vague word: "at most 250 characters", not "short".
- Trace every number to a measurement or a merged change. Otherwise write "estimate" and show the formula.
- Claim no more than the method does. If a replay cuts the data to a past date but reads some fields in today's state, say exactly what was cut and what was not.
- Judge a verdict against a target (reached, above, below) by the interval, not the point estimate. When the interval contains the target, write "likely, not proven" and show the interval and the sample size.
Check the figures against the source data before writing prose around them.
Reader test
Run it before the text goes out, and after any change to a number or its
framing. Fill reader-test.md with the reader and the rendered text, and hand
it to a fresh agent with no other context: not the data, not the thread, not
your explanation.
Complete when every number is restated correctly, every likely-misreading question is answered correctly, the hypothesis and next steps come back right, and no unclear item blocks. Fix a misread number or a blocking unclear item and rerun with a fresh agent. Keep an unclear item only on purpose, and say so in your report. After three rounds without convergence, the text is carrying too much: cut numbers rather than add explanation.
Improve
When a person or the reader test misreads something real, add a case to
evals.md (input text, the misreading, the fixed text) and read the file
before writing. Keep it to real cases, one short entry each; merge entries that
teach the same lesson.
Boundaries
Pair with a humanizer for tone and with a charting Skill for visuals. This Skill owns whether the reader gets the figure right, not how the page looks.
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.

