How do I install the Portability skill?

Run npx skillmds@latest add harshanandak/portability in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Portability safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Portability?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Portability free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Portability?

harshanandak (@harshanandak) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Portability by harshanandak — Agent Skill

Name: Portability
Author: harshanandak

Portability

Forge kernel data portability — getting issue data in and out of the local kernel. `forge export [--dir] [--dry-run]` writes the kernel backlog to deterministic git-tracked JSONL (D16 portability projection); `forge export --import` reads that committed snapshot back into the kernel (hydrate). `forge migrate --from beads [--dry-run] [--source <dir>]` imports a Beads issue store into the kernel — the onboarding path for users coming from Beads. Use when the user says "export the kernel backlog to JSONL", "back up / snapshot the backlog", "re-import / hydrate the backlog", "migrate from beads", or "import a beads store". Honesty: bare `forge migrate --dry-run` (no `--from`) is v2→v3 preview only; a re-import that applies nothing reports "already hydrated". NOT the cloud/backend sync of the kernel (that is `forge sync`, cloud-native), NOT a database/schema migration (plan/dev), NOT memory notes (memory), NOT syncing a git branch with main (ship).

harshanandak 5570e05 3 files · 4.9 KB Updated Sep 17, 2026

File contents

Moving Forge kernel issue data across a boundary: project the backlog to a git-committable snapshot (and hydrate it back), or import an existing issue store into the kernel. This is data portability — distinct from schema/database migrations and from the cloud backend sync (forge sync).

Export / re-import the backlog

forge export                     # write the kernel backlog to git-tracked JSONL (deterministic)
forge export --dir <path>        # choose the projection directory
forge export --dry-run           # show what would be written, change nothing
forge export --import            # read the committed JSONL snapshot back INTO the kernel (hydrate)

forge export is the D16 portability projection: a deterministic, git-committable snapshot of the backlog you can review in a diff and carry between machines or checkouts. forge export --import is the reverse — it hydrates the kernel from that on-disk snapshot; a re-import that finds everything already present reports "already hydrated" rather than claiming it imported anything.

Migrate in from Beads (or preview v2→v3)

forge migrate --from beads [--dry-run]     # import a Beads issue store into the kernel
forge migrate --from beads --source <dir>  # point at exported beads *.jsonl (defaults to auto-detecting .beads/)
forge migrate --dry-run                    # preview the v2→v3 migration (the ONLY supported mode without --from)

forge migrate --from beads is the onboarding path for users coming from Beads — it imports a Beads issue store into the Forge Kernel (--dry-run reads + maps only, writing nothing). Without --from, migrate is v2→v3 preview only: --dry-run is required and applying the migration is not yet available.

Boundaries

The cloud/backend sync of the kernel is forge sync (cloud-native) — a different operation; this skill is the local, git-based portability projection.
A database/schema migration (adding a column, altering a table) is application work — that's plan/dev, not forge migrate.
Persisting a decision or note is memory (forge remember), not export.
Syncing a git branch with main before a PR is ship/worktree.

---name: portabilitydescription: Forge kernel data portability — getting issue data in and out of the local kernel. `forge export [--dir] [--dry-run]` writes the kernel backlog to deterministic git-tracked JSONL (D16 portability projection); `forge export --import` reads that committed snapshot back into the kernel (hydrate). `forge migrate --from beads [--dry-run] [--source <dir>]` imports a Beads issue store into the kernel — the onboarding path for users coming from Beads. Use when the user says "export the kernel backlog to JSONL", "back up / snapshot the backlog", "re-import / hydrate the backlog", "migrate from beads", or "import a beads store". Honesty: bare `forge migrate --dry-run` (no `--from`) is v2→v3 preview only; a re-import that applies nothing reports "already hydrated". NOT the cloud/backend sync of the kernel (that is `forge sync`, cloud-native), NOT a database/schema migration (plan/dev), NOT memory notes (memory), NOT syncing a git branch with main (ship).---Moving Forge kernel issue data across a boundary: project the backlog to a git-committable snapshot (and hydrate it back), or import an existing issue store into the kernel. This is data portability — distinct from schema/database migrations and from the cloud backend sync (`forge sync`).# Export / re-import the backlog```bashforge export # write the kernel backlog to git-tracked JSONL (deterministic)forge export --dir <path> # choose the projection directoryforge export --dry-run # show what would be written, change nothingforge export --import # read the committed JSONL snapshot back INTO the kernel (hydrate)````forge export` is the **D16 portability projection**: a deterministic, git-committable snapshot of the backlog you can review in a diff and carry between machines or checkouts. `forge export --import` is the reverse — it hydrates the kernel from that on-disk snapshot; a re-import that finds everything already present reports "already hydrated" rather than claiming it imported anything.# Migrate in from Beads (or preview v2→v3)```bashforge migrate --from beads [--dry-run] # import a Beads issue store into the kernelforge migrate --from beads --source <dir> # point at exported beads *.jsonl (defaults to auto-detecting .beads/)forge migrate --dry-run # preview the v2→v3 migration (the ONLY supported mode without --from)````forge migrate --from beads` is the **onboarding path for users coming from Beads** — it imports a Beads issue store into the Forge Kernel (`--dry-run` reads + maps only, writing nothing). Without `--from`, migrate is **v2→v3 preview only**: `--dry-run` is required and applying the migration is not yet available.## Boundaries- The **cloud/backend sync** of the kernel is `forge sync` (cloud-native) — a different operation; this skill is the local, git-based portability projection.- A **database/schema** migration (adding a column, altering a table) is application work — that's **plan**/**dev**, not `forge migrate`.- Persisting a decision or note is **memory** (`forge remember`), not export.- Syncing a git **branch** with main before a PR is **ship**/**worktree**.

Frequently asked questions