Skill management

A skill is a directory with a SKILL.md file and, optionally, scripts/, references/ and other assets. Skillporter moves that directory from a source into the places your harnesses read, and keeps track of what it wrote.

Sources

skillporter add accepts any of these.

Use --ref to pin a branch, tag or commit, and --skill to pick skills out of a repository that contains several:

skillporter add anthropics/skills --skill pdf --ref main --harness all

Source resolution never executes anything inside the fetched repository or archive. Git clones run with external protocol helpers, filesystem monitors and symlink checkout disabled. Archives are extracted with path, size and file-count limits. See the security model.

What happens during add

1. Resolve. The source is fetched into a temporary directory and the commit is recorded.
2. Validate. Each selected skill is checked against the Agent Skills specification.
3. Assess. The static security assessment runs. A blocking result stops here.
4. Plan. Destinations are computed per harness. Harnesses that share a directory are deduplicated.
5. Install. Files are staged and moved into place as one transaction.
6. Verify. The installed copies are checked.

--dry-run performs steps 1 to 4 and prints the plan.

Choosing harnesses

skillporter add ./skills/release-notes --harness claude-code --harness codex
skillporter add ./skills/release-notes --harness compatible --exclude-harness windsurf
skillporter add ./skills/release-notes --harness all

--harness accepts specific adapter IDs, detected (installed on this machine), compatible (NATIVE and COMPATIBLE adapters), or all. --exclude-harness subtracts adapters from that selection. Pass --isolated when targeting a harness such as Cursor or Gemini CLI that offers its own directory (.cursor/skills, .gemini/skills) alongside shared .agents/skills.

Without --harness, Skillporter uses the harnesses declared in skillporter.yaml, or the ones it detects as active in the workspace. Use skillporter harness list, skillporter harness inspect <id> and skillporter harness status to inspect adapter paths and shared peers before installing.

Moving and adopting skills

Move an installed skill between harnesses without deleting its source, or bring pre-existing unmanaged skills under Skillporter tracking:

skillporter move pdf --from claude-code --to cursor --isolated
skillporter adopt --all
skillporter outdated

Copy or symlink

--strategy copy is the default. Every destination gets real files, which works inside Docker build contexts, CI checkouts, git worktree and Windows clones.

--strategy symlink creates relative symlinks to one canonical copy. Edits show up everywhere at once, but the links break wherever symlinks are not preserved.

Project or user scope

--scope project (the default) writes inside the repository, for example .claude/skills/pdf. --scope user writes to your home directory, for example ~/.claude/skills/pdf, so the skill is available in every project.

Adapted rule files

Some harnesses also read rule files in their own format. --adapt writes those alongside the skill:

skillporter add ./skills/release-notes --harness cursor --adapt

Preview an adaptation without installing:

skillporter inspect ./skills/release-notes --preview-adapt cursor-mdc

Bundled scripts/ stay in the skill directory. They are not embedded in the rule file.

Conflicts and risk are separate decisions

• --force answers "may I overwrite what is already there?" It never bypasses a security block.
• --allow-risky answers "do I accept these security findings?" The findings are printed and the decision is written to .skillporter/audit.jsonl.

Structural escapes, such as a symlink that points outside the skill or a path traversal entry, cannot be accepted with either flag.

Removing a skill

skillporter remove pdf --harness cursor
skillporter remove pdf

When several harnesses share .agents/skills/pdf, removing the skill from one of them keeps the shared copy for the others. It is deleted when the last owner is removed.

Updating and rolling back

skillporter update pdf --dry-run
skillporter update pdf
skillporter rollback pdf

update fetches the recorded source again, runs the security gate, snapshots the current version to .skillporter/backups/ and replaces it. rollback restores the most recent snapshot. Skillporter keeps the ten most recent snapshots per skill.

How installs stay consistent

Installs across several harnesses are a single transaction.

• New content is staged under .skillporter/tmp/txn-<id>/.
• A write-ahead journal.json records every path that will be created or replaced before anything moves.
• If any destination fails, the destinations already written are restored.
• If the process is killed mid-install, a later Skillporter run in that workspace reads the journal and rolls back the unfinished transaction.
• Workspace changes are serialized with a cross-process lock, so two concurrent runs do not interleave.

Local state

Skillporter keeps its state in .skillporter/ at the workspace root:

Add .skillporter/ to .gitignore. Commit skillporter.yaml and skillporter.lock.