holocron/plugins/kyberforge/skills/agent-audit/references/finding-criteria.md

---
source_keys:
  - context7-websites-code-claude
  - claude-code-plugins-docs
  - claude-code-subagents-docs
  - context7-github-en-copilot
  - github-custom-agents-configuration
---

# Finding Criteria

Every FAIL and SUGGESTION criterion, for every qualitative dimension, and nothing else. The
reasoning each criterion stands on, its worked examples and its house rules stay in that
dimension's rubric, which Step 3 loads only for a dimension this file puts in play.

Two rules on using it:

- A criterion that plainly applies is a finding. Write it up citing file and line.
- A criterion that might apply, or whose call the wording here does not settle, is a reason to load
  that dimension's rubric — never a reason to drop the candidate. This file decides which rubrics
  to read; it does not settle a close call on its own.

## description — `references/description-quality.md`

Flag as FAIL if:

- **Over 400 characters.** Measured on the folded YAML value, not the raw source lines.
  `validate.sh` reports the number; do not re-derive it, but do point the Fix at what to cut. Agent
  descriptions have no platform-documented ceiling of their own, so 400 is the only hard limit
  there is — do not go looking for a backstop behind it.
- **Internal mechanics appear in the description.** Any of:
  - capability enumeration or a feature list;
  - output-format detail ("Produces a compact findings report with Why and Fix per finding");
  - composition or architecture notes ("composes X rather than duplicating Y", "a cross-cutting
    shared agent", "the human-facing entry point", "replaces the old flat invocation");
  - implementation detail ("self-validates via a bundled deterministic script").

  None of it can change a routing decision and all of it is preloaded.
  `Kyberforge.CompositionNote` catches the common phrasings deterministically; the rest is
  judgment. This is the rule that deflates a description, so apply it before reaching for length.
- **The same trigger stated twice in two registers** — a verb list, then the same verbs re-quoted
  as user phrasings, usually in the same order. One register, whichever routes better.
- **Descriptive rather than imperative phrasing** (`This agent ...`, `This is the ...`).
  `Kyberforge.DescriptionOpener` catches any opener matching `^This`.
- **Vague capabilities** ("helps with agents" where "audits an agent definition pair" was
  available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is
  judgment.
- **`Use proactively` in a Copilot or vendor-neutral description.**
  `KyberforgeCopilot.ProactivePhrase` catches it. The phrase steers the Claude Code runtime and
  does nothing anywhere else, so in a `.agent.md` it is preloaded text that buys no behaviour.
- **Trigger-list, boundary or indirect-trigger content on a hand-invoked agent** — see Step 0 of
  `references/description-quality.md`.

Flag as SUGGESTION if:

- **Over 250 characters** but at or under 400. This tier is what moves the corpus average; the FAIL
  tier only stops outliers. Report it rather than treating a 399-character description as clean.
- A near-miss exclusion is present but targets a weak near-miss.
- An indirect trigger is present and warranted but could name the omitted phrasing more precisely.

**An unresolved boundary target is not graded here.** `validate.sh` resolves boundary targets for
agent files at both scopes and tiers the verdict itself — route notation (`/name`, an arrow form)
is an ERROR, the bare prose form a SUGGESTION unless a second target in the same sentence resolves.
Step 1 has already filed it under `### Structure` at that tier. Take the script's verdict rather
than re-resolving the name by hand, and do not re-grade it under description: a hand-walk over a
different universe can contradict the script, and re-grading puts one target in the report twice.
What is left to judgment is semantic and the script cannot reach it: whether a target that *does*
resolve is the right sibling to exclude, and whether a clause naming no target at all ("examine the
files manually") should have named one.

## body, delegation and comment-discipline — `references/body-and-delegation.md`

Flag as FAIL if:

- The body restates a procedure owned by a skill the agent can invoke — Fix: invoke `<skill>`
  instead
- A sentence answers "no" to the core test — it is padding
- A decision point presents a menu of options with no default
- An instruction repeats content already in the description
- Frontmatter comments are template scaffolding rather than instruction, or are HTML comments at
  plugin/APM scope
- A prescriptive sequence is used where flexibility is fine, or the reverse

Flag as SUGGESTION if:

- The body does not open with a direct role instruction
- The body specifies no error handling — nothing tells the agent what to do with malformed,
  missing or contradictory input
- The job the agent describes is unbounded, or bounded only implicitly
- A rationale is missing from a rule the agent is expected to enforce — present but unexplained
- Comments are useful but verbose enough to bury the field they annotate

**Never report an agent body as too long on a word count.** ADR-0020 gates a skill body at
600/900 words and deliberately gates an agent body at nothing, because an agent body *becomes* the
system prompt of a fresh context rather than competing with a live conversation. No number exists
to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit,
which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL
above instead.