portable-resume-skills

Offline, local-only context migration · 17 sources × 18 hosts (derived from registries) · inert handoff, not live restore

English · 繁體中文 · 简体中文 · 日本語 · 한국어 · Español · Português · Français · Deutsch · Русский · العربية · हिन्दी · All languages

Clean-room-oriented Agent Skills for migrating bounded local coding-agent context into a fresh session. Readers never invoke the source agent CLI and never add a network path; recovered text is marked untrusted and stale.

Current release: 0.4.2 · PyPI · 306/306 packaging and Ubuntu installed-runner cells (17 sources × 18 destinations). Windows native mutating install is supported (#125); Windows hard gate is focused product-install smoke (3 hosts), not full 306/306 on Windows. Published v0.4.1 / v0.4.0 remain historical; published v0.3.4 remains historical 81.

Host evidence boundary: v0.3.2-era checks cover 7/7 exact native local plugin/extension installs, 8/8 host-native headless Skill invocations, 6/6 compatible public marketplace installs, and Cursor/Kimi pickers. Fresh through 0.4.2 host reinstall/picker flows and Pi/OpenClaw native UI remain not-run (still not re-run on this tip).

Release candidate on main: exact package version 0.4.2 (tag v0.4.2). Build/release reports still add +g<commit>[.dirty] only for dirty/dev checkouts; this release pin uses the clean exact version. Artifact builds pin one canonical identity before producing bytes. Repository-level immutable v* tag enforcement remains active (ruleset 20148806).

Sources and destinations

Destination profiles: Claude Code, Codex, Cursor, OpenCode, Antigravity, Grok Build, Qwen Code, Kimi Code CLI, Pi agent, OpenClaw, goose, Crush, Cline, OpenHands, Hermes Agent, GitHub Copilot CLI, Gemini CLI (compat, not Antigravity), and Kilo CLI (destination-only).

Requirements

• Python 3.11+; CI covers 3.11–3.14 on Ubuntu and macOS.
• Product runtime is stdlib-only.
• Optional trusted zstd binary for compressed Codex rollouts.

Quick start

Install the published package, then install every destination profile into its user-global Skill root:

pipx install portable-resume
install-resume-skills quick-install all

From a source checkout, use pipx install . instead. To install only one host or one project:

install-resume-skills quick-install qwen
install-resume-skills quick-install qwen --project "$PWD"

For a host-native public marketplace install, add the portable-resume-marketplace:

# Claude Code
claude plugin marketplace add ImL1s/portable-resume-marketplace
claude plugin install portable-resume@portable-resume --scope user

# Codex
codex plugin marketplace add ImL1s/portable-resume-marketplace
codex plugin add portable-resume@portable-resume

Verified Cursor, Qwen, Grok, and Kimi commands plus direct Antigravity/OpenCode fallbacks are in docs/install-hosts.md.

The lower-level transactional command remains available for previews, custom roots, verification, and uninstall:

Installed (pipx/pip):

# Inspect capabilities and the registry-derived matrix
portable-resume --version
install-resume-skills --version
portable-resume self-check --json
install-resume-skills matrix
install-resume-skills hosts --json

# Preview, install, verify, and uninstall one destination
install-resume-skills install \
  --host qwen --scope project --project "$PWD" --dry-run
install-resume-skills install \
  --host qwen --scope project --project "$PWD"
# Selected sources are recorded in the ownership claim; verify intentionally
# takes no --sources argument and checks the recorded install plan.
install-resume-skills install \
  --host qwen --scope project --project "$PWD" --sources codex,grok
install-resume-skills verify \
  --host qwen --scope project --project "$PWD"
install-resume-skills uninstall \
  --host qwen --scope project --project "$PWD" --dry-run

From a source checkout (no install):

PYTHONPATH=src python3 scripts/portable-resume --version
PYTHONPATH=src python3 scripts/install-resume-skills --version
python3 scripts/check_version_state.py --require-git --json
PYTHONPATH=src python3 scripts/portable-resume self-check --json
PYTHONPATH=src python3 scripts/install-resume-skills matrix
PYTHONPATH=src python3 scripts/install-resume-skills hosts --json
PYTHONPATH=src python3 scripts/install-resume-skills install \
  --host qwen --scope project --project "$PWD" --dry-run

The synthetic fixture exists only in a source checkout:

PYTHONPATH=src python3 scripts/portable-resume claude show latest \
  --cwd /workspace/project \
  --source-root tests/fixtures/claude/s-cla-01-ordered-parent-chain/root \
  --format handoff

Full roots, activation grammar, direct archives, and marketplace/plugin routes are in docs/install-hosts.md. Release assets are generated with:

python3 scripts/build_host_packages.py --output-dir host-packages

Published v0.3.4 archives include nine direct-skill ZIPs (including Pi) plus supported Claude, Codex, Cursor, Antigravity, Grok, Qwen, and Kimi plugin/marketplace bundles. Current main development builds derive direct ZIPs from all 18 enabled destinations. OpenCode remains a direct Skill install because its plugin surface is executable JavaScript/TypeScript rather than a Skill bundle.

Skill contract

python3 <skill>/scripts/run_reader.py show latest --cwd "$PWD" --json
python3 <skill>/scripts/run_reader.py show <session-id|path|text> --cwd "$PWD" --json
python3 <skill>/scripts/run_reader.py list --cwd "$PWD" --json

Activate resume-<source> using the host's documented grammar, run only the installed reader, and summarize its inert output after re-checking the repository. portable-resume/request-v1 files remain an optional advanced interface.

Safety invariants

• Source stores are immutable; stable no-follow reads fail closed on races.
• Source CLIs are never invoked.
• Recovered text is inert/untrusted and only best-effort redacted.
• Installer paths are contained under the selected skill root.
• Non-owned collisions require --force-with-backup; multi-root installs compensate on failure.
• Shared physical roots with divergent host renders fail before mutation.

Tests and CI/CD

Run all required local gates:

python3 scripts/self_verify.py
python3 scripts/check_secrets.py
PYTHONPATH=src python3 -m unittest discover -s tests -q
PYTHONPATH=src python3 scripts/smoke_installed_matrix.py

.github/workflows/ci.yml runs those gates across Ubuntu/macOS and Python 3.11–3.14, then builds the wheel/sdist twice from one identity pin and epoch under different parent umasks, requires byte-for-byte reproducibility, proves the source package was not mutated, verifies the same embedded identity across all 27 generated artifacts in four artifact families, and smoke-installs the exact wheel and sdist with poisoned build-pin environment variables removed from child processes. .github/workflows/release.yml accepts only annotated vMAJOR.MINOR.PATCH tags reachable from main, re-runs dual-OS gates, builds release bytes once from one pinned identity, tests those exact bytes, creates SHA-256 checksums and GitHub attestations, stages a GitHub Release, and publishes through PyPI Trusted Publishing.

src/portable_resume/resources/latest-release.json records the immutable latest published identity. Normal CI fetches release tags and fails if changed source reuses a published stable version. The protected release path rejects development versions; after every release, main advances immediately to the next .dev0 line.

Published release v0.3.4 also verifies the GitHub Release layout itself: every SHA256SUMS entry is a flat asset basename, and both Ubuntu and macOS validate a simulated flat download before publication. The immutable v0.3.4 release run, commit, public checksum/attestation checks, GitHub Release, PyPI, and marketplace evidence are archived in docs/evidence-summary.md.

Key documentation

• docs/i18n/README.md — 12 localized quick-start guides
• docs/diagnostics.md — exit codes and machine diagnostics
• docs/STATUS.md — done/not-done truth
• docs/install-hosts.md — per-host installation
• docs/source-formats.md — format and provenance registry
• docs/host-ui-smoke.md — live activation evidence protocol
• docs/release-claim.md — release gates and external setup
• SECURITY.md — threat model
• CONTRIBUTING.md — contributor workflow

License and limitations

Apache-2.0. This project is not affiliated with the host vendors. Do not copy ~/.grok/bundled/skills/** into this tree.

Eight host CLI surfaces have recorded headless slash/name activation evidence; Pi native activation remains not-run. Public marketplace installation on six compatible hosts, including Cursor and Kimi picker flows, is recorded for v0.3.2; fresh through 0.4.1 host-by-host reinstall remains not-run. Other visual Skill pickers and vendor-curated directory listings are not claimed; Cursor's full bubble graph is not claimed; redaction is not complete DLP.