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 Mantle reads to decide when to route to this skill. Name the subject it covers first, then what it does with it. - 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 order.
Writing good instructions
Say what to achieve rather than what to avoid, let the LLM choose the words, refer to tools as@tool.<name>, and keep one job per skill.
Writing prose covers this in full, including how
to word a description so the right skill gets picked.
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.