Assume the agent already understands common concepts; only include context that changes decisions or prevents mistakes. Reduces token load after a skill is selected and keeps instructions focused on what is unique to the workflow or project. Write the frontmatter description in third person, and include both what the skill does and when to use it. The description is injected into the system prompt and is used for skill selection; point-of-view drift reduces match quality. Keep SKILL.md as an entrypoint: a concise overview + clear navigation to any linked reference files. Roo Code does not automatically load linked files; SKILL.md must make it obvious which file to read next (and why). Choose an appropriate degree of freedom: use strict, step-by-step instructions for fragile workflows; use heuristics when multiple approaches are valid. Overly rigid skills break in novel contexts; overly loose skills skip validation in high-stakes workflows. Write descriptions for retrieval: include concrete keywords, tools, file types, and user phrasing triggers. Improves selection accuracy during skill matching. Make the description actionable: describe what the skill DOES and when to use it. Vague descriptions reduce match quality and increase false positives/negatives. Start SKILL.md with "When to use" and "When NOT to use". Prevents accidental activation and reduces false positives. Prefer short, numbered steps with explicit inputs/outputs. Agents follow procedural instructions more reliably than prose. Use progressive disclosure: keep SKILL.md concise; move deep reference into references/. Minimizes context usage while preserving detail on demand. Prefer a single recommended default approach with an explicit escape hatch (only add multiple alternatives when necessary). Too many options reduces reliability and increases variance in execution. When referencing files, use forward slashes in paths (even on Windows) and keep references one level deep from SKILL.md. Forward slashes are cross-platform, and shallow references reduce accidental partial/irrelevant reads. For longer reference files, include a short table of contents near the top to make selective reading easier. Helps the agent jump to the correct section without reading the entire file. Heuristic size rule: keep SKILL.md skimmable; if it approaches ~500 lines, split detailed content into references/ and link from SKILL.md. Roo Code does not enforce a SKILL.md line limit, but long entrypoint files increase context cost when the skill is selected. I want a skill for making API docs Generate OpenAPI documentation from TypeScript/JavaScript source using JSDoc comments Keep skill names stable; treat renames as breaking changes. Prefer one-level file references from SKILL.md (e.g., references/REFERENCE.md, scripts/run.sh). Make intent explicit for scripts: state whether the agent should execute the script or read it as reference. Most scripts should be executed for deterministic behavior; reading is only needed when understanding the logic matters. Use the optional compatibility field only when it meaningfully constrains runtime requirements.