# hlix skill, agent & mcp import **These three commands activate a resource that project import only quarantines.** A project scan preserves agent instructions, skill content, and MCP configuration encrypted — but inert. Activation is separate because these files can change model behaviour, run tools, reach remote services, or execute local programs inside the Coding Workspace. ## Prerequisites - A folder bound by [`hlix import`](/reference/cli/import/) — all three exit `not_initialized` otherwise - You have read the complete file you are importing **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. ## `hlix skill import` ```bash hlix skill import [--name ] [--json] ``` ### Arguments - **``** (`string`, **required**): a `SKILL.md` file, or a folder containing one. Exactly one; zero exits `missing_argument`, two exits `invalid_usage`. ### Flags - **`--name `** (`string`, default derived from the path): the project-scoped identifier. Must be a lowercase kebab-case slug matching `^[a-z0-9]+(-[a-z0-9]+)*$`. Derivation is the folder name for a directory, the *parent* folder's name for a file called `SKILL.md`, and otherwise the file's base name. - **`--json`** (`boolean`, default `false`): return the stored skill metadata. ### Conflicts and validation - A symlink at the given path is refused outright. - The resolved file must be a regular file of at most 200,000 bytes. - Re-importing with the same project-scoped name **updates** that skill. ## `hlix agent import` ```bash hlix agent import [--name ] [--runtime ] [--profile ] [--json] ``` ### Arguments - **``** (`string`, **required**): one Markdown instruction file. The extension must be `.md` or `.mdx`. ### Flags - **`--name `** (`string`, default the file's base name with `-` and `_` turned into spaces): the agent's display name. Unlike a skill slug, this is free text. - **`--runtime `** (`claude-code` | `codex` | `cursor-agent` | `hlix`, default `hlix`): which coding agent the instructions target. Any other value is refused with the accepted list. This flag names the runtime an *agent record* targets; it is separate from the task-level harness cascade, whose default is also `hlix`. - **`--profile `** (`builder` | `desktop` | `e2e`, default `builder`): the sandbox profile the agent runs under. `desktop` and `e2e` are sandbox-driver profiles, so they require `--runtime claude-code`; combining either with `hlix` is refused rather than accepted and ignored. - **`--json`** (`boolean`, default `false`): return the created agent, including its ID. ### Conflicts and validation - The file must be a regular file of at most 20,000 bytes. - Agent import **creates a new agent each time**, so an existing agent identity is never replaced implicitly. Skill and MCP imports update in place; this one does not. - `--runtime` here names the coder for an agent record. Which harness actually runs a given task is decided by a wider cascade — see [Connect your agents](/guides/connect-agents/). ## `hlix mcp import` ```bash hlix mcp import <.mcp.json> [--server ] [--allow-stdio] [--json] ``` ### Arguments - **`<.mcp.json>`** (`string`, **required**): an MCP configuration file containing an `mcpServers` object. At most 200,000 bytes. ### Flags - **`--server `** (`string`, default the only server): which server to activate. **Required when the file defines more than one** — a file with several servers and no `--server` is refused rather than defaulting to the first. - **`--allow-stdio`** (`boolean`, default `false`): permit a stdio server. Required, because a stdio server executes a local program inside the Coding Workspace. It is not permission to run an arbitrary command string through a shell — the command must be a validated direct executable. - **`--json`** (`boolean`, default `false`): return the stored server definition, including the environment **key names** but no values. ### Conflicts and validation - The transport is taken from `type` when it is `http` or `sse`, otherwise inferred: a `command` means stdio, a `url` means http. Neither exits with ``MCP server has no supported transport.`` - A stdio server without `--allow-stdio` is refused: `Stdio MCP servers execute a local command in the cloud; repeat with --allow-stdio.` - Remote URLs must use public HTTPS. Embedded credentials, query strings, fragments, and loopback, private, link-local, or cloud-metadata hosts are refused. - Every header value must be a string, and must be exactly `${KEY}` or one approved scheme followed by it — `Bearer`, `Basic`, or `Token`. Extra prefix or suffix text is refused, and a headers object with no `${KEY}` placeholder at all is refused as a literal credential. - Only environment **key names** are sent. The values must already exist in the project's encrypted secrets; a missing one fails closed at task time rather than starting with an empty value. - Malformed JSON exits with `MCP config is not valid JSON.`; an empty `mcpServers` exits with `MCP config contains no servers.` ## If a resource import fails - `not_initialized` — ``This folder is not bound to an Hlix project. Run `hlix import .` first.`` The **nearest** binding is used, and only that one; an initialized-but-unimported folder does not fall through to an imported ancestor. - `Skill name must be a lowercase kebab-case slug.` — pass `--name` explicitly. - `Agent imports must be Markdown files.` — convert the reviewed instructions to `.md`. - `MCP config contains multiple servers; select one with --server .` - `MCP remote headers must use ${KEY} placeholders; literal credentials are refused.` - `Refusing to import a symlink: …` or `Refusing to import a non-regular file: …` - `Import file exceeds bytes: …` — 200,000 for skills and MCP configuration, 20,000 for an agent brief. ## Next steps [Import skills, agents & MCP](/cli/resources/) [Import trust model](/security/trust-model/) [Connect your agents](/guides/connect-agents/) [CLI reference](/reference/cli/)