Hive.writing Hive Skills

Operational Protocol: Writing Hive Skills

Hive agents discover skills by scanning several roots, in precedence order:

1. <project>/.hive/skills/, project, Hive-specific
2. <project>/.agents/skills/, project, cross-client
3. ~/.hive/skills/, user, Hive-specific
4. ~/.agents/skills/, user, cross-client
5. 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_skill inside 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), call write_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 in framework/skills/defaults.py::SKILL_REGISTRY only when the skill is a universal operational protocol shipped with Hive. Default skills use the hive.<name> naming convention and include type: default-skill in metadata.

Colony-scoped skills via write_skill