Skip to content

Best Practices

Guidelines for designing effective skills and workflows.

Each skill should handle one clear task.

<!-- Good -->
---
name: check-broken-links
description: Detect broken links on the site
---
<!-- Bad -->
---
name: check-and-fix-everything
description: Check and fix the entire site
---

Skill prompts should explicitly state the expected deliverables.

Execute the following steps:
1. Scan TypeScript files in the `src/` directory for type errors
2. Output the error list as a Markdown table
3. Apply automatic fixes where possible
## Output format
| File | Line | Error | Fixed |
|------|------|-------|-------|

Workflows are DAGs (node/edge graphs) built in the HQ visual editor. See DAG Nodes for the full node reference.

A handful of nodes per workflow is ideal. Large, sprawling graphs make error recovery and reasoning difficult — split unrelated concerns into separate workflows.

Insert a Review node before destructive operations (deployments, data changes, etc.). Review nodes support a revision loop, so a rejected output can be routed back to an upstream node to be redone.

When steps have no dependency on each other, branch the graph so they run in parallel instead of forcing a straight line. Use a Fan-out node to apply the same sub-graph across every item in a list, and a Join node to gather the results.

High-frequency execution (intervals under 5 minutes) consumes resources. Consider whether such frequency is truly necessary.

  • Editor — a minion that designs workflows and keeps the context up to date. Reviews are always approved by people
  • Member — a minion that runs the steps and works on its tasks

Any member minion of the project can run a step. To have one particular minion run a step, pin it under Who runs each step on the workflow’s page in the project. See Project members and permissions.

Recording shared knowledge in project context makes it available to all assigned minions. This eliminates the need to repeat the same explanations in every skill.