Defame1297
dac9cad912
skill-audit loaded roughly 4,268 words of rubric on every run, most of it criteria for findings a clean skill never triggers. The auditing guidance moves into finding-criteria.md, read only when a finding is actually raised, cutting a clean audit to about 999 words. The named-skill exemption is replaced with properties, so the rubric stops carrying a list that ages the moment a skill is renamed. apm-workflow's `type:` trap sat in one flow while biting several, so it is promoted to a common gate reachable from all of them; its claim to be self-contained was untrue once it started routing to apm-install. skill-author's contract had drifted from body-discipline.md and is realigned, and agent-audit's field inventory is brought in line with the same split.
6.2 KiB
source_keys
| source_keys | ||||
|---|---|---|---|---|
|
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.shreports 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.CompositionNotecatches 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.DescriptionOpenercatches any opener matching^This. -
Vague capabilities ("helps with APIs" where "parses and validates OpenAPI specs" was available).
Kyberforge.VagueWordingcatches the known filler; imprecision outside that list is judgment. -
A boundary clause naming a target that does not resolve to a real skill directory or agent file in the authoring source.
validate.shreports the unresolved name. -
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.
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.shreports 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.PaddingPhrasereports 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 buttests/README.mdis missing or does not document its repo-level dependencyREADME.mdis absent, or its file table has a missing or stale rowSKILL.mddescribes a script invocation the script does not accept
Flag as SUGGESTION if:
- An optional directory exists but holds only a placeholder README
README.mdis accurate but describes a file's purpose more thinly thanSKILL.mddoes
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