Import Existing Work

Importing turns selected provider-native or Agent standards material into reviewable canonical source. Choose the workflow by scope: survey a whole repository with init --adopt, or import one known skill or plugin with import.

Survey a repository

Use this path when an existing repository may contain several provider directories, skills, plugins, or instruction files.

skillset init

The preview reports setup and adoption candidates. If you do not want to adopt them, a plain confirmed initialization scaffolds Skillset without importing them:

skillset init --yes

If you do want to adopt surveyed material, do not scaffold first. Select a stable candidate id or explicitly choose all candidates, then confirm setup and adoption together:

skillset init --adopt all --yes

Adoption preserves originals, stages imported source under .skillset/, validates it, runs an isolated projection, and records an audit report. It does not write live provider output. Conflicting identities, versions, portable metadata, or divergent source block instead of being merged by name alone.

Review the exact route in the generated init reference.

Import one explicit source

Use direct import when you already know the path to one skill, a skill collection, one plugin, or a plugin collection:

skillset import /path/to/SKILL.md
skillset import /path/to/plugin

Direct import writes source immediately; it has no --yes preview mode. Skillset stages and writes each imported source unit separately and refuses to overwrite an existing source path. During a collection import, an earlier unit can remain written if a later unit fails. If a directory is ambiguous, use --kind as documented in the generated import reference.

Origin shortcuts are an explicit request to inspect a known local provider or Agent Skills origin:

skillset import claude
skillset import agents

claude, codex, and cursor name providers. agents names the Agent Skills standard root at ~/.agents/skills; it is not a provider. Use shortcuts deliberately. Import does not silently scan user-level origins during ordinary build or check operations.

Preserve imported material

A skill import treats the containing skill directory as the unit, even when the selected path is its SKILL.md. Sibling references/, scripts/, assets/, agents/, and other sidecars are copied into canonical source with it. Collection imports follow linked skill directories but de-duplicate identical real paths.

Plugin imports accept Skillset source plugins, supported Claude, Codex, or Cursor native plugin directories, and closed Agent Plugins 1.0 packages. Agent Plugins import maps the portable manifest, immediate-child skills, MCP model, and recognized neutral support files back into canonical source; unmappable extensions or extra files block the write rather than disappearing. Native manifests are preserved, and Skillset synthesizes a minimal source skillset.yaml when the imported plugin has no source config.

Import preserves recognized source frontmatter, provider-native fields, and unknown fields instead of silently dropping them. Review the report’s copied files, inferred source fields, preserved provider-native fields, unsupported fields, warnings, and next checks before building. These categories describe what Skillset understood and what still needs human judgment; they do not claim every preserved field is portable.

Review what became source

After either workflow:

1. Inspect the new .skillset/ files and any reported transformations or preserved target-native islands.
2. Resolve lint, identity, reference, or unsupported-destination diagnostics.
3. Preview the first build with skillset build.
4. Confirm it with skillset build --yes.
5. Run skillset check --only outputs and review the generated diff.

Provider-specific material may remain explicit rather than being forced into a fake portable abstraction. The support matrix shows current support, and ADR-0024 records the adoption rationale for the workspace workflow.

If import refuses a path or adoption reports a conflict, follow troubleshooting before changing source by hand.

Importing changes repository source only. Activation, installation, trust, and user-level provider configuration remain separate workflows.