hive/docs/skills-user-guide.md

Agent Skills User Guide

This guide covers how to use, create, and manage Agent Skills in the Hive framework. Agent Skills follow the open Agent Skills standard — skills written for Claude Code, Cursor, or other compatible agents work in Hive unchanged.

What are skills?

Skills are folders containing a SKILL.md file that teaches an agent how to perform a specific task. They can also bundle scripts, templates, and reference materials. Skills are loaded on demand — the agent sees a lightweight catalog at startup and pulls in full instructions only when relevant.

Quick start

Install a skill

Drop a skill folder into one of the discovery directories:

# Project-level (shared with the repo)
mkdir -p .hive/skills/my-skill
cat > .hive/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does X when the user asks about Y.
---

# My Skill

Step-by-step instructions for the agent...
EOF

The agent will discover it automatically on the next session.

List discovered skills

hive skill list

Output groups skills by scope:

PROJECT SKILLS
────────────────────────────────────
  • my-skill
    Does X when the user asks about Y.
    /home/user/project/.hive/skills/my-skill/SKILL.md

USER SKILLS
────────────────────────────────────
  • deep-research
    Multi-step web research with source verification.
    /home/user/.hive/skills/deep-research/SKILL.md

Where to put skills

Hive scans five directories at startup, in this precedence order:

Scope	Path	Use case
Project (Hive)	<project>/.hive/skills/	Skills specific to this repo
Project (cross-client)	<project>/.agents/skills/	Skills shared across Claude Code, Cursor, etc.
User (Hive)	~/.hive/skills/	Personal skills available in all projects
User (cross-client)	~/.agents/skills/	Personal cross-client skills
Framework	(built-in)	Default operational skills shipped with Hive

Precedence: If two skills share the same name, the higher-precedence location wins. A project-level code-review skill overrides a user-level one with the same name.

Cross-client paths: The .agents/skills/ directories are a convention shared across compatible agents. A skill installed at ~/.agents/skills/pdf-processing/ is visible to Hive, Claude Code, Cursor, and other compatible tools simultaneously.

Creating a skill

Directory structure

my-skill/
├── SKILL.md              # Required — metadata + instructions
├── scripts/              # Optional — executable code
│   └── run.py
├── references/           # Optional — supplementary docs
│   └── api-reference.md
└── assets/               # Optional — templates, data files
    └── template.json

SKILL.md format

Every skill needs a SKILL.md with YAML frontmatter and a markdown body:

---
name: my-skill
description: Extract and summarize PDF documents. Use when the user mentions PDFs or document extraction.
---

# PDF Processing

## When to use
Use this skill when the user needs to extract text from PDFs or merge documents.

## Steps
1. Check if pdfplumber is available...
2. Extract text using...

## Edge cases
- Scanned PDFs need OCR first...

Frontmatter fields

Field	Required	Description
name	Yes	Lowercase letters, numbers, hyphens. Must match the parent directory name. Max 64 chars.
description	Yes	What the skill does and when to use it. Max 1024 chars. Include keywords that help the agent match tasks.
license	No	License name or reference to a bundled LICENSE file.
compatibility	No	Environment requirements (e.g., "Requires git, docker").
metadata	No	Arbitrary key-value pairs (author, version, etc.).
allowed-tools	No	Space-delimited list of pre-approved tools.

Writing good descriptions

The description is critical — it's what the agent uses to decide whether to activate a skill. Be specific:

# Good — tells the agent what and when
description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

# Bad — too vague for the agent to match
description: Helps with PDFs.

Writing good instructions

The markdown body is loaded into the agent's context when the skill is activated. Tips:

• Be procedural: Step-by-step instructions work better than abstract descriptions.
• Keep it focused: Stay under 500 lines / 5000 tokens. Move detailed reference material to references/.
• Use relative paths: Reference bundled files with relative paths (scripts/run.py, references/guide.md).
• Include examples: Show sample inputs and expected outputs.
• Cover edge cases: Tell the agent what to do when things go wrong.

How skills are activated

Skills use progressive disclosure — three tiers that keep context usage efficient:

Tier 1: Catalog (always loaded)

At session start, the agent sees a compact catalog of all available skills (name + description only, ~50-100 tokens each). This is how it knows what skills exist.

Tier 2: Instructions (on demand)

When the agent determines a skill is relevant to the current task, it reads the full SKILL.md body into context. This happens automatically — the agent matches the task against skill descriptions and activates the best fit.

Tier 3: Resources (on demand)

When skill instructions reference supporting files (scripts/extract.py, references/api-docs.md), the agent reads those individually as needed.

Pre-activated skills

Some agents are configured to load specific skills at session start (skipping the catalog phase). This is set in the agent's configuration:

# In agent definition
skills = ["code-review", "deep-research"]

Pre-activated skills have their full instructions loaded from the start, without waiting for the agent to decide they're relevant.

Trust and security

Why trust gating exists

Project-level skills come from the repository being worked on. If you clone an untrusted repo that contains a .hive/skills/ directory, those skills could inject instructions into the agent's system prompt. Trust gating prevents this.

User-level and framework skills are always trusted. Only project-scope skills go through trust gating.

What happens with untrusted project skills

When Hive encounters project-level skills from a repo you haven't trusted before, it shows a consent prompt:

============================================================
  SKILL TRUST REQUIRED
============================================================

  The project at /home/user/new-project wants to load 2 skill(s)
  that will inject instructions into the agent's system prompt.
  Source: github.com/org/new-project

  Skills requesting access:
    • deploy-pipeline
      "Automated deployment workflow for this project."
      /home/user/new-project/.hive/skills/deploy-pipeline/SKILL.md
    • code-standards
      "Project-specific coding standards and review checklist."
      /home/user/new-project/.hive/skills/code-standards/SKILL.md

  Options:
    1) Trust this session only
    2) Trust permanently  — remember for future runs
    3) Deny              — skip all project-scope skills from this repo
────────────────────────────────────────────────────────────
Select option (1-3):

Trust a repo via CLI

To trust a repo permanently without the interactive prompt:

hive skill trust /path/to/project

This stores the trust decision in ~/.hive/trusted_repos.json, keyed by the normalized git remote URL (e.g., github.com/org/repo).

Automatic trust

Some repos are trusted automatically:

• No git repo: Directories without .git/ are always trusted.
• No remote: Local-only git repos (no origin remote) are always trusted.
• Localhost remotes: Repos with localhost/127.0.0.1 remotes are always trusted.
• Own-remote patterns: Repos matching patterns in ~/.hive/own_remotes or the HIVE_OWN_REMOTES env var are always trusted.

Configure own-remote patterns

If you trust all repos from your organization:

# Via file (one pattern per line)
echo "github.com/my-org/*" >> ~/.hive/own_remotes
echo "gitlab.com/my-team/*" >> ~/.hive/own_remotes

# Via environment variable (comma-separated)
export HIVE_OWN_REMOTES="github.com/my-org/*,github.com/my-corp/*"

CI / headless environments

In non-interactive environments, untrusted project skills are silently skipped. To trust them explicitly:

export HIVE_TRUST_PROJECT_SKILLS=1
hive run my-agent

Default skills

Hive ships with built-in operational skills that provide runtime resilience. These are always loaded (unless disabled) and appear as "Operational Protocols" in the agent's system prompt.

Skill	Purpose
hive.note-taking	Structured working notes in the shared buffer
hive.colony-progress-tracker	Claim tasks and track progress in the colony's SQLite ledger (progress.db)
hive.context-preservation	Save context before context window pruning
hive.quality-monitor	Self-assess output quality periodically
hive.error-recovery	Structured error classification and recovery
hive.writing-hive-skills	Author Hive-compatible SKILL.md files

Disable default skills

In your agent configuration:

# Disable a specific default skill
default_skills = {
    "hive.quality-monitor": {"enabled": False},
}

# Disable all default skills
default_skills = {
    "_all": {"enabled": False},
}

Environment variables

Variable	Description
HIVE_TRUST_PROJECT_SKILLS=1	Bypass trust gating for all project-level skills (CI override)
HIVE_OWN_REMOTES	Comma-separated glob patterns for auto-trusted remotes (e.g., github.com/myorg/*)

Compatibility with other agents

Skills written for any Agent Skills-compatible agent work in Hive:

• Place them in .agents/skills/ (cross-client) or .hive/skills/ (Hive-specific).
• The SKILL.md format is identical across Claude Code, Cursor, Gemini CLI, and others.
• Skills installed at ~/.agents/skills/ are visible to all compatible agents on your machine.

See the Agent Skills specification for the full format reference.