Review Agent Primitives

Review Agent Primitives

Evaluate three artifacts that steer an agent's behavior — tool descriptions, agent/system prompts, and skills (SKILL.md) — against a single, source-backed rubric. Reviews all three with one shared foundation so overlap, contradictions, and duplicated context are caught in one pass.

When to use

• Reviewing / auditing / scoring a tool description, agent or system prompt, or a SKILL.md.
• Diagnosing behavior: a tool is called with wrong params, not called when it should be, or the agent makes redundant tool calls / burns turns guessing.
• Deciding placement: given a piece of behavior or context, which primitive it belongs in (system prompt vs tool vs skill), and flagging content that currently sits in the wrong one.
• Pre-ship polish of any of the three artifacts.

When NOT to use

• Writing the artifact from scratch (do that first, then review).
• Reviewing application/business logic — that is a normal code review.

Shared foundation (applies to all three)

These five principles come from the "context engineering" line of thinking and cut across every artifact. Score them once, here, before diving into the type-specific rubric — do not repeat them per section.

1. Minimal high-signal tokens. Find the smallest set of tokens that fully specifies the behavior. minimal ≠ short: include everything the reader needs, nothing it doesn't. Cut restated rules, filler, and dead caveats.
2. Right altitude. Avoid the two failure modes: (a) brittle hardcoded if-else logic that tries to script every case, and (b) vague high-level guidance that assumes shared context the model doesn't have. Aim for specific-but-flexible heuristics.
3. Zero ambiguity → zero guessing. Every implicit assumption (formats, niche terms, resource relationships, boundaries) must be explicit. Ambiguity is what causes the agent to guess wrong and spend extra tool-call turns. Name things unambiguously (user_id, not user).
4. Self-consistency. The artifact must not contradict itself, the system prompt, or a sibling tool/skill. If a human expert can't say which tool/instruction applies in a situation, the agent can't either.
5. Fail-safe by design (poka-yoke). Prefer constraints, examples, and actionable error text that make mistakes hard to make, over prose that merely warns against them.
6. Discoverable & load-on-demand. The name/description (for a skill) and the name/description (for tool search) are the discovery surface — keyword-rich and distinctive. For large tool/skill libraries, defer loading and keep only the few highest-use items resident, so context isn't spent on definitions the task doesn't need.

Review workflow

1. Identify the artifact type. Tool description → prompt → skill. If mixed (e.g. a skill that also defines tools, or a prompt with an embedded tool spec), review each part with its own rubric.
2. Score the shared foundation (6 principles above) → Pass / Warn / Fail each.
3. Load the matching reference rubric and score its items:

   Artifact	Reference
   Tool description / spec	references/tool-description.md
   Agent / system prompt	references/agent-prompt.md
   Skill (SKILL.md)	references/skill-quality.md

4. When all three exist together, additionally check cross-artifact issues: duplicated context across prompt and tool descriptions, procedures restated in the system prompt that belong in a skill, tools the prompt references but doesn't scope, and name/description keywords that collide between skills or similar tools. Also check same-type fan-out: one fact restated across files of the same type — a tool description and its own parameter/field-schema description strings, a SKILL.md and its sibling reference files, or two peer skills. The cross-artifact-type lens misses these because both copies are the same type; grep the distinctive phrase to find every copy, then flag lockstep-sync risk (see the fan-out signal under Placement mode).
5. Report using the output format below.