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

source_keys

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