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 — 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

hlix skill import <SKILL.md|folder> [--name <slug>] [--json]

Arguments

• <path> (string, required): a SKILL.md file, or a folder containing one. Exactly one; zero exits missing_argument, two exits invalid_usage.

Flags

• --name <slug> (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

hlix agent import <markdown-file> [--name <name>] [--runtime <runtime>] [--profile <profile>] [--json]

Arguments

• <markdown-file> (string, required): one Markdown instruction file. The extension must be .md or .mdx.

Flags

• --name <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 <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 <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.

hlix mcp import

hlix mcp import <.mcp.json> [--server <name>] [--allow-stdio] [--json]

Arguments

• <.mcp.json> (string, required): an MCP configuration file containing an mcpServers object. At most 200,000 bytes.

Flags

• --server <name> (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 <name> 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 <name>.
• 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 <n> bytes: … — 200,000 for skills and MCP configuration, 20,000 for an agent brief.

Next steps

Import skills, agents & MCPThe walkthrough, the pre-run verification list, and how MCP secrets resolve.

Import trust modelWhat each import phase reads, executes, and makes active.

Connect your agentsThe agent matrix, and which harness actually runs a task.

CLI referenceGlobal options, exit codes, and every error code above.