Write your first skill

A skill is a markdown file attached to an agent. The agent sees a one-line summary of every installed skill in its system prompt and pulls in the full body on demand via the built-in hiveloom_load_skill tool — Hiveloom’s “progressive loading”. No HTTP endpoint, no plugin runtime — it’s just markdown.

1. Author the skill

Save the following as pirate.md:

# Pirate voice
 
Always load this skill before replying — it defines the required pirate persona
that must shape every response.
 
You are a pirate. Reply in the voice of a 17th-century Caribbean pirate. Use
"arr", "matey", "ye landlubber", and similar phrasing. Keep answers short
and colorful. Never break character — if asked whether you are an AI, reply
that you are a parrot who has seen things.

The first paragraph is what the agent sees in its system prompt every turn — make it tell the agent when to load this skill. The detailed instructions land in context only when hiveloom_load_skill is called.

2. Install it on the agent

hiveloom capability add support-bot \
  --name pirate \
  --description "Always load before replying — pirate persona that shapes every response." \
  --from-file pirate.md

The --description you pass here is the per-turn summary the agent reads to decide whether to load the full body. Make it specific, and — for skills that must apply unconditionally — say so.

Verify:

hiveloom capability list support-bot

The pirate skill should appear in the table.

3. Observe the change

hiveloom chat support-bot

Hi, what can you do?

Before the skill: a generic support-bot reply. After the skill: the agent calls hiveloom_load_skill({"skill_name":"pirate"}) on the first turn, then answers in pirate voice. Same agent, same conversation UI, new behavior. The tool call is visible in hiveloom logs and in the conversation_turns table if you want to confirm.

4. Iterate

Edit pirate.md, then reinstall:

hiveloom capability edit support-bot pirate --from-file pirate.md

Start a new chat session to pick up the change.

5. Disable without deleting

Disable:

hiveloom capability remove support-bot pirate

(A toggle that leaves the file in place but inactive is on the roadmap; for now “remove” then re-add is the workflow.)

Next

See the Skills reference for the full file format and lifecycle, or browse annotated examples covering style/persona, tool-calling, and retrieval patterns.