skill.md, and the LLM reads them to run the conversation. This is where
every skill starts. No code, no config, just a clear description of the job.
Where instructions live
Theskill.md file has two parts: YAML frontmatter for metadata, and a
markdown body for the instructions.
skills/card_replace/skill.md
- The
descriptionis what Maestro reads to decide when to route to this skill. Write it as a clear summary of what the skill does. - The body is soft guidance the LLM interprets. Write it the way you’d brief a new teammate: what to do, what to ask, and in what rough order.
Writing good instructions
- Be specific about outcomes, not phrasing. Say what to accomplish and let the LLM choose the words, unless you need exact wording, which belongs in responses.
- Name tools plainly when the LLM should take an action: “Ask for their
account number, then call
check_balance.” The tool is already in the model’s schema; naming it in prose is guidance, not a reference the compiler resolves. - Keep each skill focused. One job per skill. If the body reads like two different tasks, split it into two skills.
- Don’t restate what a tool returns. The LLM sees the tool result directly.
Instructions are soft until you add control
At this stage everything is guidance. The LLM can call a tool early, skip a step, or take the wrong branch. That’s fine for most of a skill. Where a mistake is expensive, layer on framework-enforced guarantees without touching the body:- Scoped instructions: show only the
relevant branch with
if:markers. - Tool constraints: block a tool until a value exists.
- Ordered blocks: enforce a strict sequence.
Write one
if: paragraph per case, each spelling out its own condition. For
exclusive either/or branching, use an ordered block’s next: branches.Reference
For the full body syntax, coveringif: markers, @block and @skill
references, and ordered-block fences, see the
skill.md reference.