gabrielmoreira Operational Protocol: Writing Hive Skills
Hive agents discover skills by scanning several roots, in precedence order:
<project>/.hive/skills/— project, Hive-specific<project>/.agents/skills/— project, cross-client~/.hive/skills/— user, Hive-specific~/.agents/skills/— user, cross-client- Framework defaults shipped in
core/framework/skills/_default_skills/
Each skill is a directory containing a SKILL.md. At startup, only the frontmatter name + description of every skill is loaded; the body is loaded only when the agent activates the skill. Design for that.
Choosing where to put a new skill
- Colony-scoped (via
write_skillinside colony mode): when the skill is the operational protocol a single colony needs — its API auth, DOM selectors, DB schema, task-queue conventions — do NOT place it under~/.hive/skills/or<project>/.hive/skills/yourself. Those roots are SHARED and every colony on the machine will see it. Instead, once you're inside the colony (post-fork), callwrite_skill(skill_name, skill_description, skill_body, skill_files?)and the skill is materialized under~/.hive/colonies/<colony_name>/skills/<skill-name>/where only that colony's workers discover it. See the subsection below. - Project-scoped: put under
<project>/.hive/skills/when the skill is tied to that codebase's APIs, conventions, or infra and multiple agents in the project should share it. - User-scoped: put under
~/.hive/skills/when the skill is reusable across projects for this machine/user and all agents should see it. - Framework default: add under
core/framework/skills/_default_skills/AND register inframework/skills/defaults.py::SKILL_REGISTRYonly when the skill is a universal operational protocol shipped with Hive. Default skills use thehive.<name>naming convention and includetype: default-skillin metadata.
Colony-scoped skills via write_skill
A colony-scoped skill is one that belongs to exactly ONE colony — e.g. it encodes the HoneyComb staging API the honeycomb_research colony polls, or the LinkedIn outbound flow the linkedin_outbound_campaign colony runs. Writing such a skill at ~/.hive/skills/ or <project>/.hive/skills/ leaks it to every other colony, which will then see it at selection time.
Do not create the folder yourself with the terminal. Once the colony has been forked (via suggest_colony → user confirms the Create Colony popup), call write_skill inside the colony:
write_skill(
skill_name="honeycomb-api-protocol",
skill_description="How to query the HoneyComb staging API…",
skill_body="## Operational Protocol\n\nAuth: …",
skill_files=[{"path": "scripts/fetch_tickers.py", "content": "…"}], # optional
)
The tool writes ~/.hive/colonies/<this_colony>/skills/honeycomb-api-protocol/SKILL.md (plus any skill_files), which SkillDiscovery picks up as project scope when that colony's workers start — and ONLY that colony's workers. No cross-colony leakage.
Do not write colony-bound skill folders by hand under ~/.hive/skills/. A skill placed there is user-scoped and becomes visible to every colony on the machine — defeating the isolation you wanted.
Directory layout
<skill-name>/
├── SKILL.md # Required
├── scripts/ # Optional — executable helpers
├── references/ # Optional — on-demand docs
└── assets/ # Optional — templates, data, images
Rules:
- The directory name must equal the
namefrontmatter field (for framework defaults, the directory is the unprefixed name, e.g.writing-hive-skills/forhive.writing-hive-skills). - Keep
SKILL.mdunder ~500 lines. Move long reference material intoreferences/. - Reference other files with relative paths from the skill root (
scripts/foo.py,references/API.md). Keep references one level deep.
SKILL.md frontmatter
Required fields:
| Field | Constraints |
|---|---|
name |
1–64 chars, [a-z0-9-], no leading/trailing/consecutive hyphens. Must match the directory name. Framework defaults prefix with hive. |
description |
1–1024 chars. Must describe what the skill does and when to use it. Include trigger keywords the user is likely to say. |
Optional fields:
| Field | Notes |
|---|---|
license |
License name or reference to a bundled file |
compatibility |
≤500 chars. Only include if env requirements are non-trivial (network, tools, runtime) |
metadata |
Free-form string→string map. Namespace keys to avoid collisions. Default skills set type: default-skill. |
allowed-tools |
Experimental. Space-separated pre-approved tools, e.g. Bash(curl:*) Bash(jq:*) Read |
Minimal template:
---
name: my-skill
description: One sentence on what it does. One sentence on when to use it, with concrete trigger words the agent will see in user requests.
---
# My Skill
<body>
Writing a good description
This is the single most important field — it's the only thing the agent sees at skill-selection time.
- Bad:
Helps with trading. - Good:
Buy and sell shares on the HoneyComb exchange. Handles auth, slippage-protected orders, idempotent retries, and AMM output estimation. Use when placing trades or interacting with the AMM.
Include verbs the user is likely to say (buy, sell, place trade) and proper nouns (HoneyComb, AMM).
Writing the body
Structure the body for the agent, not a human reader:
- Lead with what the agent can't guess — API base URLs, auth shape, project conventions, specific function names. Skip generic background ("PDFs are a document format").
- Show exact request/response shapes — include JSON payloads, headers, status codes. Copy real examples rather than paraphrasing.
- Document failure modes — error codes, retry rules, rate limits. This is where skills earn their keep vs. a generic agent.
- Give a short end-to-end example — a "typical flow" section at the bottom anchors everything above.
Recommended sections (adapt to the domain):
- Authentication / setup
- Core operations (one per endpoint or action)
- Error reference table
- Rate limits / gotchas
- End-to-end example pattern
Progressive disclosure
Three tiers of context cost:
- Always loaded (~100 tokens per skill):
name+description. Keep tight. - Loaded on activation (<5k tokens target): body of
SKILL.md. - Loaded on demand: files under
scripts/,references/,assets/. The agent reads these only when the body points to them.
If a section is long and only needed sometimes (e.g., a full schema dump, rarely-used edge cases), move it to references/SOMETHING.md and link to it from the body: See [the error catalog](references/ERRORS.md) for the full list.
Scripts
Put executable helpers in scripts/. They should:
- Be self-contained or document dependencies in a comment header.
- Print human-readable errors to stderr and exit non-zero on failure.
- Accept arguments via CLI flags, not env vars (easier for the agent to invoke).
Reference them from the body by relative path:
Estimate buy output with `scripts/estimate_buy.py --v-hc 1000000 --v-shares 1000000 --hc 500`.
For Python scripts in a Hive project, prefer uv run scripts/foo.py ....
Creating a new skill — workflow
- Pick a
<skill-name>(lowercase-hyphenated). - Decide scope: colony (pass content INLINE to
create_colony— STOP here, do not hand-author the folder), project (<project>/.hive/skills/), user (~/.hive/skills/), or framework default (core/framework/skills/_default_skills/+ registry entry). - For the non-colony scopes: create the directory and write
SKILL.mdwith frontmatter + body. - Add
scripts/,references/,assets/only if needed. - Validate the frontmatter: name matches dir, description is specific, no forbidden characters.
- Validate using the Hive CLI:
uv run hive skill validate <path-to-skill-dir> uv run hive skill doctor - Confirm discovery with
uv run hive skill list. - Test by invoking a Hive agent on a task the skill should match — confirm it activates and follows the instructions.
Registering as a framework default
When adding a skill as a shipped default:
- Place the directory under
core/framework/skills/_default_skills/<unprefixed-name>/. - Set frontmatter
name: hive.<unprefixed-name>andmetadata.type: default-skill. - Add the mapping to
SKILL_REGISTRYincore/framework/skills/defaults.py:SKILL_REGISTRY: dict[str, str] = { ... "hive.<unprefixed-name>": "<unprefixed-name>", } - If the skill uses
{{placeholder}}substitution, add defaults to_SKILL_DEFAULTSin the same file. - If the skill reads/writes shared buffer keys, list them in
DATA_BUFFER_KEYS.
What NOT to put in a skill
- Generic programming knowledge the agent already has.
- Conversation-specific state (use memory or plans instead).
- Secrets or credentials (skills are plaintext; reference env vars or credential stores).
- Deeply nested reference chains — keep everything one hop from
SKILL.md.