Validate Claude Code plugin manifests before you submit them.
hanko is a single-binary Go CLI that reads your .claude-plugin/plugin.json and .claude-plugin/marketplace.json, validates them against the schema extracted from Anthropic's plugin docs, and catches the common footguns that make marketplace submission fail: reserved marketplace names, duplicate hooks declarations, agents set to a bare directory string, path traversal, and more.
The name: 判子 (hanko) is the personal seal stamped on official Japanese documents, the traditional act of approving a submission. Run hanko check before you file yours.
The full rule catalog, what hanko deliberately will not do, and the FAQ: https://roninforge.org/hanko/
curl -fsSL https://roninforge.org/hanko/install.sh | shVia Homebrew (macOS, Linux):
brew install roninforge/tap/hankoOr grab a binary from the latest release. Prefer Go install:
go install github.com/RoninForge/hanko/cmd/hanko@latest# From inside a plugin repo:
hanko check
# Before submitting to a specific marketplace:
hanko submit-check --marketplace anthropic
# Print the embedded JSON Schema for editor integration:
hanko schema print --file plugin > .claude-plugin/plugin.schema.json
# Use in CI (JSON output):
hanko check --json .- Schema errors the official validator reports opaquely (missing
name, wrong types, non-kebab-case, invalid hook event names). - Reserved marketplace names (eight exact names plus an impersonation-pattern regex).
- Duplicate hooks declaration where a plugin points
hooksat./hooks/hooks.jsoneven though Claude Code v2.1+ auto-loads that path by convention. agentsas a bare directory string, which the validator rejects despite the docs example showing it works.- Path traversal (
..or absolute) in any component path. - Missing
authorfor plugins that plan to ship via the Anthropic marketplace (Claude Desktop'slistAvailablePluginsvalidator refuses to load the whole catalog when even one plugin lacks one). - Missing
version, which is technically optional but breaks Claude Code's install cache.
See docs/rules.md for the full list with fix suggestions.
hanko submit-check layers rules on top of the base schema per marketplace:
--marketplace |
Source | Extra rules |
|---|---|---|
anthropic |
anthropics/claude-plugins-official | Strict reserved-name check, author strongly required |
buildwithclaude |
davepoon/buildwithclaude | No delta from base rules (conventions pending) |
cc-marketplace |
ananddtyagi/cc-marketplace | name, version, description all required |
claudemarketplaces |
mertbuilds/claudemarketplaces.com | No delta from base rules (auto-discovery) |
- uses: RoninForge/hanko@v0
with:
path: .
marketplace: anthropicAppends a findings table to the workflow run summary (the "Summary" tab of the PR's checks view) and exits non-zero on any error-severity finding. Set fail-on-warnings: true to also fail on warnings.
//go:embedincludes the JSON Schema forplugin.jsonandmarketplace.json.santhosh-tekuri/jsonschema/v6validates the file against the schema.- Go-coded rules apply the checks that do not round-trip cleanly through JSON Schema (reserved names, duplicate hooks, cross-references).
- Errors are formatted with schema path, offending value, a one-line fix suggestion, and a doc link.
Zero network calls. Binary is roughly 6 MB. MIT licensed.
See CONTRIBUTING.md.
See SECURITY.md.
Free, local-first tools for developers working with AI coding assistants. No accounts, MIT licensed.
- Tsuba - scaffold Claude Code plugins and skills
- BudgetClaw - local spend monitor for Claude Code
- Goei - unified AI provider cost dashboard
Free web tools (run in your browser, nothing uploaded):
- GitHub Copilot AI Credits calculator - estimate your monthly credit burn under usage-based billing
- Copilot usage CSV analyzer - break your usage report down by model, day, and SKU
- LLM API pricing comparison - Claude, GPT, Gemini, DeepSeek, Mistral, and Grok token prices side by side
hanko is part of RoninForge.org.