Skill author

Treat every loaded line as a cost. A skill earns that cost by changing an ordinary coding agent's decision.

Start with the trigger

• Give the skill one clear job and a short name that matches its directory.
• Write a brief description that says what the skill helps accomplish and distinguishes it from its closest neighbors.
• Do not turn the description into a keyword inventory. Test realistic user requests when the boundary is uncertain.
• If an existing skill already owns the decision, deepen it instead of adding another trigger surface.

Write the entrypoint

• Frontmatter contains only name and description.
• Organize SKILL.md around one useful mental model, not a universal template.
• Prefer short, natural bullets that a human can scan without decoding process language.
• Assume the agent can already code, search a repository, and read ordinary documentation. Keep only constraints, choices, and failure patterns that materially improve its work.
• Avoid fixed sequences unless order protects correctness, safety, money, or external state.
• Mention another skill only where evidence crosses that skill's boundary.

Put depth behind links

• Keep the common path in SKILL.md. Put conditional commands, failure diagnosis, tuning, platform compatibility, schemas, and substantial examples in focused supporting files.
• Link each supporting file at the point where it becomes useful and say when to read it. Do not load every reference by default.
• Reuse a focused existing file before creating another layer of navigation.
• Preserve exact Robium-observed values with their measured conditions. They are evidence, not universal defaults.
• Use current official documentation for volatile APIs, flags, packages, and configuration. Do not copy a manual into the skill.
• Keep executable helpers only when deterministic reuse justifies maintaining code; keep examples only when they show something prose cannot.

Test usefulness

• Read QUALITY.md for the review bar and mechanical checks.
• Run uv run skills/skill-author/scripts/validate_skills.py once after a coherent batch of skill changes, not after every edit. It checks the lightweight contract, not writing quality.
• For description, routing, or behavioral changes, review one common request, one likely failure, and one neighboring request that should route elsewhere. A typo or source-link refresh needs only the relevant mechanical check.
• Start with manual scenario review. Run bounded live-agent evals only for unresolved behavioral uncertainty, meaningful regression evidence, or an explicit request; do not rerun every model or prompt after each prose edit.
• Prefer observable behavior checks over tests that assert headings or exact prose. Keep evals.yaml only when a real routing or task regression is worth preserving.

Done

• The entrypoint is small enough to load routinely.
• Optional detail is discoverable without being injected into every task.
• Every strong claim is either stable, sourced upstream, or tied to observed conditions.
• There is no version field, changelog, README, or format-only section.