SaaS • Docs • Discord

Helix agent skills

Agent skills for Helix — a private agent fleet with spec-driven coding. They teach a coding agent how to drive a Helix control plane from the helix CLI: manage the Kanban board, dispatch and steer spec tasks, upload files and build knowledge bases, configure agents, and install or debug a deployment.

Install

npx skills add helixml/skills

Or copy the directories you want out of skills/ into your agent's skills directory (.claude/skills/, .agents/skills/, …).

Skills

Skill	Use it for
helix-session	Running inside Helix? Start here: what is already in your environment, and how to get a secret.
helix-cli	Install and authenticate the CLI, the command map, orgs/teams/members/secrets/providers, and the helix api escape hatch.
helix-board	Projects and the Kanban board: project YAML, listing the board, creating and moving cards, labels, assignees, WIP limits, approvals, archiving.
helix-spec-tasks	Running work: start a task, watch and chat with its agent, exec in its sandbox, screenshot and stream the desktop, drive standalone sandboxes.
helix-files	Getting files into Helix: filestore uploads, knowledge/RAG indexing and search, spec-task attachments, files in and out of containers.
helix-artifacts	Build and publish project-scoped static pages, compiled SPAs, PDFs, and images, then update, verify, list, or delete them.
helix-agents	Agent YAML (system prompts, OpenAPI tools, MCP servers, tests), chatting with agents, models and provider endpoints.
helix-bot-builder	helix-org bots end to end: prompts that work as runbooks, harness/model choice, bot instances and the app-key gateway for customer-facing support bots, tested page libraries as repo skills, troubleshooting, and graded eval suites (helix org bots, helix org instances, helix org eval, helix session).
helix-deploy	Install and debug: control plane on Compose or Helm, the Hydra sandbox runner that actually runs agent desktops, runtime config, health checks, logs, troubleshooting.
helix-e2e	Prove a deployment works end to end: org → project → agent → task → chat → approve → PR → cleanup.

Quick start

The spectask board|get|create|update|move|… commands used below are newer than the latest release (2.12.3) — see Version note. On a released binary, use helix project tasks <project-id> and the helix api forms each skill gives inline.

export HELIX_URL=https://your-helix.example.com
export HELIX_API_KEY=hl-...            # Account → API Keys in the web UI
export HELIX_ORG=your-org              # optional default

helix organization list                            # check auth
helix project list                                 # find a project
helix spectask board --project prj_01xxx           # read the board
helix spectask start --project prj_01xxx --agent app_01yyy \
  -n "Add dark mode" --prompt "Users want a dark theme"

Version note

The board and task-lifecycle commands (helix spectask board|get|create|update|move|label| attach|attachments|approve|archive|delete|progress, and addressing a task by spt_… in send/interact) come from helixml/helix#3033, which is merged to main and ships in the first release after 2.12.3. Every skill that uses them also gives the helix api equivalent, so the guidance holds on older binaries too.

Check with helix spectask --help. On a binary that predates them the failure is misleading — cobra treats board as a stray positional and reports the flag instead:

$ helix spectask board --project prj_01xxx
Error: unknown flag: --project

That means "your binary is too old", not "wrong flag".

Contributing

Each skill is one directory under skills/ containing a SKILL.md, plus an optional reference/ directory:

skills/helix-something/
  SKILL.md              # router: concept, the common path, a table of pointers
  reference/
    some-domain.md      # loaded only when that domain is the task

---
name: helix-something
description: Use when <specific triggering conditions and symptoms>.
---

These skills are loaded on every Helix run, so context cost is a feature requirement, not a nicety. Two rules follow:

• description states when to reach for the skill, not what it contains. An inventory of everything a skill covers widens the trigger surface until the skill fires on every run, and invites agents to answer from the description instead of reading the body.
• SKILL.md stays a router. Keep it well under 500 lines. Anything a task needs only sometimes belongs in reference/, linked exactly one level deep so the file is read whole. Give reference files over 100 lines a ## Contents list.

Keep commands verified against a real control plane — check helix <command> --help before documenting a flag, and mark anything that isn't in a released binary yet. Time-sensitive notes go in a collapsed ## Old patterns block at the end of the file, not inline.