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.

Skill

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

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

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

Override the derived slug when needed:

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:

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

The JSON response contains metadata, not secret values.

Agent

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

Agent import accepts one Markdown instruction file:

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

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

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.

MCP server

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:

hlix mcp import .mcp.json

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

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:

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 modelReview the full boundary before a newly imported resource joins production work.

Resource import referenceEvery flag, accepted value, and validation that refuses an import.

Connect your agentsWhich harness actually runs a task, and how `--runtime` fits the cascade.

Official MCP serverThe other direction — let a local coding agent operate hlix.