implementation / P1
Managing portable Skills across AI harnesses
How teams can manage portable AI Skills across Claude, Codex, Cursor, ChatGPT, and other harnesses with Fygment registry and CLI workflows.
Portable Skills become manageable when a governed registry, the fygment CLI, local inventory, lockfiles, and check/update flows keep supported harness installs reviewable.
How it works
Direct answer
Manage portable AI Skills across supported harnesses by treating Fygment as the governed registry, then using the shipped `fygment` CLI loop to set up harness access, install approved Skill packages, list local inventory, write a portable `fygment.lock`, sync another machine, and run `fygment check` plus `fygment update` when installs drift.
The supported harness model
Fygment is built around AI harnesses, not a two-client world. Hosted MCP setup covers OAuth-capable clients such as Claude, ChatGPT, Manus, and Perplexity; local setup guidance names Codex CLI, Claude Code, Cursor, Gemini CLI, and Antigravity where that path is available.
For local Skill installs, the first official end-to-end writable targets remain `codex`, `claude-code`, and `claude-desktop`. The CLI also treats older Codex aliases such as `openai-codex` and `openai_codex` as Codex-compatible target names, while broader harness automation stays labeled as alpha or roadmap until each target has its own smoke evidence.
Install, check, update
The public CLI language is intentionally package-manager-like, but scoped to managed Skills and selected harness folders.
- 1
Start with guided setup
Run `npx fygment` or `fygment setup --workspace=<slug>` to sign in, choose supported setup targets, configure the Fygment MCP connector, and install the companion Fygment Skill where the selected harness has a stable local Skill folder convention.
- 2
Install an approved Skill
Run `fygment install <slug> --target=codex`, `--target=claude-code`, or `--target=claude-desktop` for the first writable local targets. The CLI exports the approved package, confirms the local write unless `--yes` is provided, installs into the target folder, records the checksum, and reports the install back to the workspace when tracking is available.
- 3
Check local state
Run `fygment check [--target=codex|claude-code|claude-desktop]` to compare local installs with the workspace. Current installs are safe to keep, stale installs can warn with an update recommendation, and blocked or revoked installs are marked not safe to run.
- 4
Update deliberately
Run `fygment update [slug ...]`, `fygment update --all`, or add a target filter. The CLI refreshes eligible installs through the same install path and skips or blocks updates when workspace policy says the local version should not be replaced automatically.
CLI commands teams use
These are the shipped commands that make portable Skills manageable without hand-copying folders between machines.
| Command | Purpose | Boundary |
|---|---|---|
| `fygment setup` or `npx fygment` | Guided first-time setup for workspace sign-in, MCP connector configuration, and companion Skill installation for supported setup targets. | MCP setup targets are not the same as every Skill install target; do not imply Claude Desktop MCP setup unless that surface ships. |
| `fygment install <slug> --target=...` | Installs an approved Skill package into Codex, Claude Code, Claude Desktop, or another explicitly supported install target. | The first writable targets are not the full product boundary. The CLI asks before writing locally unless `--yes` is used, and it does not delete unrelated local files. |
| `fygment list [--json] [--paths]` | Shows managed installs plus local Skill candidates for recognized harness roots so teams can see what is tracked and what is merely present on disk. | Raw local paths stay hidden by default and only appear when `--paths` is explicitly requested. |
| `fygment lock write` | Writes a portable `fygment.lock` with Skill slug, version, target, checksum, generated time, and optional workspace metadata. | The lockfile is Skills-only; it excludes secrets, tokens, raw local paths, MCP servers, and arbitrary CLI state. |
| `fygment sync --lock=fygment.lock --dry-run` | Plans the installs and skips needed to reproduce the managed Skill setup on another machine before any writes occur. | Sync installs missing or mismatched managed Skill targets and leaves unmanaged local files untouched. |
| `fygment doctor` | Reports config, workspace, install registry, default harness paths, lockfile default, and local root scan status. | Diagnostics avoid tokens and do not require exposing paths except where the command itself is reporting default harness locations. |
Trust and safety states
Fygment keeps Skill package state separate from arbitrary local cleanup.
Live now
Checksummed installs
Installed Skill records include the version, target, path, checksum, and install time, so local state can be compared with the approved registry package instead of trusting a copied folder name.
Live now
Approvals and runtime policy signals
`fygment check` and `fygment update` can surface current, stale, blocked, and revoked states. Current installs are safe to keep, stale installs warn or recommend refresh, and blocked or revoked installs are not safe to run.
Alpha
Portable local inventory
`fygment list`, `fygment lock write`, and `fygment sync` are available as a Skills-only alpha workflow for the first writable targets, with dry-run planning and path redaction by default.
Roadmap
Broader harness automation
Marketplace-scale rollout policy, more setup targets, and wider harness automation should stay roadmap-labeled until their own install, rollback, and smoke evidence exists.
What Fygment does not do locally
The CLI does not treat your machine as a general-purpose cleanup target. Lockfile sync installs missing or mismatched managed Skill targets, skips current entries, and states that unmanaged local files are untouched.
That boundary is important for team trust: Fygment can make approved package state reproducible without claiming ownership over every local prompt, MCP server, or hand-written config file a developer already has.
FAQ
Can one Skill work across more than one AI harness?
Yes, when the Skill package is authored for the relevant harness compatibility and installed or exposed through an approved export target. Fygment keeps the package version, checksum, approval state, and target-specific install record together.
Which target names should I use first?
Use `codex`, `claude-code`, and `claude-desktop` for the current Skills install and lockfile loop. Codex aliases such as `openai-codex` and `openai_codex` normalize to Codex-compatible installs.
Is `fygment.lock` shipped or only planned?
`fygment lock write` and `fygment sync --lock=fygment.lock` are shipped as an alpha, Skills-only workflow. The lockfile records managed Skill targets, versions, and checksums, but not secrets, tokens, raw local paths, MCP servers, or arbitrary CLI state.
Will sync delete local Skills that are not in the lockfile?
No. Sync installs missing or mismatched managed Skill targets and skips current entries. Unmanaged local files are left untouched.
How does a team know whether an installed Skill is still safe?
Run `fygment check`. The CLI can report current, stale, blocked, and revoked states; blocked or revoked installs are marked not safe to run, while stale installs recommend or require an update depending on policy.
How does this relate to the broader registry resources?
Start with the AI Skills registry page for the governed package model, the MCP setup for teams page for connector setup, and the hand-edited config comparison for why local JSON and copied folders do not scale by themselves.
Related resources
- What is an AI Skills registry?
An AI Skills registry is the shared inventory, review surface, and package lifecycle for reusable agent capabilities that need ownership, versioning, and install state.
- How teams should manage MCP setup
MCP setup should be managed as shared configuration with ownership, review, install instructions, and a clear boundary between local credentials and team policy.
- Fygment vs hand-edited agent configs
Hand-edited agent config is fine for a small personal setup, but teams eventually need governed packages, reproducible installs, approvals, and visible setup health.