The public skills repo doesn't have a companion for app developers porting from Harper v4 to v5. The canonical v5 Migration Guide covers what changed, but it's not packaged as an installable skill — nothing triggers when an agent is editing v4 Harper code.
The internal harper-v4-to-v5-migration skill (in HarperFast/skills-internal) is operator-shaped — focused on Fabric / hosted-cluster cutovers, explicitly defers app-side changes to the canonical guide. Leaves a gap for the dev-shaped case.
What's actually needed
Most of the migration content already exists in the canonical guide — a Claude session that's explicitly asked about upgrading will likely web-search it. The real value-add of a skill would be discovery and unprompted activation, plus a small set of traps that aren't yet in the guide:
-
Auto-trigger on v4 patterns (from 'harperdb', engines.harperdb, static loadAsInstance = false, etc.) so an agent doing unrelated work in a v4 codebase surfaces the upgrade context unprompted. Even a thin SKILL.md that activates and points at the canonical guide is useful.
-
Field-tested app-side traps the canonical guide doesn't have (yet):
Resource.delete({...}) filter-style trap- CJS/ESM interop on certain CommonJS packages (
fast-xml-parser XMLParser named-export error)
applications.lockdown block trial-and-errorimport.meta.dirname undefined under the VM loader (pre-5.0.11)@fastify/static < 9 routing break
-
Optional: pre-baked scan recipes (rg one-liners) that find every v4-ism in a codebase.
Suggested shape
A thin skill — harper-v4-to-v5-upgrade/ with one SKILL.md and maybe one rules/ file. Not a full duplicate of the canonical guide; a trigger + pointer + field-tested traps. ~100 lines total. Internal harper-v4-to-v5-migration skill in HarperFast/skills-internal has reusable content: pre-flight-checks.md scan recipes + Module/Import & Auth/Sessions sections of error-fingerprints.md are largely dev-facing and could be sanitized and ported.
Out of scope
- Fabric / cluster cutover mechanics (internal-skill territory).
- v5 onboarding / "how to build on Harper v5" —
harper-best-practices already does this.
- Duplicating the canonical migration guide.
References
The public skills repo doesn't have a companion for app developers porting from Harper v4 to v5. The canonical v5 Migration Guide covers what changed, but it's not packaged as an installable skill — nothing triggers when an agent is editing v4 Harper code.
The internal
harper-v4-to-v5-migrationskill (inHarperFast/skills-internal) is operator-shaped — focused on Fabric / hosted-cluster cutovers, explicitly defers app-side changes to the canonical guide. Leaves a gap for the dev-shaped case.What's actually needed
Most of the migration content already exists in the canonical guide — a Claude session that's explicitly asked about upgrading will likely web-search it. The real value-add of a skill would be discovery and unprompted activation, plus a small set of traps that aren't yet in the guide:
Auto-trigger on v4 patterns (
from 'harperdb',engines.harperdb,static loadAsInstance = false, etc.) so an agent doing unrelated work in a v4 codebase surfaces the upgrade context unprompted. Even a thin SKILL.md that activates and points at the canonical guide is useful.Field-tested app-side traps the canonical guide doesn't have (yet):
Resource.delete({...})filter-style trapfast-xml-parserXMLParsernamed-export error)applications.lockdownblock trial-and-errorimport.meta.dirnameundefined under the VM loader (pre-5.0.11)@fastify/static < 9routing breakOptional: pre-baked scan recipes (
rgone-liners) that find every v4-ism in a codebase.Suggested shape
A thin skill —
harper-v4-to-v5-upgrade/with one SKILL.md and maybe one rules/ file. Not a full duplicate of the canonical guide; a trigger + pointer + field-tested traps. ~100 lines total. Internalharper-v4-to-v5-migrationskill inHarperFast/skills-internalhas reusable content:pre-flight-checks.mdscan recipes + Module/Import & Auth/Sessions sections oferror-fingerprints.mdare largely dev-facing and could be sanitized and ported.Out of scope
harper-best-practicesalready does this.References
HarperFast/agent-example-harper#2— concrete v4→v5 PR exercising the changes.