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

3. End with execution-report

Place the execution-report skill at the end of workflows to report results back to HQ.

{
  "pipeline_skill_names": ["analyze", "fix", "execution-report"]
}

Workflow design principles

Keep pipelines short

3–5 steps is ideal. Long pipelines make error recovery difficult.

Place review points strategically

Insert review steps before destructive operations (deployments, data changes, etc.).

{
  "pipeline_steps": [
    { "assigned_role": "engineer", "requires_review": false },
    { "assigned_role": "engineer", "requires_review": true },
    { "assigned_role": "engineer", "requires_review": false }
  ]
}

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, pipeline 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.