A rule that takes eight sentences costs eight sentences every time
The eleventh article in the "Design of Hora Kit" series. kit/ is read every time; docs/ is not. A rule that takes eight sentences costs eight sentences every time. This is about how to write a skill, and it applies to anyone writing Claude Code skills, even if you do not use Hora Kit.
1. Introduction
This article is the eleventh in a series explaining the design of Hora Kit, the AI development framework that we (Open Reach Tech) released as open source. The main article is here.
We open-sourced Hora Kit, an AI development framework for truly automated development
A note on terminology. There is only one command you type in Hora Kit:
/hora. Depending on the situation,/horacalls/hora-spec(writes the spec),/hora-setup(creates the implementation repositories),/hora-plan(fixes the version and writes the feature list and contracts),/hora-build(takes one feature through the 18 checkpoints), and/hora-accept(performs acceptance), in that order./hora-hotfixis the only one that/horadoes not call; a person types it directly. The docs call/hora-spec"the deciding side" and the rest "the building side", and this article uses those names too.
Of all the articles in this series, this is the one I would like even people who do not use Hora Kit to read. It applies to anyone who writes Claude Code skills.
If you carefully write "why this rule exists" into your skills, this may be a little uncomfortable to hear.
2. kit/ is read every time; docs/ is not
The Hora Kit repository has two kinds of prose.
kit/ | docs/ | |
|---|---|---|
| Who reads it | Agents. At runtime, every time | People. With a question in mind, of their own accord |
| Cost | Number of sentences × number of runs | 0 |
| What goes in it | Rules | Reasoning, rejected alternatives, the failures being prevented |
The docs' writing-style.ja.md opens with this sentence. Every file that each hora package distributes is read at runtime before the agent acts. A rule that takes eight sentences costs eight sentences every time.
When writing a skill, you want to put "why this rule exists" inside the skill. It looks kinder, and it can be read in one place. But that also means having the agent load several paragraphs per rule every time it runs. And the "why" part is almost never needed to apply the rule correctly.
That is why Hora Kit separates them. The "why" goes to docs, the "what" goes to kit.
3. The three rules on the kit/ side
The first is: state the rule, do not narrate the failure.
✅ Match on what a description says, never on what a name sounds like.
❌ Match on what a description says, never on what a name sounds like. Two
skills whose names differ by one word can serve different surfaces
entirely, and a name that stops matching does not announce itself — the
gate simply runs without its convention and reports a pass, which is the
one kind of failure a gate must not have.
Following a rule with two paragraphs of "what happens if you break it" still leaves you with one rule. The reason stays, in a single clause, only when the rule cannot be applied correctly without it.
The second is: write it once, point to it everywhere else. Each rule gets one owning file, and every other file places only a one-line reference. This is the same thinking Hora Kit already applies to skill packages (copies go stale silently), applied to our own prose as well.
The third is: one claim per sentence. An em dash that joins a second claim is where the sentence gets cut. Forty words is the guideline for the upper limit.
4. What it means at the line level
| Bold | Only the command or prohibition itself. One or two per section |
| Em dash | At most one per sentence. A second one is a sentence break |
| Headings | Noun phrases of six words or fewer. A heading that other files cite is not changed without fixing the citing side |
| Cross-references | One per rule, placed at the end of the sentence |
| Negation | Write what holds. No two negations in one sentence |
| Aphorisms | At most one per document |
description: | Two sentences, 40 words. What it does, and when it runs |
The most important of these is the description: line. Hora Kit matches skills by description, not by name, so if this line does not say "what it does, and when it runs" in two sentences, that skill will not be called.
5. What is not compressed
Because they are read by exact match, some things break when you improve their wording.
- The 18 checkpoint headings in
checkpoints.md./hora-plancopies them verbatim - The section names in
_plan.md:## Features,## Features — adopted as built,## Not accepted,## Withdrawn,## Acceptance - The verdict phrasing:
reach: full,reach: scoped,passed over <n> of <m> features; <k> not accepted,version-criteria:,not-accepted:
These are identifiers, not prose. Touch them with the intention of "tidying up the text" and other files can no longer find them.
6. The docs/ side's style runs the other way
The docs side has a separate style rule, document-style.ja.md. It says that what separates the two is cost. Rules in skill files are paid for on every run, so all three rules over there are about compression. Docs, on the other hand, are not read at runtime, so argument costs nothing.
So in docs, stating the reasoning, showing the rejected alternatives, and naming the failure the rule prevents all earn their place. The budget is not length; it is findability. The only thing that does not earn its place is a claim the reader has to reassemble from four sections.
The use of bold differs too. In docs, bold is used for "a command, a prohibition, or the one fact that even a skimming reader should take away", and the topic of a paragraph is not bolded. That is the heading's job.
While I am at it: the docs are written as Japanese and English pairs, but the Japanese version is not a translation. The rule is that when you fix one, you fix the other in the same commit, and both are the original.
7. To those writing Claude Code skills
We think this separation is usable even if you do not use Hora Kit. There are three checks we recommend.
Is this sentence necessary to apply the rule correctly? If not, it goes to docs. Is this rule also written in another skill? If so, turn one of them into a reference. Does description: say "what it does, and when it runs" in two sentences? If not, it will not be called.
Skills are read every time. Remove one sentence and that skill gets one sentence cheaper every time it runs, without lowering the precision with which the rule is applied. I hope this is useful to anyone whose skills have grown too long.
The original sources are here. https://github.com/openreachtech/hora-core/blob/main/docs/writing-style.ja.mdhttps://github.com/openreachtech/hora-core/blob/main/docs/document-style.ja.md
