Agent skills for Handsontable DataGrid and HyperFormula, for Claude Code, Codex, and other coding agents.

Website   —   Documentation   —   HyperFormula docs   —   Community

Handsontable Agent Skills

Agent skills for Handsontable DataGrid (data grid component) and HyperFormula (headless spreadsheet calculation engine) to use in Claude Code, Codex, and other coding agents. These skills give your agent deep knowledge of both products so it can help you build, configure, and debug faster.

Skills included

Skill	What it covers
handsontable	The data grid component — React/Angular/Vue/vanilla JS setup, configuration, theming, cell types, sorting, filtering, formulas (via HyperFormula), hooks, performance, and v17 migration.
hyperformula	The headless calculation engine — instance creation, CRUD, custom functions, named expressions, error handling, batch operations, and Node.js usage.

When to use which: If you're building a visible grid in a web app, use handsontable. If you're evaluating formulas programmatically without a UI (server-side calculations, pricing engines, what-if analysis), use hyperformula. Both skills cross-reference each other.

Installation

Claude Code — plugin marketplace (recommended)

Run these as prompts in Claude Code, not as terminal commands.

/plugin marketplace add handsontable/handsontable-skills
/plugin install handsontable-skills@handsontable-skills

Then restart Claude Code or prompt with /reload-plugins slash command.

This installs both skills together. Claude Code will load handsontable and hyperformula automatically based on what you ask.

Cowork / Claude.ai web — zip upload

Download handsontable.zip and/or hyperformula.zip from the latest GitHub release, then drag the zip into the Cowork chat or upload it via Settings → Features → Skills on Claude.ai.

Claude Code — manual install from source

Clone the repo somewhere convenient:

git clone https://github.com/handsontable/handsontable-skills.git

Then copy the two skill folders into your Claude Code skills directory. Pick the scope that fits — both assume Claude Code is already set up so .claude/skills/ exists.

User-scope — skills available in every project (recommended for product-knowledge skills like these):

cp -r handsontable-skills/skills/handsontable ~/.claude/skills/
cp -r handsontable-skills/skills/hyperformula ~/.claude/skills/

Project-scope — skills available only in one project. From inside that project's root:

cp -r /path/to/handsontable-skills/skills/handsontable .claude/skills/
cp -r /path/to/handsontable-skills/skills/hyperformula .claude/skills/

Keep the cloned repo around to git pull updates and re-copy when this skill ships a new release.

Claude API — programmatic upload

Upload skills/handsontable/ and skills/hyperformula/ to the Skills API. Each folder contains the SKILL.md and references/ that the API expects.

npm — hyperformula skill

The hyperformula skill is also published to npm as @handsontable/hyperformula-skill for use in any agent toolchain:

npm install @handsontable/hyperformula-skill

See the package README for how to wire it into Claude Code, the Claude API, or any other agent.

Other coding agents — npx skills installer

The community skills CLI can install this repo into agents that support Agent Skills, including Codex.

Install both skills for Codex:

npx skills add handsontable/handsontable-skills \
  --agent codex \
  --global \
  --skill '*' \
  --copy \
  --yes

Install only HyperFormula Skill:

npx skills add handsontable/handsontable-skills \
  --agent codex \
  --global \
  --skill hyperformula \
  --copy \
  --yes

Replace codex with another supported agent id from the skills CLI agent list. Omit --global for project-scoped installation.

Distribution formats

We ship the skills in several forms because different agents and surfaces accept different inputs. Use whichever matches the platform you're installing into.

Format	Where it lives	Use case
Raw skill folder	skills/<name>/ (this repo)	Source of truth. Used directly by Claude Code (.claude/skills/), the Claude API (folder upload), and as the input to every other format. Edit here when contributing.
.zip archive	GitHub Releases (built from source on tag push)	Drag-and-drop install for Cowork and Claude.ai web. Both platforms require zip and reject other archive formats.
-rag.md flat doc	dist/ (this repo)	Single concatenated markdown of SKILL.md + every reference file. For loading the skill into a RAG / vector store / chatbot context window where directory trees aren't supported.
npm package	@handsontable/hyperformula-skill (published on tag push)	npm install the skill into a JS/TS toolchain and copy it into your agent's skills directory. Currently the hyperformula skill only; the package version tracks the HyperFormula product version.

Earlier versions also shipped a .skill (gzipped tar) artifact. That format isn't accepted by Cowork or Claude.ai web and isn't part of Anthropic's documented spec, so it was removed.

Repository structure

.
├── README.md
├── LICENSE.txt
├── .claude-plugin/
│   └── marketplace.json          ← enables /plugin marketplace add
├── skills/                       ← source of truth
│   ├── handsontable/
│   │   ├── SKILL.md
│   │   └── references/
│   └── hyperformula/
│       ├── SKILL.md
│       ├── references/
│       ├── package.json          ← npm distribution metadata
│       └── README.md             ← npm package page
├── dist/                         ← generated artifacts (some tracked, some gitignored)
│   ├── handsontable-rag.md       ← tracked
│   ├── hyperformula-rag.md       ← tracked
│   ├── handsontable.zip          ← gitignored, built on demand / by CI
│   └── hyperformula.zip          ← gitignored, built on demand / by CI
├── scripts/
│   ├── build.sh                  ← regenerates dist/*.zip and dist/*-rag.md
│   ├── check-links.sh            ← verifies all skill URLs return 200
│   ├── check-plugin.sh           ← installs the plugin with Claude Code, fails if it won't load
│   ├── plugin-version.sh         ← bumps / checks the plugin version (used by CI)
│   └── release-if-bumped.sh      ← tags + releases a skill whose version marker moved
└── .github/workflows/
    ├── dist-sync.yml             ← PRs: rebuild dist/*-rag.md + bump the plugin version, commit to the PR branch
    ├── release-on-merge.yml      ← main: tag + release skills whose version marker moved
    ├── ht-skill-release.yml      ← handsontable: build zip on a tag, attach to Release
    ├── hf-skill-release.yml      ← hyperformula: build zip + publish to npm on a tag
    ├── link-check.yml            ← weekly link check
    └── plugin-check.yml          ← PRs, main, weekly: plugin loads in Claude Code; main: version moved with content

Building artifacts

After editing files in skills/, regenerate the dist artifacts:

./scripts/build.sh

This checks all documentation links for 404s, then writes dist/handsontable.zip, dist/hyperformula.zip, dist/handsontable-rag.md, and dist/hyperformula-rag.md.

To skip the link check (e.g., offline, or in CI):

./scripts/build.sh --skip-links

To check links independently, or auto-fix redirects:

./scripts/check-links.sh
./scripts/check-links.sh --fix-redirects

After touching .claude-plugin/ (or adding/removing a skill), confirm Claude Code still loads the plugin. claude plugin validate misses some loader errors, so this installs it for real in a throwaway home directory (needs the claude CLI and Node.js on PATH; no login required):

./scripts/check-plugin.sh

How to publish a new version of the skills

Each skill is versioned and released independently. The flow is the same for both skills; only hyperformula additionally publishes to npm.

The Claude Code plugin version

The marketplace plugin has its own version, in .claude-plugin/plugin.json, separate from the skill tags. Claude Code only gives users a new copy of the plugin when that version changes, so it has to move with every change to skills/ or .claude-plugin/. Dist sync takes care of the patch bump: on each such PR it raises the patch when the PR's version isn't already higher than main's. Bump minor or major yourself if you want to; the workflow leaves a higher version alone. Never lower it.

When two PRs are open at once, each one bumps from the same main, so after one merges the other usually conflicts on the "version" line. To resolve it, merge main into the branch (or use GitHub's conflict editor) and keep main's value; that push makes Dist sync raise it past main's again. For an automated skill-update PR, re-running the update does the same, since it rebuilds the branch from main. If two PRs instead land the same version without a conflict, Plugin Check fails on main and opens an issue; fix it with a PR that bumps the version.

How a skill update comes together

A skill is updated once per product release, after the release is fully published: the GitHub release notes, the docs for the new version (including the migration guide, when there is one), and the release blog post. Those are the sources an update is written from, so a draft started before they all exist has to be redone once they land.

The first draft comes from an automated pipeline that reads those sources together with the Handsontable DataGrid docs knowledge base and opens a draft pull request here. A maintainer then reviews every claim against the published docs, cross-checks hook, option, and method names against the API of the exact version being targeted, fixes what the draft got wrong, and merges. Merging is the release: CI keeps dist/ in step on the PR and tags the merge commit (see below). A tag such as handsontable/v18.1.0 therefore describes 18.1.0 and nothing newer.

Versioning convention

A skill's version matches the underlying product version, so the tag hyperformula/v3.3.0 is the skill that targets HyperFormula 3.3.0 and handsontable/v17.0.0 targets Handsontable DataGrid 17.0.0. Both skills live in one repo (rather than two) because they cross-reference each other constantly — a change in one almost always wants a paired check in the other, and a monorepo keeps that atomic.

Tag formats:

# Skill matches a Handsontable DataGrid / HyperFormula product release
handsontable/v17.0.0
hyperformula/v3.3.0

# Skill-only fix (typo, broken link, no product change) — same product version + suffix
handsontable/v17.0.0+skill.1
hyperformula/v3.3.0+skill.1

Release steps (both skills)

1. Edit the skill under skills/<name>/ in a PR, including its version marker: - **Latest version:** X.Y.Z in skills/handsontable/SKILL.md, or Aligned with HyperFormula X.Y.Z at the end of skills/hyperformula/SKILL.md. For hyperformula you do not bump skills/hyperformula/package.json by hand — CI sets the npm version from the tag (keep the committed value at the current product version as a sane default).

2. dist/ takes care of itself. dist-sync.yml rebuilds dist/*-rag.md on every PR that touches a skill and commits it to the PR branch when it changed (the .zip files are gitignored and built by the release). On a PR from a fork it cannot push, so the check fails and asks you to run ./scripts/build.sh --skip-links and commit dist/*-rag.md yourself. The docs assistant's knowledge base ingests the committed dist/*-rag.md from main, so a stale file means stale answers.

3. Merge. release-on-merge.yml runs scripts/release-if-bumped.sh: when a skill's version marker is newer than its newest <name>/vX.Y.Z tag, it tags the merge commit and dispatches that skill's release workflow on the tag. A merge that does not move a marker releases nothing. If a dispatch or a release run fails, re-run the workflow: a tag that has no GitHub Release yet is dispatched again. Preview what it would do with ./scripts/release-if-bumped.sh --dry-run.

4. Skill-only fixes are tagged by hand (typo, broken link, no product change — the marker does not move):

   git tag hyperformula/v3.3.0+skill.1 && git push origin hyperformula/v3.3.0+skill.1

   A product-version tag can still be pushed by hand too (git tag handsontable/v17.0.0 && git push origin handsontable/v17.0.0); the tag push starts the release exactly as before, and the merge workflow then sees the tag exists and does nothing.

What happens automatically on each tag

Each skill has its own workflow, so the two release fully independently — tagging one never touches the other. A workflow runs on a tag push, or when release-on-merge.yml dispatches it on a tag (a tag pushed with the workflow token does not trigger the push event); run by hand on anything but a <name>/v* tag, it refuses. A manual run on a tag only works for tags created after the dispatch trigger was added (October 2026), because a dispatch uses the workflow file as it is at the tag; re-push an older tag to re-release it.

• handsontable/v* → .github/workflows/ht-skill-release.yml:

  1. Runs ./scripts/build.sh --skip-links to build dist/handsontable.zip and dist/handsontable-rag.md.
  2. Creates a GitHub Release named after the tag (with auto-generated notes) and attaches both files.

• hyperformula/v* → .github/workflows/hf-skill-release.yml:

  1. Builds dist/hyperformula.zip and dist/hyperformula-rag.md and attaches them to a GitHub Release, same as above.
  2. Additionally publishes @handsontable/hyperformula-skill to npm with provenance, authenticated via trusted publishing (OIDC — no stored token). The npm version is derived from the tag (hyperformula/v3.3.0 → 3.3.0). A skill-only re-tag (hyperformula/v3.3.0+skill.1) publishes a prerelease (3.3.0-skill.1) under the skill-fix dist-tag instead, because npm strips semver build metadata and would otherwise collide with the already-published 3.3.0; these never overwrite latest. Install them explicitly with npm install @handsontable/hyperformula-skill@skill-fix.

handsontable is not published to npm — only the hyperformula folder carries a package.json.

One-time npm setup (hyperformula)

The npm publish uses trusted publishing (OIDC) — there is no NPM_TOKEN secret and nothing to rotate. npm exchanges the workflow's GitHub Actions OIDC token for a short-lived publish token at publish time.

This is configured once, on npm rather than in this repo. On the package access page, a package admin or @handsontable org owner adds a GitHub Actions trusted publisher with:

Field	Value
Organization or user	handsontable
Repository	handsontable-skills
Workflow filename	hf-skill-release.yml
Environment	(leave blank)

The workflow filename is case-sensitive and must include the extension. Renaming hf-skill-release.yml breaks publishing until the trusted publisher is updated to match.

Two requirements the workflow satisfies on purpose, worth knowing before editing it:

• Trusted publishing needs npm >= 11.5.1, so the workflow upgrades npm — the Node 22 image still bundles npm 10.x.
• actions/setup-node writes an _authToken line into ~/.npmrc whenever registry-url is set. Under OIDC that line is empty, which makes npm skip the token exchange and fail with a misleading ENEEDAUTH/E404, so the workflow deletes it before publishing (setup-node#1551).

Resources

• Handsontable docs
• HyperFormula docs
• Handsontable DataGrid GitHub
• HyperFormula GitHub
• Community forum

License

These skills are provided under the MIT License. See LICENSE.txt for details.

Handsontable and HyperFormula themselves are separately licensed products. A commercial Handsontable license includes HyperFormula when used inside the grid. HyperFormula can also be purchased separately for standalone/headless use.

	Handsontable	HyperFormula
Non-commercial	Free (licenseKey: 'non-commercial-and-evaluation')	Free (GPLv3, licenseKey: 'gpl-v3')
Commercial	Paid, per developer/year includes HyperFormula	Paid, per user/year
Pricing	handsontable.com/pricing	sales@handsontable.com
License details	License key docs	Licensing guide

Contributing

We welcome contributions to improve these skills. A few things to know about how they're designed:

Design philosophy. These skills are intentionally conceptual rather than exhaustive. They teach Claude how to think about each product — when to use what, common patterns, pitfalls to avoid — rather than trying to replicate the full documentation. The goal is for the skills to remain useful across product versions with minimal updates.

Progressive disclosure via references/. Each skill keeps SKILL.md short (under ~500 lines) as the always-loaded entry point, and pushes detail into references/*.md files that Claude reads on demand. The handsontable skill currently uses one references/docs-map.md curated link directory; the hyperformula skill is split into seven topic-specific reference files (api-quickref, configuration, custom-functions, error-handling, general-pitfalls, getting-started, vue3) plus the docs map. Both patterns are valid — split when one file grows past readability.

Why this works. Claude reads SKILL.md on every invocation, so it always has the conceptual foundation. For specifics, it follows links from the docs-map (or the topic-specific references) to the live docs. This approach means a new product version typically only requires updating version numbers and adding new entries — not rewriting the skill.

Standards we followed when creating these skills:

• Keep SKILL.md under ~500 lines; use reference files for overflow.
• Lead with working code examples that can be copy-pasted.
• Include a "Common Pitfalls" section based on real issues users hit.
• Include a "What this skill does NOT cover" section to help Claude route to the right skill.
• Add "Last verified" dates to docs-map files so staleness is visible.
• Make skill descriptions slightly "pushy" — Claude tends to under-trigger skills, so descriptions should be generous with trigger phrases.
• Cross-reference related skills by name so Claude can point users to the right one.

If you're adding a new skill or updating an existing one, follow these patterns and submit a PR.