Agent skills
Honeybase is a workflow-automation platform with surfaces that no AI model has seen in training: an org-scoped GraphQL API, and a deliberately subsetted SurveyJS form schema. Ask an assistant to write against either from memory and it will guess field names, invent operations, or use SurveyJS features the server refuses.
A Honeybase skill closes that gap. A skill is a packaged set of instructions —
a SKILL.md file plus bundled reference material — that an AI agent loads on demand
to learn a specific surface. It is the format used by Claude Code and Claude Desktop,
and it works in any tool that reads the same folder layout. When the agent recognizes
that a task touches Honeybase, it loads the relevant skill and works from documented
facts instead of guesses.
Skills are documentation for the agent. These docs are the same material for you. The two are meant to be used together: point your assistant at a skill, keep this site open for the human-readable guides it links back to.
The skills
| Skill | Load it before | Bundles |
|---|---|---|
honeybase-mcp | Connecting an AI client to the Honeybase MCP server, or calling its tools | Nothing extra — the tool surface is discovered live via tools/list |
honeybase-graphql-api | Writing any query, mutation, or integration against a Honeybase server with an hbk_ organization API key | The full GraphQL SDL as a greppable reference |
honeybase-forms | Authoring or editing a Honeybase task form (validate_form_schema, create_form, update_form, or a Create/Update Task node's formAttachment) | The subsetted SurveyJS JSON Schema — the 15 allowed question types and the blocked keys |
honeybase-mcp teaches an agent to drive Honeybase over the remote MCP
server: the OAuth-vs-hbk_-key distinction, the scopes and what each gates,
discovering the tool surface with tools/list rather than guessing, and the
untrusted-data trust boundary. It is the counterpart to the other two — MCP for the
common tool surface, honeybase-graphql-api when you need raw GraphQL, honeybase-forms
whenever a form schema is involved.
honeybase-graphql-api teaches an agent to drive the API: the single namespaced
endpoint, Bearer hbk_... auth, the id/date/JsonString conventions, the permission
model, and how to grep the shipped schema instead of introspecting. It complements the
human-readable GraphQL API guides and integration setup pages
on this site.
honeybase-forms teaches an agent to author a valid form: which of SurveyJS's
question types Honeybase allows and why the rest are refused, the nine blocked keys,
how a question name becomes the downstream task.form.data.<name> contract, and the
attach/snapshot lifecycle. Pair it with the Concepts pages for how tasks
and forms fit the wider model.
Both are the customer-facing skills. (Honeybase's repository also contains internal skills used only for maintaining the product; those are not published.)
Installing a skill
Three supported ways to get a skill in front of your agent — npx is the quickest.
1. Install with npx (recommended)
The skills are published to the public honeybase-inc/honeybase-skills
repository, so the open-source skills CLI can
install them straight into your agent — no clone, nothing to build:
# Install every Honeybase skill into ./.claude/skills/
npx skills add honeybase-inc/honeybase-skills
# Install just one
npx skills add honeybase-inc/honeybase-skills --skill honeybase-graphql-api
# Preview without installing
npx skills add honeybase-inc/honeybase-skills --list
# Install for every project (into ~/.claude/skills/)
npx skills add honeybase-inc/honeybase-skills --global
It writes into .claude/skills/ (the project's by default, or ~/.claude/skills/ with
--global), pulling each skill's SKILL.md and its references/ files. Re-run
npx skills update any time to refresh. The skills CLI is a third-party tool
(vercel-labs); it sends anonymous usage telemetry that includes the public repo and skill
names — set DISABLE_TELEMETRY=1 (or DO_NOT_TRACK=1) to opt out.
2. Copy the folder into a project
Each skill lives in a self-contained folder — SKILL.md plus a references/
directory. Drop that folder into either location and a compatible agent picks it up:
- Per project:
<your-project>/.claude/skills/<name>/ - For your user account:
~/.claude/skills/<name>/
For example, .claude/skills/honeybase-graphql-api/ with its SKILL.md and
references/schema.gql inside. Nothing else is required — the folder carries
everything the agent needs.
3. Fetch from the hosted copy
Every published skill is also served as static files under honeybase.ai/skills/:
https://honeybase.ai/skills/honeybase-mcp/SKILL.md
https://honeybase.ai/skills/honeybase-mcp/version.json
https://honeybase.ai/skills/honeybase-graphql-api/SKILL.md
https://honeybase.ai/skills/honeybase-graphql-api/references/schema.gql
https://honeybase.ai/skills/honeybase-graphql-api/version.json
https://honeybase.ai/skills/honeybase-forms/SKILL.md
https://honeybase.ai/skills/honeybase-forms/references/surveyjs-subset.json
https://honeybase.ai/skills/honeybase-forms/version.json
Download SKILL.md and the files it references into a .claude/skills/<name>/
folder as above, preserving the references/ subfolder.
If you use the Honeybase MCP server, you don't have to fetch anything by
hand: the get_graphql_api_skill and get_forms_skill tools return these hosted
URLs (and the fetch commands) on request, so your agent can pull the current skill
mid-conversation.
Knowing when to re-download
Each skill's SKILL.md frontmatter carries a version: line — a date stamp bumped
whenever the skill is regenerated (for example, after a GraphQL schema change or a
SurveyJS version bump). The hosted version.json sits next to it and reports the same
version plus the list of files:
{ "version": "2026-08-28", "files": ["SKILL.md", "references/schema.gql"] }
To check whether an installed copy is stale, compare the version: line in your local
SKILL.md against the hosted version.json. If the hosted version is newer,
re-download the listed files. When a schema changes, the hosted skill is what stays
current — an old local copy keeps working but may describe fields that have since
moved.
See also
- GraphQL API — the human-readable companion to
honeybase-graphql-api: authentication, conventions, errors, and the generated schema reference. - Integrations — one page per connection type, listing exactly what each setup form asks for.
- Concepts — processes, workflows, runs, tasks and forms, and the vocabulary the skills assume.