# Hive Intelligence - Agent Skills

Skill packages for AI coding assistants: Claude Code, Cursor, Codex CLI,
and any other agent that consumes the
[Agent Skills convention](https://github.com/vercel-labs/skills).

## What this is

A skill is a folder of Markdown files that tells an AI agent how to use a
vendor API correctly. For Hive, the skill layer is the agent-facing workflow
surface above the MCP server:

1. Discover compact task candidates, then load one exact toolset.
2. Inspect the exact schema, operation, call budget, and stop conditions.
3. Execute bounded reads; require explicit approval for Hive state changes.
4. Preserve each material call's server-minted runtime receipt.
5. Validate the typed workflow envelope, then report provider provenance,
   source recency, missing evidence, and runtime status.

This mirrors the pattern used by strong ecosystem publishers: Vercel ships a
multi-skill repo, Supabase ships focused database and platform skills, and
Firecrawl ships a CLI skill that teaches command selection, output handling,
and escalation.

## Layout

```
agent-skills/
├── package.json       - standalone @hiveintelligence/agent-skills package
├── LICENSE
├── skills.sh.json     - public directory grouping metadata
├── .claude-plugin/     — Claude Code plugin manifest
├── .mcp.json           — hosted Hive MCP server config (wired on plugin install)
├── evals/             - trigger-quality eval prompts
├── references/        - always-on routing snippets for AGENTS.md-style files
├── scripts/           - deterministic package validation
├── README.md
└── packs/
    ├── hive-cli/                — Use the `hive` CLI from a chat
    ├── hive-mcp/                — Add Hive MCP to a client
    ├── hive-build-onboarding/   — Walk a user through browser sign-in
    ├── hive-build/              — Integrate Hive into app code
    ├── hive-query/              — Route crypto questions through task toolsets
    ├── hive-tool-discovery/     — Search tools, inspect schemas, and invoke safely
    ├── hive-market-research/    — Prices, liquidity, exchanges, OHLC, derivatives
    ├── hive-token-diligence/    — Token metadata, holders, liquidity, enrichment, risk
    ├── hive-wallet-investigation/ — Wallet balances, transfers, PnL, NFTs, DeFi
    ├── hive-security-risk/      — Token, approval, phishing, address, simulation risk
    ├── hive-dex-pool-analysis/  — Pools, pairs, liquidity, trades, DEX flow
    ├── hive-defi-research/      — Protocols, TVL, fees, stablecoins, bridges, yields
    ├── hive-nft-research/       — NFT collections, owners, metadata, floors, rarity
    ├── hive-solana-analysis/    — Solana wallets, SPL accounts, DAS assets, fees
    ├── hive-network-infrastructure/ — Blocks, gas, receipts, logs, RPC diagnostics
    ├── hive-prediction-markets/ — Prediction markets, events, outcomes, traders
    └── hive-stateful-monitoring/ — Durable monitors, alerts, scheduled reports, agent memory
```

## Distribution

The skills folder ships in three places (skills are not published to npm —
the agent-skills ecosystem resolves from GitHub, not npmjs.com):

1. **Bundled with `hive-intelligence`** — the root npm package includes these packs so
   `npx -y -p hive-intelligence@latest hive init --all` can copy them into
   `~/.claude/skills/`, `~/.cursor/skills/`, and other supported clients.

2. **Public GitHub skills mirror** — this directory is mirrored to
   [`hive-intel/hive-skills`](https://github.com/hive-intel/hive-skills) (a
   `skills/<name>/SKILL.md` layout the `skills` CLI walks). Install every skill
   with `npx skills add hive-intel/hive-skills`, a single skill with
   `npx skills add hive-intel/hive-skills@hive-mcp`, or as a Claude plugin via
   the bundled `.claude-plugin/plugin.json`. Regenerate the mirror after any
   change with `npm run skills:sync <path-to-clone>` (validate locally first
   with `npx skills add ./agent-skills --list`). The sync target must be a clean
   `main` checkout exactly matching the freshly fetched `origin/main`. After
   generation, create a release branch and merge it through the protected
   CODEOWNER-reviewed PR flow; never push generated changes directly to `main`.

3. **Public agent-onboarding manifest** — the top-level `SKILL.md` is
   mirrored at `https://www.hiveintelligence.xyz/agent-onboarding/SKILL.md`
   (lives in the `hive-website` repo's `public/` directory). Any AI
   agent that fetches the marketing site's `<link rel="alternate"
type="text/markdown" href="/agent-onboarding/SKILL.md">` discovers
   this file and can self-install Hive.

## Authoring conventions

Each sub-skill follows the same shape:

```
packs/hive-<topic>/
├── SKILL.md          — frontmatter + instructions an agent should follow
├── references/       — deeper docs loaded only when needed
└── evals/            — realistic prompts for regression testing the skill
```

`SKILL.md` frontmatter:

```yaml
---
name: hive-<topic>
description: One-sentence "use this when…" trigger
license: MIT
metadata:
  package: "@hiveintelligence/agent-skills"
  category: "<setup|discovery|domain>"
  requires_network: "true"
version: 1.0.0
---
```

Body shape: short imperative instructions, code examples, links to
canonical docs. Keep each SKILL.md under ~400 lines; agents truncate
long files.

## Patterns copied from high-signal skills

- Keep the install command short and repo-level, then allow single-skill
  installs for narrow workflows.
- Put trigger rules in frontmatter and the first paragraphs, not buried in
  examples.
- Ship a compact always-on routing snippet for `AGENTS.md` / `CLAUDE.md` /
  `GEMINI.md`. Skills are vertical workflow modules; the routing snippet
  removes the "will the agent remember to load the skill?" decision point.
- Prefer progressive disclosure: `SKILL.md` gives the workflow, `references/`
  carries architecture and command matrices, and scripts are reserved for
  deterministic automation.
- Teach the agent how to decide before it executes: discover compact toolsets,
  load one exact workflow, inspect schema/operation, obey budgets and stops,
  then validate and cite provider/runtime receipts.
- Add eval prompts for real user tasks. A skill is not done until trigger
  prompts and output-quality prompts prove it routes and reports better than a
  generic model answer.

## Always-on routing

For agents that support repo-level instruction files, add the compact routing
block from `references/agents-routing.md`. Keep the block short; it should only
decide which Hive skill to load. Detailed endpoint and provider behavior stays
inside the skill packs and their `references/` files.

## Source of truth

The shipped skill metadata source of truth is `src/agentSkills.ts`.
The task-routing source of truth is `src/taskToolsets.ts`.

The sub-skills here are procedural expansions per topic. Run
`npm run verify:agent-skills`, `npx skills add ./agent-skills --list`, and
`npm --workspace @hiveintelligence/agent-skills run pack:check` after editing
this directory. Website copies should mirror these packs, but MCP execution
remains the runtime authority.