Best Practices

Guidelines for designing effective skills and workflows.

Skill design principles

1. Single responsibility

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
---

2. Clear goals

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 |
|------|------|-------|-------|

Workflow design principles

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

Keep graphs focused

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

Place review nodes strategically

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.

Parallelize independent work

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.

Be conservative with cron frequency

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

Project organization tips

Role separation

• PM — Workflow design, context management, review approval
• Engineer — Skill implementation, workflow execution

Leverage context

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.