# Hive.writing Hive Skills

Author a new Agent Skill for a Hive agent that conforms to the Agent Skills...

- Repository: https://github.com/aden-hive/hive (11131 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aden-hive/hive --skill hive.writing-hive-skills -g -a claude-code -y`
Codex: `npx skills add aden-hive/hive --skill hive.writing-hive-skills -g -a codex -y`
Cursor: `npx skills add aden-hive/hive --skill hive.writing-hive-skills -g -a cursor -y`
Gemini CLI: `npx skills add aden-hive/hive --skill hive.writing-hive-skills -g -a gemini-cli -y`

## Description

Author a new Agent Skill for a Hive agent that conforms to the Agent Skills specification (SKILL.md with YAML frontmatter, optional scripts/references/assets directories). Use when the user asks to create, scaffold, add, or package a new skill for a Hive agent.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 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`

The rest: https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_default_skills/writing-hive-skills/SKILL.md