---
title: "Import Existing Work"
slug: "skillset/guides/importing"
description: Adopts supported provider-native material into canonical Skillset source without overwriting existing source or changing runtime configuration.
---

<a id="import-existing-work"></a>

Importing turns selected [provider-native](/skillset/glossary/#provider-native) or Agent standards material into reviewable [canonical source](/skillset/glossary/#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.

```bash
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:

```bash
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:

```bash
skillset init --adopt all --yes
```

Adoption preserves originals, stages imported source under `.skillset/`, validates it, runs an isolated [projection](/skillset/glossary/#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](/skillset/reference/cli/init/).

## 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:

```bash
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](/skillset/glossary/#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](/skillset/reference/cli/import/).

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

```bash
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](/skillset/glossary/#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](/skillset/glossary/#target-native-island).
2. Resolve lint, identity, reference, or [unsupported-destination diagnostics](/skillset/configuration/project-configuration/#handle-unsupported-destinations).
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](/skillset/reference/support-matrix/) shows current support, and [ADR-0024](https://github.com/outfitter-dev/skillset/blob/24800e02ed4e7150ea1bc7130c35603c98ea9da2/docs/adrs/0024-one-action-repo-adoption.md) records the adoption rationale for the [workspace](/skillset/glossary/#workspace) workflow.

If import refuses a path or adoption reports a conflict, follow [troubleshooting](/skillset/troubleshooting/) before changing source by hand.

Importing changes repository source only. [Activation](/skillset/glossary/#activation), installation, trust, and user-level provider configuration remain separate workflows.