RoninForge / Hanko
Validate Claude Code plugin manifests before you submit them. Catches reserved names, duplicate hooks declarations, path traversal, and the schema errors the official validator reports opaquely.
判子 (hanko) is the personal seal stamped on official Japanese documents. The ritual act of approving a submission before filing it. Run hanko before you file yours.
Both plugin.json and marketplace.json are validated against a JSON Schema synthesised from Anthropic's published docs, the unofficial hesreallyhim schema, and real plugin manifests in the wild. The schema lives inside the binary via //go:embed.
Eight exact marketplace names are reserved by Anthropic plus an impersonation pattern for variants like official-claude-plugins. Hanko catches these locally so you don't waste a submission round.
Claude Code v2.1+ auto-loads hooks/hooks.json by convention. Declaring it explicitly in hooks: causes a double-load error. Hanko flags this before you submit.
The docs example for agents shows a bare directory string, but the validator actually rejects it (issue #44777). Hanko suggests the array-of-files fix and a doc link.
Layer extra rules on top of the base schema with hanko submit-check --marketplace <name>. Supports Anthropic official, buildwithclaude, cc-marketplace, and claudemarketplaces.
Drop in uses: RoninForge/hanko@v0 and Hanko runs on every PR, writing a sticky summary comment with the findings table.
Every rule has a stable identifier (HANKO001, HANKO002, …) so CI scripts can pin or skip specific rules without relying on wording.
| ID | Severity | What it catches |
|---|---|---|
| HANKO000 | error | File is not valid JSON. |
| HANKO-SCHEMA | error | Any violation of the embedded JSON Schema (type mismatch, missing required field, pattern violation, path traversal, kebab-case). |
| HANKO001 | error | Duplicate hooks declaration. Plugin hooks points at ./hooks/hooks.json which Claude Code v2.1+ already auto-loads. |
| HANKO002 | error | agents is set to a bare directory string, which the official validator rejects. |
| HANKO003 | warning | author is missing. Claude Desktop's listAvailablePlugins refuses to load catalogs that contain any plugin without one. |
| HANKO004 | warning | version is missing. Claude Code's install cache keys on this field, so users will not see updates. |
| HANKO101 | error | Marketplace name is on Anthropic's exact-match reserved list (claude-code-plugins, anthropic-marketplace, etc.). |
| HANKO102 | warning | Marketplace name matches the impersonation pattern (official-claude-*, anthropic-tools-v*). |
| HANKO103 | error | Two or more plugins in the marketplace catalog share the same name. |
| Command | Purpose |
|---|---|
| hanko check [path] | Validate a plugin manifest, a marketplace manifest, or a directory containing either. Base rules only. |
| hanko submit-check --marketplace <name> | Layer marketplace-specific rules on top of the base schema. Use right before submitting. |
| hanko schema print --file <plugin|marketplace> | Emit the embedded JSON Schema for editor autocomplete. |
| hanko --json | Output findings as JSON for CI consumption. Available on check and submit-check. |
| hanko version | Print version, commit, and build date. |
Drop this into .github/workflows/plugin.yml. The action posts a sticky summary comment on every PR with the validation table.
name: Plugin validation on: pull_request: paths: [ '.claude-plugin/**' ] jobs: hanko: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: RoninForge/hanko@v0 with: marketplace: anthropic
Hanko's binary opens zero sockets. Validation happens offline against embedded schemas.
No crash reports, no usage analytics. Source is MIT, 100% Go, auditable in an afternoon.
Hanko validates manifests. It does not submit them for you, talk to Anthropic, or require an API key.
Both Claude Code plugin manifest files: .claude-plugin/plugin.json (your plugin's metadata) and .claude-plugin/marketplace.json (a marketplace catalog listing plugins). It runs the file through an embedded JSON Schema plus a set of Go-coded rules that catch the cases the official validator reports opaquely.
hesreallyhim/claude-code-json-schema is a JSON Schema file plus a thin Ajv CLI wrapper. Hanko adds: a single-binary Go install, the reserved marketplace names catalog, duplicate hooks detection, the agents-as-bare-directory footgun, pretty error output with fix suggestions, and per-marketplace rule layering. We embedded and credit the hesreallyhim schema as a starting point.
No. Hanko is a local validator. It reads your files and reports issues. Submission to the Anthropic marketplace, buildwithclaude, or any other marketplace is a separate step you do yourself.
No. Hanko's binary has zero network calls. The install script downloads from GitHub Releases and that is the only time bytes cross the network. The validator itself runs fully offline.
Hanko (判子) is the personal seal Japanese employees use to stamp official documents. The ritual act of approving a submission. The tool serves the same purpose for plugin manifests: stamp it with hanko before you submit.
Run curl -fsSL https://roninforge.org/hanko/install.sh | sh. This downloads a single Go binary from GitHub Releases and installs it to /usr/local/bin (or ~/.local/bin as a fallback). Or use Homebrew: brew install roninforge/tap/hanko. Supports macOS, Linux (amd64, arm64), and Windows (amd64).
Yes. Add uses: RoninForge/hanko@v0 to your workflow. The action runs hanko against your repo on every PR and posts a sticky comment with the validation summary.
Hanko is part of RoninForge. Sibling: Tsuba (scaffolds plugins that hanko validates). Also shipped: BudgetClaw (Claude Code spend monitor).