Skills reference

A skill is any markdown file. Hiveloom stores the file verbatim and exposes it to the agent through progressive loading: every turn the agent sees a one-line summary of each installed skill in its system prompt, alongside an internal hiveloom_load_skill tool. The full body is fetched only when the agent calls that tool — typically because the user asked for a procedure the summary hints at.

This keeps the standing context small and predictable: a hundred skills cost roughly a hundred summary lines per turn, not a hundred full bodies.

File format

There is no required structure, but the first paragraph (or the --description you pass to capability add) is what the agent sees by default. Make it specific enough that the model knows when to reach for the skill — then put the detailed procedure further down.

# Skill name
 
Short description of when this skill applies. Becomes the per-turn summary.
 
## Instructions
 
Specific directives to the agent: how to behave, what to emphasise, what to
avoid.
 
## Examples (optional)
 
Concrete input → output pairs that the agent uses as few-shot grounding.

Frontmatter is not parsed by Hiveloom. The --description flag on capability add (or, failing that, the first non-empty line of the body — truncated to 240 characters) is what becomes the per-turn summary. The rest of the file is delivered verbatim only when hiveloom_load_skill is called.

Discovery

Skills are registered explicitly via hiveloom capability add; Hiveloom does not scan a folder. This means:

• You can store skill files anywhere (git repo, shared drive, /etc/hiveloom/skills).
• hiveloom capability add ... --from-file PATH imports the file’s contents into the tenant store. Moving or deleting the source file after import has no effect on the installed skill.
• To re-sync after editing the source file, use hiveloom capability edit <agent> <name> --from-file PATH.

Size and performance

Progressive loading means a skill’s body costs context only on the turn the agent loads it, not every turn. The standing cost is one summary line per installed skill. So:

• Summaries are cheap, but visible every turn. Make them concise and trigger-worthy (“Use this when …”) — that’s what the agent reads to decide whether to load the full body.
• Bodies can be longer than they used to be, since they don’t compete with conversation history on every turn. They only land in context when actually needed.
• Very long skills (>2000 tokens) still hurt the turn that loads them, so prefer one focused skill per task over a single sprawling document.

See Operations for how Hiveloom manages context overall.

Forcing a skill to apply every turn

Progressive loading means an agent may not load a skill if the summary doesn’t make the connection clear. If a skill needs to apply unconditionally (e.g. a persona that should colour every reply), say so explicitly in the summary — for example: “Always load this skill before replying. Defines the required Acme house style.” The agent will then call hiveloom_load_skill on each turn.

What skills are not

• Skills are not tools. They don’t invoke external APIs. They only shape what the agent says. For tool-calling, see the capability add --cap-endpoint URL path in the CLI reference.
• Skills are not fine-tuning. They’re per-request prompt injection. If you uninstall one, the effect disappears on the next turn.
• Skills are not tenant-global. They’re attached to a specific agent. Cloning a skill to another agent means running capability add again.

Next

Examples — three annotated worked skills you can adapt.