--- source_keys: - agentskills-home - agentskills-spec - agentskills-best-practices - agentskills-optimizing-descriptions - agentskills-using-scripts --- # Skill Flow Steps 1 to 3 for a skill directory — the target Step 0 matched as a directory containing `SKILL.md`, or as a `SKILL.md` file, in which case `` below is its parent directory. Work them in order, then return to `SKILL.md` Step 4 to report. ## Gotchas - A skill takes two independent length families, and it can sit inside one while failing the other — so report them separately. The 500-line / 2,770-word pair counts the **whole file** for spec conformance. The 250/400-character and 600/900-word pair is the house context budget, and its word half counts the **body only**. ## Step 1 — Deterministic checks Resolve all three paths against this skill's own directory so they work from a repo checkout and an installed plugin cache alike. Run exactly: ```bash bash scripts/validate.sh bash scripts/validate-provenance.sh bash scripts/vale-wrap.sh /SKILL.md ``` `validate.sh` findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both, at the tier the script assigned. Report each once; never re-grade one under another dimension. Unresolved boundary targets are where this bites, because their tier turns on notation. It exits **0** when no check failed, **1** on real findings, and **2** when it never ran — an unshaped or missing target, a missing script library, or a missing dependency, reason on stderr. Report an exit 2 as `### Structure` unverified, quoting that reason, never as a failure or a pass. Read `references/skill-validation-scripts.md` when any of the three cannot run or exits non-zero for a reason other than findings, **and whenever `validate-provenance.sh` exits 0 having printed anything**. Ordinary content FAILs are the expected outcome here and need no fallback. `validate-provenance.sh` reports through exit code **and** output; neither alone is the verdict. **0, silent** is a genuine pass. **0 with output** is INFO-only findings — still a `### Provenance` dimension; `references/skill-validation-scripts.md` says what each obliges — for a check-9 INFO, reading rather than relaying. **1** is FAILs plus any INFOs; it emits Why and Fix itself — surface those verbatim. **2** means it never ran — an unshaped or missing target, a missing script library, or a missing dependency, reason on stderr, often no stdout — so report `### Provenance` unverified and quote that reason. Never grade an exit 2, or an exit 0 that printed, as a clean pass. `vale-wrap.sh` applies the bundled `Kyberforge` style as a prefilter. Pass no `--config`; the wrapper locates its own. Every rule is graded `error`, so every alert is a FAIL. Report each one citing its rule ID, filed under the dimension it belongs to, and do not re-derive it by judgment: | Rule | Dimension | |---|---| | `Kyberforge.DescriptionOpener`, `Kyberforge.CompositionNote`, `Kyberforge.VagueWording` | description | | `Kyberforge.SentenceOpenerThereIs` | body-discipline | | `Kyberforge.PaddingPhrase` | patterns | ## Step 2 — Read the whole skill Read `SKILL.md` and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture. ## Step 3 — Qualitative audit Read `references/skill-finding-criteria.md` first — every dimension's FAIL and SUGGESTION criteria. Load the rubric below only for a dimension the criteria put in play: one carrying a candidate finding, or one where the criterion alone does not settle the call. | Dimension | Rubric | |---|---| | description | `references/skill-description-quality.md` | | body-discipline | `references/skill-body-discipline.md` | | patterns | `references/skill-patterns.md` | | file-structure, internal-consistency | `references/skill-file-structure.md` | | formatting, scripts | `references/skill-formatting-and-scripts.md` | Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget. Cite file and line number for every finding. Then return to `SKILL.md` Step 4.