hive-intelligence 1.1.0 → 1.1.3

package/agent-skills/README.md

@@ -0,0 +1,146 @@
+# 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 the right task toolset.
+2. Inspect the exact schema.
+3. Execute a bounded call.
+4. Report provider provenance, freshness, 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
+├── 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 PKCE auth
+    ├── 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
+```
+
+## Distribution
+
+The skills folder ships in four places:
+
+1. **Bundled with `hive-intelligence`** — the root npm package includes these packs so
+   `npx -y -p hive-intelligence@latest hive init --all --browser` can copy them into
+   `~/.claude/skills/`, `~/.cursor/skills/`, and other supported clients.
+
+2. **Standalone npm package** — this directory publishes as
+   `@hiveintelligence/agent-skills` for agents, installers, and package
+   managers that want the skill corpus without the MCP server runtime.
+
+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.
+
+4. **GitHub skills mirror** — mirror this directory into a dedicated skills
+   repo for the public skills directory and CLI install flow. Do not publish
+   skills CLI examples until the mirror exists and has been installed in CI.
+   Until then, validate locally with:
+
+   ```bash
+   npx skills add ./agent-skills --list
+   ```
+
+## 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 toolsets, inspect
+  schema, bound the call, then cite provider/runtime state.
+- 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.

package/agent-skills/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: hive-agent-skills
+description: Use this skill when installing or routing Hive Intelligence agent skills as a complete pack for MCP setup, tool discovery, live crypto workflows, CLI use, or application integrations.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "routing"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# Hive Agent Skills
+
+Use this as the top-level routing skill for the Hive skills package. Pick the
+smallest downstream skill that matches the user's intent.
+
+## Routing
+
+- `hive-mcp` — install or configure Hive MCP in Claude Code, Claude Desktop,
+  Cursor, VS Code, Windsurf, ChatGPT Desktop, or Gemini CLI.
+- `hive-build-onboarding` — the user needs a Hive account, API key, or auth
+  fix before setup can work.
+- `hive-build` — the user is integrating Hive into app code, backend services,
+  SDK adapters, agents, cron jobs, or production systems. For TypeScript,
+  prefer `@hiveintelligence/mcp-client`; use REST as fallback.
+- `hive-tool-discovery` — the user needs the right tool, task toolset, category,
+  provider, or input schema before execution.
+- `hive-query` — the user wants a live data answer in the current chat.
+- Workflow skills — use `hive-market-research`, `hive-token-diligence`,
+  `hive-wallet-investigation`, `hive-security-risk`, `hive-dex-pool-analysis`,
+  `hive-defi-research`, `hive-nft-research`, `hive-solana-analysis`,
+  `hive-network-infrastructure`, or `hive-prediction-markets` for deeper
+  production workflows.
+
+## Install
+
+Use the published Hive package for client setup:
+
+```bash
+npx -y -p hive-intelligence@latest hive init --all --browser
+```
+
+Hosted MCP:
+
+```text
+https://mcp.hiveintelligence.xyz/mcp
+```
+
+Local stdio:
+
+```text
+npx -y -p hive-intelligence@latest hive
+```
+
+## Operating Rules
+
+- Start with task discovery, not raw tool browsing.
+- Inspect schema before calling an unfamiliar endpoint.
+- Keep calls bounded with `limit`, `page`, `per_page`, or `offset`.
+- Preserve provider, source, freshness, cache, and runtime status metadata.
+- Never expose full API keys in browser code, logs, screenshots, or generated
+  artifacts.
+
+## Runtime status handling
+
+When a provider is unavailable, gated, rate limited, or degraded, keep the tool
+discoverable and surface the classified runtime status. Do not silently swap
+providers or drop provenance.

package/agent-skills/evals/README.md

@@ -0,0 +1,20 @@
+# Hive Agent Skills Evals
+
+This folder contains package-level eval prompts that test whether agents choose
+the right Hive skill before execution.
+
+- `trigger-queries.json` checks skill-trigger quality with should-trigger and
+  should-not-trigger prompts.
+- Per-skill `packs/*/evals/evals.json` files check output quality after a skill
+  is loaded.
+
+Run the static verifier after editing:
+
+```bash
+npm run verify:agent-skills
+npx skills add ./agent-skills --list
+```
+
+For live trigger testing, run each query in a clean agent session with the Hive
+skills installed and record whether the expected skill was loaded. Keep train
+and validation splits separate so description changes do not overfit.

package/agent-skills/evals/trigger-queries.json

@@ -0,0 +1,194 @@
+{
+  "description": "Trigger-quality evals for Hive agent skills. Train prompts guide description improvements; validation prompts are held out for sanity checks.",
+  "skills": [
+    {
+      "skill_name": "hive-query",
+      "train": [
+        {
+          "query": "Can you check what's happening with this wallet and whether it has any recent DeFi activity?",
+          "should_trigger": true
+        },
+        {
+          "query": "What's the latest BTC price and liquidity context?",
+          "should_trigger": true
+        },
+        {
+          "query": "Write a TypeScript type for a wallet object.",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "I need a live read on a token, its holders, liquidity, and safety flags.",
+          "should_trigger": true
+        },
+        {
+          "query": "Explain what a blockchain wallet is at a high level.",
+          "should_trigger": false
+        }
+      ]
+    },
+    {
+      "skill_name": "hive-tool-discovery",
+      "train": [
+        {
+          "query": "I know Hive has a tool for token holders but I don't know the endpoint name.",
+          "should_trigger": true
+        },
+        {
+          "query": "Which Hive provider can inspect Solana DAS assets?",
+          "should_trigger": true
+        },
+        {
+          "query": "List the files in this repository.",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "Before calling Hive, find the schema for an Ethereum approval risk check.",
+          "should_trigger": true
+        },
+        {
+          "query": "Summarize the README without using external tools.",
+          "should_trigger": false
+        }
+      ]
+    },
+    {
+      "skill_name": "hive-mcp",
+      "train": [
+        {
+          "query": "Add Hive MCP to Cursor with the hosted endpoint.",
+          "should_trigger": true
+        },
+        {
+          "query": "Should I use hosted MCP or local stdio for Claude Desktop?",
+          "should_trigger": true
+        },
+        {
+          "query": "What is MCP in general?",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "Configure Hive MCP in VS Code and include the auth header.",
+          "should_trigger": true
+        },
+        {
+          "query": "Write a generic JSON-RPC example unrelated to Hive.",
+          "should_trigger": false
+        }
+      ]
+    },
+    {
+      "skill_name": "hive-build",
+      "train": [
+        {
+          "query": "Use Hive from my TypeScript backend and preserve provider metadata in the response.",
+          "should_trigger": true
+        },
+        {
+          "query": "I am integrating Hive MCP into a custom app, should I use the SDK or REST?",
+          "should_trigger": true
+        },
+        {
+          "query": "Connect Claude Desktop to Hive MCP.",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "In Brownian Code, add a server-side Hive helper that calls get_price and keeps the API key private.",
+          "should_trigger": true
+        },
+        {
+          "query": "What is the latest Bitcoin price right now?",
+          "should_trigger": false
+        }
+      ]
+    },
+    {
+      "skill_name": "hive-build-onboarding",
+      "train": [
+        {
+          "query": "I do not have a Hive API key yet, walk me through getting one.",
+          "should_trigger": true
+        },
+        {
+          "query": "Hive says my key is missing in Claude Code.",
+          "should_trigger": true
+        },
+        {
+          "query": "Write a Python wrapper for get_price.",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "Help me sign in and create my first Hive key for an agent integration.",
+          "should_trigger": true
+        },
+        {
+          "query": "Explain how OAuth works generally.",
+          "should_trigger": false
+        }
+      ]
+    },
+    {
+      "skill_name": "hive-cli",
+      "train": [
+        {
+          "query": "Use the hive CLI to search for a wallet analytics endpoint.",
+          "should_trigger": true
+        },
+        {
+          "query": "Run a Hive command that fetches bitcoin price as JSON.",
+          "should_trigger": true
+        },
+        {
+          "query": "List npm scripts in this repository.",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "Show me the hive command to inspect the schema for get_price.",
+          "should_trigger": true
+        },
+        {
+          "query": "What are common CLI design principles?",
+          "should_trigger": false
+        }
+      ]
+    },
+    {
+      "skill_name": "hive-token-diligence",
+      "train": [
+        {
+          "query": "Is this token contract real, liquid, and safe enough to research further?",
+          "should_trigger": true
+        },
+        {
+          "query": "Compare token holders and DEX liquidity for this contract.",
+          "should_trigger": true
+        },
+        {
+          "query": "Implement an ERC-20 contract from scratch.",
+          "should_trigger": false
+        }
+      ],
+      "validation": [
+        {
+          "query": "Run diligence on this Base token address before I trade it.",
+          "should_trigger": true
+        },
+        {
+          "query": "Explain the ERC-20 standard historically.",
+          "should_trigger": false
+        }
+      ]
+    }
+  ]
+}

package/agent-skills/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hiveintelligence/agent-skills",
+  "version": "0.1.0",
+  "description": "Agent Skills for using Hive MCP: crypto research workflows, tool discovery, client setup, and provenance-aware execution.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "Hive Intelligence",
+  "homepage": "https://www.hiveintelligence.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharpe-labs/hive-mcp2.git",
+    "directory": "agent-skills"
+  },
+  "bugs": {
+    "url": "https://github.com/sharpe-labs/hive-mcp2/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-skills",
+    "mcp",
+    "crypto",
+    "defi",
+    "wallet-analytics",
+    "token-security",
+    "solana",
+    "nft",
+    "prediction-markets"
+  ],
+  "files": [
+    ".claude-plugin/**/*",
+    "evals/**/*",
+    "packs/**/*",
+    "references/**/*",
+    "scripts/**/*",
+    "LICENSE",
+    "README.md",
+    "SKILL.md",
+    "package.json",
+    "skills.sh.json"
+  ],
+  "scripts": {
+    "check": "npm run validate && npx skills add . --list && npm pack --dry-run",
+    "validate": "node scripts/validate-agent-skills-package.mjs",
+    "pack:check": "npm pack --dry-run"
+  }
+}