GUIDE / SCORING

What an instruction-file score can tell you

A score can organize a review. It cannot substitute for testing an agent on representative work.

What deterministic checks measure

Heuristic rules can detect headings, command examples, verification language, documentation references and safety boundaries. These are useful signals, but their presence does not establish that the instructions are correct.

Where false positives appear

A file might mention “test” without supplying a runnable command. It might mention “secrets” while instructing an agent to expose them. Keyword detection alone cannot resolve such meaning.

How to interpret a score

Compare the reported dimensions and recommendations with the actual repository. Treat changes in score as changes in the rubric's detected signals, not necessarily improvements in agent output.

What real validation requires

Build a task set with expected outcomes. Run it under controlled conditions, review generated changes and track regressions. Record the instruction-file version and evaluation method alongside the result.

Our current limitation

OptimizeAgentsMD's free v0.1 scorer uses browser-local, deterministic checks. It has not been validated as a predictor of agent performance.