Best Practices

1. Semantics in Spec, style in Adapter

Never put Markdown headings, XML tags, or "let's think step by step" in your Spec. Those are "how to say it" — the adapter's job. The Spec only says "what to do".

2. Reasoning models ≠ normal models

For o1 / R1 / QwQ, the shorter the prompt the better — just state the problem, the constraints, and the output format. The adapter auto-strips CoT prompts; you only need to get the Spec right.

3. Layered few-shot

The examples[].reasoning field is rendered only for non-reasoning models; reasoning models auto-filter it. One Spec works great for both classes of model.

4. Put long docs into knowledge

Kimi / Gemini inline knowledge directly. The Claude adapter emits a suggested SKILL.md for progressive disclosure. Do NOT chunk your knowledge manually — let each adapter decide.

5. Canonical tool schema

Spec only needs name / description / parameters. The adapter converts to Anthropic tool_use / OpenAI function / Google function_declarations as needed.

6. Build a cross-model eval loop

Run the same Spec across all models as regression tests. Pick per-task winners based on success rate + output stability + token cost — don't just trust vendor claims.