Import skills, agents & MCP servers

Add or update an individual skill, agent brief or MCP server in a project.

Use these commands to add or update an individual skill, agent, or MCP server in a project. Agent instructions such as AGENTS.md and CLAUDE.md remain ordinary project files.

Project import preserves skill files and recognized MCP connections. Use the commands below to activate a selected skill, create an agent brief or update a server connection. Check connections and authorization under the project’s Integrations page.

Prerequisites

Run from a folder bound to a project, or pass --project <id>
Confirm that referenced secret keys belong to this project and workspace
For MCP, store the required credential values as project secrets

Activate a resource

Choose the command for the resource you want to add. These commands write to the selected project; review the source before running them.

A skill is reusable instructions in a SKILL.md file.

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.

Add --json to the import command when you need a structured metadata response.

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"

By default an imported agent follows your project and Workspace AI settings. Pin its coder explicitly when it should always run on one:

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

Supported runtime values are claude-code, codex, opencode, goose, qwen-code, pi, and hlix.

An imported agent runs tasks unless you say otherwise. Pass --duty intake to make it the project’s request judge instead — the agent that triages every inbound request before it becomes a cycle:

hlix agent import INTAKE.md \
  --name "Acme front desk" \
  --duty intake

A project has exactly one agent that triages requests. A second --duty intake import into the same project exits conflict rather than creating a duplicate.

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

An MCP server supplies tools agents can call. A remote server reaches another service; a stdio server starts a program in the Cloud Machine.

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

Use a public HTTPS endpoint. Keep credentials in project secrets and reference them through headers; the endpoint URL must have no credentials, query string or fragment.

Stdio servers

Stdio MCP starts an executable inside the Cloud Machine, so it requires an extra approval flag:

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

Use one of the supported executables directly: bunx, deno, node, npx, python, python3 or uvx, with its arguments in the server definition.

MCP secrets

Reference project secrets by key name. For example, use Authorization: Bearer ${TOKEN} and declare TOKEN in envKeys. A sensitive stdio argument uses a complete ${KEY} placeholder.

Add every referenced key to the project’s secrets before importing the server. Hlix resolves the values for each run and keeps the generated credential configuration out of source commits.

Check the imported resource

Use --json to inspect the returned resource metadata and hlix status to confirm the folder’s project binding. Check MCP authorization and required secret keys before using the server in a run.

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.
For stdio MCP, pass --allow-stdio and use a direct executable with explicit arguments.
Required environment key is missing: add the value through the project’s protected secret path, then push the updated files.

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.