Skip to content

vt-c-skill-structural-screen

Score every deployed skill against the mechanically-checkable subset of Anthropic's skill-authoring checklist (description sharpness, SKILL.md size, one-level references, forward-slash paths, no time-sensitive dates) plus a bucket-level Testing signal. Use this when auditing authoring-quality debt across the skill library, finding oversized or vague skills to trim, or after adding/editing skills. Advisory only — never emits a keep/retest/retire verdict.

Plugin: core-standards
Category: Other
Command: /vt-c-skill-structural-screen

vt-c-skill-structural-screen — Structural-Quality Screen for Skills

An advisory static-analysis screen (SPEC-162). It scores the toolkit's deployed skills on the authoring/structural axis — the mechanically-checkable subset of Anthropic's "Checklist for effective Skills" — and is strictly separate from SPEC-156's empirical keep/retest/retire value axis. A skill can be well-authored yet empirically useless, or valuable yet structurally poor; the two signals are reported independently and never substitute for one another.

When to Use

  • Auditing authoring-quality debt across the ~127-skill library.
  • Finding which skills are bloated (oversized SKILL.md), vaguely described, or use nested references.
  • After adding or editing skills, to catch structural regressions before review.

Prerequisites

  • SPEC-156 merged — the screen consumes its inventory docs/skill-audit-inventory.json (schema_version 1). If that file is absent the screen reports it and exits without partial output.
  • Python 3 (stdlib only — no third-party dependencies).

Execution

Run from the repository root:

python3 plugins/core-standards/skills/skill-structural-screen/scripts/structural-screen.py

Options:

  • --inventory PATH — override the SPEC-156 inventory location (default docs/skill-audit-inventory.json).
  • --skills-root PATH — override the skills directory (default plugins/core-standards/skills).
  • --emit-proposal [--proposal-threshold N] [--proposal-dir DIR] — additionally write advisory intake proposals for skills with ≥ N failing checks (default N=2) into intake/pending/from-research/. Nothing else is edited.

The script prints JSON to stdout: per-skill pass/fail per check with locations, and a library-wide summary of the most common failing checks ranked by frequency, plus the testing_debt_count (SPEC-156 not-evaluable skills — the ≥3-eval shortfall proxy).

Checks (mechanical, FR-2)

  • description — non-empty, third-person, not a vague stem (helps with X); a short description must carry a when/trigger clause. Long specific descriptions pass without an explicit trigger word.
  • size — SKILL.md body ≤ 500 lines.
  • references — file references from SKILL.md are one level deep (no nested see A → see B).
  • dates — no time-sensitive absolute date in a live instruction (dates inside an anchored old-patterns/deprecated/historical heading block are exempt).
  • paths — forward-slash paths only (no backslash separators).

Testing signal (FR-3)

Sourced from SPEC-156's evaluability bucket, reported at bucket granularity: not-evaluable skills are surfaced as authoring debt (no eval suite) and linked to SPEC-156's list. The screen does NOT compute per-skill evaluation counts — the ≥3-eval precision is unavailable from the inventory.

Manual-review only (FR-4, out of scope for the automated screen)

Consistent terminology, concrete (not abstract) examples, feedback-loop quality, and progressive-disclosure appropriateness require human judgement and are NOT auto-checked — the report lists them so a reviewer knows what the screen does not cover.

Edge Cases

  • Inventory absent — prints inventory unavailable — SPEC-156 must be merged first and exits 0 with no per-skill output (hard dependency).
  • Deprecated redirect stubs — descriptions beginning with [DEPRECATED] are exempt from the description check (they intentionally redirect and lack a when-clause by design).
  • Skill legitimately > 500 lines but well-organized — still flagged by the mechanical line count; the summary marks it a split candidate. A human decides via intake.

Success Criteria

  • Every deployed skill (count derived from SPEC-156's inventory, not hard-coded) carries a per-check structural result with offending locations.
  • The library-wide summary ranks the most common failing checks.
  • No keep/retest/retire verdict is emitted and SPEC-156's decision layer is never fed (advisory).
  • Two consecutive runs over the same skill set produce identical output (no model calls).

Anti-patterns

  • Never auto-edit, split, or delete a skill based on this screen — reason: it is advisory; a human decides via the intake pipeline (FR-6).
  • Never treat a structural fail as an empirical verdict — reason: authoring quality and value are orthogonal axes (US-3).