When a Skill Gets Too Big, Hermes Only Sees the First 1,500 Characters

You have spent six months growing a SKILL.md around one deployment procedure: back up first, roll out to 10% next, roll back to this tag if error rates move, and always hand the change to person X for approval. Thirty pages, edited dozens of times, a paragraph added each time. Then one day the agent runs the skill, gets the first half exactly right, and hands the change to the wrong approver — because the “always X” clause simply was not in what it read.
The model did not disobey. It never saw that section.
The hard budget: 100,000 characters per tool result
Hermes applies a general budget to tool results. Past 100,000 characters, a result is no longer placed in context whole: it is written to a spillover file on disk, and the model gets a preview plus a path.
That design is sensible. A page fetch, a find, a log tail can run to hundreds of thousands of characters; carrying all of it is expensive and crowds out what actually matters. So the limits stack:
| Limit | Default | Effect |
|---|---|---|
| Per-result threshold | 100,000 chars | Above it, persist to disk and keep a preview |
| Preview length | 1,500 chars | The text actually visible in context |
| Per-turn budget | 200,000 chars | Total across all tool results in one turn |
| MCP tool results | 50,000 chars | MCP payloads tend to be larger and less paginated |
The problem is that the budget does not distinguish data from rules.
For a skill, truncation does not save space — it drops rules
skill_view returns a JSON object: the body, linked_files, metadata. When the body grows enough that the whole JSON passes 100,000 characters, it is persisted like any other result and context receives this instead:
<persisted-output>
This tool result was too large (103,412 characters, 101.0 KB).
Full output saved to: ~/.hermes/cache/spillover/<id>.txt
Use the read_file tool with offset and limit to access specific sections of this output.
...
Preview (first 1500 chars):
...
</persisted-output>
For a scraped page, that notice does its job: the model knows the content is on disk and goes to read it. For a skill, the model tends to read it as “skill loaded”. The preview has a title, the first steps, the formatting — it looks complete. Nothing tells the model that the clause at 18% depth, the one naming the correct approver, was dropped.
That is exactly the scenario in issue #151283. The reporter’s skill carried a fixed production parameter that could not be inferred; after truncation the agent proceeded on inferred defaults and performed a state-changing write against a live enterprise system. Their summary is the important part: the failure is silent and asymmetric — harmless for a data payload, damaging for a policy payload.
What actually fits in 1,500 characters
There is a thoughtful detail in the implementation. Skill results are JSON, and persisting that verbatim would put the whole document on one line with escaped newlines, which makes read_file offset/limit pagination useless. So before persisting, the longest multi-line string is unwrapped into pageable plain text, and structured fields such as linked_files and metadata are moved behind the text so they cannot eat the preview.
The practical result: the preview shows scalar fields (status, paths), then the first 1,500 characters of the body.
For a two-thousand-word skill that is plenty. For a hundred-thousand-character skill, it is a table of contents.
How to write skills that avoid this
You do not have to wait for a fix. The habits are cheap:
1. Measure the size first. In the skill directory:
wc -c ~/.hermes/skills/<category>/<skill>/SKILL.md
Ten to twenty thousand characters is healthy. Past fifty thousand, start planning a split — not because truncation is certain, but because you are one more “let me just append this” away from the line.
2. Move long appendices into references/. Skills can ship supporting files; skill_view reports them as linked_files. Keep SKILL.md for the procedure and the non-negotiable rules, and put command inventories, platform differences and case histories in references/something.md, read only when needed. The main document shrinks and each load stays focused.
3. Put binding rules at the top. The preview is the first 1,500 characters. Approvers, forbidden operations, required parameters — anything where one wrong word is an incident — belongs in the opening few hundred characters, not in a caveats section three chapters down.
4. If you see persisted-output, go read the file. When that notice appears and the result was a skill, do not assume you have the whole thing. Open the path with read_file and page through the missing part with offset/limit.
5. A skill is not better for being exhaustive. A skill that covers everything is a runbook nobody finishes. Separating “must follow every time” from “look up occasionally” is the root fix.
Where things stand
At the time of writing, issue #151283 is still open: skill_view does not yet warn that rules were dropped. The safeguard today is authoring discipline, not tooling.
Skills grow the way documents always do — a paragraph at a time, over months, past the size anyone planned for. Measuring once in a while and moving appendices out is the cheapest insurance available.
Related: skill management commands, project-local skills inside a repo, and the three new optional skills.