# Import skills, agents & MCP servers

Project import encrypts and preserves agent instructions, skill content, and MCP configuration, but quarantines them. Activation is a separate command because these files can change model behavior, run tools, reach remote services, or execute local programs in the Coding Workspace.

## Prerequisites

- Run from a folder already bound by `hlix import`
- Review the complete file you are importing
- Confirm that referenced secret keys belong to this project and workspace
- For MCP, understand whether the server is remote or starts a process
**Import is a trust decision:** Only import resources you would allow an agent to follow or execute. Encryption protects storage and transport; it does not make instructions or code trustworthy.

## Activate a resource

Each resource type has its own command and its own approval. Pick the one you are importing.

**A skill** is a reviewed `SKILL.md` that gives agents a named capability.

Pass a `SKILL.md` file or a folder containing one:

```bash
hlix skill import .agents/skills/release/SKILL.md
```

Override the derived slug when needed:

```bash
hlix skill import .agents/skills/release --name release-checks
```

Expected result: the CLI prints the imported skill identity. The skill becomes an explicit project resource rather than being activated merely because the scanner found it.

Verification:

```bash
hlix skill import .agents/skills/release --name release-checks --json
```

The JSON response contains metadata, not secret values.

**An agent** is a Markdown instruction brief that becomes a project-scoped agent record.

Agent import accepts one Markdown instruction file:

```bash
hlix agent import AGENTS.md --name "Repository builder"
```

Select the runtime and sandbox profile explicitly when the defaults are not right:

```bash
hlix agent import AGENTS.md \
  --name "Repository builder" \
  --runtime claude-code \
  --profile builder
```

Supported runtime values are `claude-code`, `codex`, `cursor-agent`, and `hlix`. Supported profiles are `builder`, `desktop`, and `e2e`.

Expected result: the imported agent is associated with the bound project and carries the exact reviewed Markdown instructions.

**An MCP server** is a tool server agents may call — the one resource that can reach the network or execute a local program.

For a file containing one server:

```bash
hlix mcp import .mcp.json
```

When the file contains several servers, name the one being approved:

```bash
hlix mcp import .mcp.json --server github
```

Remote servers must use HTTPS. URLs with embedded credentials, query strings, or fragments are refused, as are endpoints targeting loopback, private, link-local, or cloud-metadata hosts.

### Stdio servers

Stdio MCP starts an executable inside the Coding Workspace, so it requires an extra approval flag:

```bash
hlix mcp import .mcp.json --server filesystem --allow-stdio
```

The command must be one of the supported direct executables: `bunx`, `deno`, `node`, `npx`, `python`, `python3`, or `uvx`. Shell wrappers and shell syntax are refused; `--allow-stdio` is not permission to run an arbitrary command string through a shell.

### MCP secrets

Only environment **key names** are imported from MCP configuration. Literal secret values are not sent as part of the MCP server definition. At task time, hlix resolves those names from the project's encrypted secrets. A remote header must be exactly `${KEY}` or one approved authentication scheme followed by it, such as `Authorization: Bearer ${TOKEN}`; extra prefix or suffix text is refused. A sensitive stdio argument value must be exactly one `${KEY}` placeholder, and high-confidence literal tokens are refused in every argument.

For example, configuration may declare that a server needs `GITHUB_TOKEN`; the value must already exist in the imported project's protected environment. If it does not, execution fails closed rather than starting with an empty value. Hlix-owned `.mcp.json` files hydrated into the Coding Workspace are owner-readable only and excluded from Git.

## Verify before the first run

For each imported resource:

1. Re-open the source and confirm its hash/content did not change during review.
2. Use `--json` and capture the complete result in your change or approval record. Agent import returns an agent ID; skill and MCP import return the selected resource metadata instead.
3. Confirm the project ID in `.hlix/config.json` is the intended project.
4. For MCP, confirm the selected server name, transport, remote hostname or executable, arguments, and environment key names.
5. Start with the least-privileged credentials the server can use.

## Common failures

- `not_initialized`: import the project first and run from its root.
- Skill folder has no `SKILL.md`: point at the file or the correct directory.
- Agent file is not Markdown: convert the reviewed instructions to a Markdown file.
- MCP file contains multiple servers: add `--server <name>`.
- Remote MCP URL is not HTTPS: use the service's TLS endpoint.
- Stdio MCP is refused: review it, then pass `--allow-stdio`; if it still fails, replace shell syntax with a direct executable and explicit arguments.
- Required environment key is missing: add the value through the project's protected secret path, then push a new revision.

Re-importing a skill or MCP server with the same project-scoped name updates that resource. Agent import creates a new agent each time so an existing agent identity is never replaced implicitly.

## Next steps

[Import trust model](/security/trust-model/)
  [Resource import reference](/reference/cli/resources/)
  [Connect your agents](/guides/connect-agents/)
  [Official MCP server](/mcp/)