docs(skill): add agent-hub-release skill for publishing sidecar agents

[kovtcharov]

Releasing a sidecar agent to the Agent Hub today means reverse-engineering release_agent_email.yml and its packaging scripts every time — the knowledge lives only in workflow comments. This adds a reusable Claude skill that captures the whole pipeline as a phased checklist, so the next agent's release (and the email agent's own) is a guided process instead of an archaeology session.

The skill generalizes the email agent as the reference implementation: freeze → Agent Hub Worker /publish (immutable, server-checksummed) → regenerate binaries.lock.json with real hashes → fetch-verify → npm publish via OIDC → website redeploy. It documents the per-agent file layout, the gaia-agent.yaml manifest, the three version numbers that must match before tagging, the one-time agent-publish gate + infra setup, and the load-bearing invariants (immutable-per-filename, publish-only-from-main, best-effort Intel, SCHEMA_VERSION MAJOR compat gate, OIDC-tied-to-filename).

Single file: .claude/skills/agent-hub-release/SKILL.md (directory + SKILL.md, matching the existing gaia-release / gaia-testing skills).

Test plan

• Skill frontmatter (name, description) parses like the sibling skills under .claude/skills/.
• Every referenced path resolves on main: release_agent_email.yml, gaia-agent.yaml, workers/agent-hub/schemas/manifest.schema.json, the packaging scripts, binaries.lock.json.
• Claims trace to the source: tag namespace agent-pkg-<id>-*, main-only publish guard, OIDC tied to the workflow filename, 3-required + best-effort-Intel platform matrix.

[github-actions]

Summary

Solid, genuinely useful skill — it turns the email-agent release pipeline into a guided checklist, and almost every load-bearing claim traces cleanly to the source. I verified the workflow invariants one by one against release_agent_email.yml and the packaging/Worker code, and they hold: the agent-pkg-email-* tag namespace, the main-ancestry publish guard, the agent-publish gate with GAIA_HUB_TOKEN as an environment secret, the three-version match step, the best-effort-Intel drop, the post-publish fetch-verify gate, and the OIDC-tied-to-filename warning are all accurate.

The one thing to fix before merge: the skill describes the npm client package in a shape that doesn't match the reference package on main in two places. Since this skill's entire value proposition (and its own test plan) is "claims trace to the source," these should be corrected so the next author following it literally doesn't hit a wall.

Issues Found

🟡 Important

CHANGELOG.md is referenced as part of the reference package but doesn't exist there (SKILL.md:62,64,84,97,107,191)

The skill states files includes CHANGELOG.md and tells the author to "confirm CHANGELOG.md/README.md ship" via npm pack --dry-run. But hub/agents/npm/agent-email/ has no CHANGELOG.md, and package.json files is ["dist/", "binaries.lock.json", "README.md", "LICENSE"] — no CHANGELOG. Following this literally, the test-plan dry-run check fails and the "add the matching CHANGELOG entry" step has no file to edit. Either add a CHANGELOG.md to the reference package and to files, or soften the skill to "create CHANGELOG.md and add it to package.json files" so it reads as a setup step, not an existing fact.

The ./client second entry point / client-entry.ts don't exist in the reference (SKILL.md:62,65,77-78)

The skill claims the package exposes "Two entry points: . (Node) and ./client (browser/Electron renderer: EmailClient only, zero Node built-ins)" and lists client-entry.ts (browser) in src/. In the reference, package.json exports has only .; there is no client-entry.ts; EmailClient is exported from the single index.ts entry (src/index.ts:20). A new agent mirroring email per this skill would build a browser entry point that the reference doesn't actually have. Recommend correcting to the real single-entry shape (or explicitly marking the browser-safe export as planned, if that's the intent).

🟢 Minor

The illustrative src/ row also omits files that are present (index.ts, logger.ts, platform.ts, url.ts). Fine to leave as illustrative — but dropping the invented client-entry.ts (above) is the part that matters.

Strengths

• The hard parts are right. Every irreversible/contract claim I spot-checked against the workflow and Worker is accurate — tag namespace, main-only ancestry guard, env-scoped publish token, three-version gate, best-effort-Intel drop-and-ship-3, fetch-verify as the real integrity gate, immutable-per-filename, and the rclone→gaia-hub manual fallback. That's the expensive knowledge to capture, and it's captured correctly.
• Right format and placement. Single SKILL.md under its own directory with name/description frontmatter matching the sibling gaia-release / gaia-testing skills.
• Teaches the why, not just steps — the OIDC-tied-to-filename warning and the WAF-blocks-uploads rationale for GAIA_HUB_PUBLISH_URL are exactly the gotchas that bite on a first release.

Verdict

Request changes — doc-only, low-risk, but two repeatedly-referenced npm-package facts don't match the reference on main, and one of them breaks a step the skill's own test plan asserts. Fix the CHANGELOG.md and ./client/client-entry.ts descriptions (align the reference package or soften the wording) and this is a clear merge. No security concerns; no prompt-injection content in the diff.