Loading
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 cr
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add aden-hive/hive --skill writing-hive-skills -a cursor -y
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.
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.
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-clientcore/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.
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>/.hive/skills/ when the skill is tied to that codebase's APIs, conventions, or infra and multiple agents in the project should share it.~/.hive/skills/ when the skill is reusable across projects for this machine/user and all agents should see it.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.write_skillA 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.
<skill-name>/
├── SKILL.md # Required
├── scripts/ # Optional — executable helpers
├── references/ # Optional — on-demand docs
└── assets/ # Optional — templates, data, images
Rules:
name frontmatter field (for framework defaults, the directory is the unprefixed name, e.g. writing-hive-skills/ for hive.writing-hive-skills).SKILL.md under ~500 lines. Move long reference material into references/.scripts/foo.py, references/API.md). Keep references one level deep.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>
descriptionThis is the single most important field — it's the only thing the agent sees at skill-selection time.
Helps with trading.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).
Structure the body for the agent, not a human reader:
Recommended sections (adapt to the domain):
Three tiers of context cost:
name + description. Keep tight.SKILL.md.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.
Put executable helpers in scripts/. They should:
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 ....
<skill-name> (lowercase-hyphenated).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).SKILL.md with frontmatter + body.scripts/, references/, assets/ only if needed.uv run hive skill validate <path-to-skill-dir>
uv run hive skill doctor
uv run hive skill list.When adding a skill as a shipped default:
core/framework/skills/_default_skills/<unprefixed-name>/.name: hive.<unprefixed-name> and metadata.type: default-skill.SKILL_REGISTRY in core/framework/skills/defaults.py:
SKILL_REGISTRY: dict[str, str] = {
...
"hive.<unprefixed-name>": "<unprefixed-name>",
}
{{placeholder}} substitution, add defaults to _SKILL_DEFAULTS in the same file.DATA_BUFFER_KEYS.SKILL.md.