hlix skill, agent & mcp import

Use these commands to add or update an individual project resource. Project import already preserves skill files and recognized MCP configurations; it carries MCP enabled state across and reports connections that need attention. Agent instructions such as AGENTS.md remain ordinary project files.

Resources can change agent behavior, reach remote services, or start programs in a Cloud Machine. Review the source before importing. See Import skills, agents & MCP servers for the walkthrough.

Prerequisites

• A folder bound to a project, or an explicit --project <id>

Pass --project <id> to any command below to select a project explicitly. Otherwise the nearest folder binding is used; an unbound folder exits not_initialized.

hlix skill import

hlix skill import <SKILL.md|folder> [--name <slug>] [--project <id>] [--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

• Use a regular file or directory rather than a symbolic link.
• 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>] [--duty <duty>] [--project <id>] [--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 | opencode | goose | qwen-code | pi | hlix, no default): the coder this agent always runs on. Leave it out and the agent follows your project and Workspace AI settings.
• --duty <duty> (executor | intake, default executor): what the agent is for. executor runs tasks. intake makes it the agent that triages requests for the project — it judges every inbound request before it becomes a cycle — and carries its brief into triage, pinned to its model.
• --json (boolean, default false): return the created agent, including its ID and the duty that landed.

Conflicts and validation

• The file must be a regular file of at most 20,000 bytes.
• Agent import creates a new agent. To update an existing agent, edit that agent’s record.
• An agent’s --runtime outranks your project and Workspace settings but not a coder pinned on the run itself — see Connect your agents.
• A duplicate name returns 409 (conflict): An agent named "<name>" already exists in this workspace. A second agent that triages for the same scope also returns conflict: This project already has an intake agent — edit or fork that one. A project’s own agent for triage overrides the Workspace default for that project.

hlix mcp import

hlix mcp import <.mcp.json> [--server <name>] [--allow-stdio] [--project <id>] [--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 — select one server by name when the file contains several.
• --allow-stdio (boolean, default false): permit a stdio server. Required for a stdio server, which runs a supported executable and its arguments inside the Cloud Machine.
• --json (boolean, default false): return the stored server definition, including the environment key names but no values.

Conflicts and validation

• Set type to http or sse for a remote server. A definition with command uses stdio; one with url defaults to HTTP.
• For a stdio server, pass --allow-stdio. The CLI explains the requirement as: 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. Use the placeholder as the complete value, with an optional authentication scheme.
• Only environment key names are sent. Values must already exist in the project’s encrypted secrets; missing keys are rejected during import. Removing a required secret later causes the run to fail before the server starts.
• 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. Run from the imported project folder or pass --project <id>.
• 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 & MCP

Add a skill, agent brief or MCP server to a project.

Import security

What each import step reads, runs, and makes active.

Connect your agents

The coder matrix, and which coder runs a task.

CLI reference

Global options, exit codes, and every error code above.