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

---
source_keys:
  - agentskills-spec
  - agentskills-best-practices
  - agentskills-optimizing-descriptions
  - agentskills-using-scripts
---

# 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.
- **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 skill", "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 skill ...`, `This is the ...`).
  `Kyberforge.DescriptionOpener` catches any opener matching `^This`.
- **Vague capabilities** ("helps with APIs" where "parses and validates OpenAPI specs" was
  available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is
  judgment.
- **Trigger-list, boundary or indirect-trigger content on a hand-invoked skill** — see Step 0 of
  `references/description-quality.md`.
- **Over 1024 characters** — the agentskills.io specification ceiling, unchanged and independent
  of the 400-character house ceiling above.

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` owns that call and tiers it by
notation — `/name` or an arrow form is an ERROR, the bare prose form a SUGGESTION unless a second
target in the same sentence resolves — and Step 1 has already filed it under `### Structure` at that
tier. Re-grading it as a description FAIL puts one target in the report twice at two tiers. What is
left to judgment here 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-discipline — `references/body-discipline.md`

Flag as FAIL if:

- A sentence answers "no" to the core test — it is padding
- The body exceeds 900 words counted body-only (`validate.sh` reports it)
- Two or more mutually exclusive flows are inlined instead of dispatched
- A Gotcha paraphrases a step in the body below it that every branch reaching the Gotcha also
  reaches
- A decision point presents a menu of options with no default
- An instruction repeats content already in the description
- A prescriptive sequence is used where flexibility is fine, or the reverse

Flag as SUGGESTION if:

- The body exceeds 600 words counted body-only but stays at or under 900
- The Gotchas section carries more than five entries
- The Gotchas section exceeds 25% of the body
- A rationale is missing from an include/exclude rule — present but unexplained
- Gotchas are correct but placed late in the body rather than near the top
- Content that only one branch reaches is inlined where a `references/` file would serve

## patterns — `references/patterns.md`

Flag as FAIL if:

- A Gotcha entry is a general tip or a reminder rather than a fact that defies a reasonable
  assumption
- An inner code fence is unescaped inside a markdown block, breaking the render
- A checklist wraps a single step
- A conditional reference gives no trigger — `Kyberforge.PaddingPhrase` reports the common form
- The agent must produce a specific format and no output template is given

Flag as SUGGESTION if:

- Gotchas are correctly formed but placed late in the body
- An output template is present but permissive where the consumer needs it exact
- A conditional reference names a trigger that is real but broader than the branch it guards

## file-structure and internal-consistency — `references/file-structure.md`

Flag as FAIL if:

- A directory outside the four permitted ones exists
- Test files sit in `scripts/`
- A non-spec file sits at the skill root
- A path that resolves outside the skill directory appears outside the two exempt locations, in
  prose rather than in a fenced example
- `tests/` exists but `tests/README.md` is missing or does not document its repo-level dependency
- `README.md` is absent, or its file table has a missing or stale row
- `SKILL.md` describes a script invocation the script does not accept

Flag as SUGGESTION if:

- An optional directory exists but holds only a placeholder README
- `README.md` is accurate but describes a file's purpose more thinly than `SKILL.md` does

## formatting and scripts — `references/formatting-and-scripts.md`

Flag as FAIL if:

- A script prompts interactively, in any form
- A script exposes no `--help`
- A destructive script has no `--dry-run`
- Data and diagnostics share a stream, so the output cannot be piped
- A relative path named in the body does not resolve
- Heading levels are inconsistent enough to break the document's structure

Flag as SUGGESTION if:

- Exit codes are meaningful but undocumented in `--help`
- A code block is untagged where a language applies
- A script is idempotent in practice but does not say so, leaving a re-run's safety unclear
- List indentation or section spacing is inconsistent without breaking the render