v0.3: portable skill for Codex, Cursor, Hermes, and Claude Desktop

[ccf]

Summary

v0.3 makes the same humanize skill installable on Claude Code, Codex CLI, Cursor, Hermes Agent, and the Claude Desktop app through each harness's own installer, and repositions the public copy: humanize is grounded in the thirteen studies in references/SOURCES.md and covers every layer of a text, with StoryScope named where it is the source of a number.

Spec: docs/design/2026-09-14-humanize-v0.3-design.md (revision 2 after a three-lens adversarial review) · Plan: docs/design/2026-09-14-humanize-v0.3-plan.md (revision 2 after a worktree dry run).

Layout and manifests

• Plugin moved from plugins/humanize/ to the repository root: skills/humanize/, .claude-plugin/ (marketplace source is ./), new root plugin.json (Agent Plugins 1.0) and .codex-plugin/plugin.json with the Codex interface block.
• Version 0.3.0 in lockstep across the four manifests, pyproject.toml, and the CHANGELOG heading — tests/test_portability.py fails on drift.

Skill

• SKILL.md is harness-agnostic (still ≤ 150 lines): argument-hint removed (a hard error outside Claude Code), relative python3 scripts/surface_scan.py path, Codex $humanize and plain-words options noted, document extraction described generically. No harness variables anywhere under skills/ (tested).

Tests, tooling, docs

• tests/test_portability.py: spec-only frontmatter; no harness-specific content; runtime references named; guard-clean scripts (Hermes skills_guard patterns); manifests agree; zip packager contract; study count matches SOURCES.md.
• tools/package_skill_zip.py builds the claude.ai skill upload (dist/humanize-skill-0.3.0.zip, attached to the release).
• tools/smoke_harnesses.sh: local acceptance matrix whose PASS rule needs evidence the scanner ran; transcripts under docs/acceptance/v0.3/.
• README install table (Claude Code, Codex, Cursor, Hermes, Cowork, claude.ai) with the verified gotchas; CLAUDE.md and BUGBOT.md invariants for portability and version lockstep.

Migration

Existing Claude Code installs: claude plugin marketplace update humanize && claude plugin update humanize@humanize.

Test plan

• uv run pytest -q -W error → 108 passed on 3.9 and 3.13; ruff clean; claude plugin validate --strict . passes
• Smoke matrix PASS on Claude Code, Codex, Cursor, Hermes (Task 7, in progress)
• codex plugin marketplace add ccf/humanize@feat/v0.3 installs from GitHub (pre-merge)
• CI green, Bugbot threads resolved
• Post-merge: Hermes skills install, Claude plugin upgrade 0.2.0 → 0.3.0, Cowork marketplace add; tag v0.3.0 + release with the zip; claude.ai upload

🤖 Generated with Claude Code

https://claude.ai/code/session_01KTKYvLEVY4mStJ3iPaB1Mh

---

Note

Low Risk
Packaging, docs, and compliance tests only; surface_scan.py behavior is unchanged. Main operational risk is install-path migration (source: "./") for existing Claude Code marketplace users.

Overview
v0.3.0 reframes humanize as a harness-portable agent skill: the package moves from plugins/humanize/ to the repo root (skills/humanize/, marketplace source: "./"), bumps version everywhere in lockstep, and adds Agent Plugins 1.0 (plugin.json), Claude (.claude-plugin/plugin.json), and Codex (.codex-plugin/plugin.json) manifests so the same skill installs on Claude Code, Codex, Cursor, Hermes, and Claude Desktop.

SKILL.md is made harness-agnostic: argument-hint and ${CLAUDE_PLUGIN_ROOT} go away, the scanner uses a relative <skill folder>/scripts/surface_scan.py path, audit rules require a row for every fired scanner block, and public copy grounds the tool in thirteen studies (SOURCES.md) rather than StoryScope-first positioning.

New enforcement and release tooling: tests/test_portability.py (frontmatter, no harness tokens under skills/, manifest/version/study-count sync, guard-clean scripts, zip contract), tools/package_skill_zip.py for claude.ai uploads, and tools/smoke_harnesses.sh with transcripts under docs/acceptance/v0.3/. README gains a per-harness install table; CLAUDE.md and BUGBOT.md document portability invariants. Migration: existing Claude Code users run marketplace + plugin update after merge.

^{Reviewed by Cursor Bugbot for commit a517f74. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2a39835. Configure here.}