Guide · Agent skill
How to use the Writing Hive Skills agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Writing Hive Skills is an agent skill, a folder containing a SKILL.md file that gives an AI agent extra know-how when it needs it. This one teaches a Hive agent how to author new skills that follow the Agent Skills specification. It is for developers and teams who want to package an API, workflow or project convention as a reusable skill for Hive. After reading this guide you will know how to install the skill, ask for a new skill in plain language, and check the result.
Writing Hive Skillsaden-hive/hive · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
- 2Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 3Describe the skill you need. Ask the agent in plain language to create, scaffold or package a skill, naming its purpose.
- 4Pick the scope. Choose colony, project, user, or framework default based on who should see the skill.
- 5Review the SKILL.md. Check the frontmatter name and description, and confirm the body has exact details and no secrets.
- 6Test with a real request. Ask the agent a question the new skill should answer and confirm it activates and uses the body correctly.
What the skill makes the agent do
When this skill is active, the agent knows how to create a new skill for a Hive agent. It chooses where the skill should live, writes the required YAML frontmatter (name and description), and structures the body so the agent can use it well later.
Hive agents scan several locations for skills, in precedence order: a project's .hive/skills/ folder, a project's .agents/skills/ folder, the user's ~/.hive/skills/ folder, the user's ~/.agents/skills/ folder, and the framework defaults. The skill explains which scope fits each kind of skill, including a colony-scoped path that keeps a skill limited to one colony's workers.
- Places a skill at project, user, or colony scope
- Writes a valid name and description in the frontmatter
- Structures the body with exact request shapes, failure modes and an end-to-end example
- Keeps long reference material in a references/ folder
Install the skill with a ZIP download or the Claude apps
Download the ZIP from this page and unzip it into one of two places. For a personal setup, unzip it into ~/.claude/skills/. To share it with one project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills. The skill ships as a single file, SKILL.md, so after unzipping you should see a writing-hive-skills folder containing that file.
- Personal install: ~/.claude/skills/
- Project install: the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. The skill is selected when your request matches its description, which covers creating, scaffolding, adding or packaging a new skill for a Hive agent. Name the thing you want and the kind of skill it is.
Clear requests mention the purpose and the audience, for example a skill that encodes the API your team calls. Vague requests about general documents or code are outside what this skill covers.
- "Create a new skill for my Hive agent that wraps our billing API."
- "Scaffold a skill for the staging database schema in this project."
- "Package our deploy checklist as a skill so every agent in the project can use it."
Choose the right scope for a new skill
Scope decides who can see the skill. A skill that holds one colony's API auth or task conventions should be written with write_skill from inside colony mode, not placed by hand in a shared folder. Writing it under ~/.hive/skills/ makes it visible to every colony on the machine.
Use project scope when agents in one codebase should share a skill, and user scope when a skill is reusable across projects for your machine. Framework defaults are only for universal protocols shipped with Hive, and they use the hive. naming prefix.
- Colony: created with write_skill after the colony is forked; visible only to that colony's workers
- Project: <project>/.hive/skills/, shared by agents in that project
- User: ~/.hive/skills/, shared across projects for one user
- Framework default: core/framework/skills/_default_skills/, only for universal Hive protocols
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": "…"}],
)Get the SKILL.md structure right
Every skill is a directory whose name equals the name field in its frontmatter. The name is 1 to 64 characters, uses only lowercase letters, digits and hyphens, and cannot start, end or repeat a hyphen. The description is 1 to 1024 characters and must say both what the skill does and when to use it, including the words a user is likely to say.
Only the name and description load at startup. The body loads when the agent activates the skill, so keep the description specific and the body focused. Keep SKILL.md under about 500 lines and move long material into references/.
- Required frontmatter: name and description
- Optional: license, compatibility, metadata, allowed-tools (experimental)
- Directory layout: SKILL.md (required), plus optional scripts/, references/ and assets/
- Reference other files with relative paths one level deep
---
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>Review the result before you rely on it
Read the generated SKILL.md before the agent uses it. Check that the name matches the folder, that the description names concrete trigger words, and that the body gives exact commands or request shapes instead of generic background.
Remove any credentials. The guidance encourages putting API auth details into skill bodies, so anything you paste in can end up in a shared folder. Keep secrets out of skill files and supply them another way.
- Name matches the directory name
- Description includes what, when and trigger words
- Body contains exact details and failure modes
- No secrets or tokens in the file
What people use it for
- Packaging an internal API's auth shape and error codes as a skill for a Hive agent
- Writing a project-scoped skill that encodes the team's coding conventions
- Creating a colony-scoped skill that holds one colony's task-queue rules without sharing them
- Scaffolding a SKILL.md with the required frontmatter and optional scripts/ folder
Frequently asked questions
Do I need the Hive agent framework to use this skill?
Yes. The skill assumes Hive's skill discovery paths and the write_skill tool, so it is written for Hive agents. It does not help with skills for other agent setups beyond the shared Agent Skills format.
Does this skill run scripts or use the network?
According to the listing, it runs no scripts and uses no network. It only ships a SKILL.md file.
Is the Writing Hive Skills skill free?
The source is licensed under Apache-2.0, which is stated on this page. Check the repository's license file for the terms that apply to your use.
Where do I put the downloaded skill folder?
Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
Can this skill write a skill that only one colony can see?
Yes. The guidance says to use write_skill inside colony mode after the colony is forked. That places the skill under ~/.hive/colonies/<colony_name>/skills/ so only that colony's workers discover it.
What is the alternative if this skill is not right for me?
If you only want to use an existing skill, this one is not the right tool, since it only helps write new ones. Use a general skill for your task instead, or write a skill by hand following the SKILL.md format.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you build custom or default skills for Hive and want consistent, spec-conforming SKILL.md files. Skip it if you only want to use existing skills, or if you need help with general documents or code unrelated to Hive or the Agent Skills format.
Download the skill