Rules

Rule codes are stable: never renumbered, never recycled. Codes and kebab-case aliases are interchangeable in config and CLI flags.

Severity tiers: error = skills-ref 0.1.0 strict parity, warning = beyond-parity + client-guide lenient tier, info = advisory, never gates CI.

Code	Alias	Severity	Lenient	Fixable	Summary
SC001	skill-md-missing	error	error	-	Skill directory must contain SKILL.md
SC002	frontmatter-missing	error	error	-	SKILL.md must start with YAML frontmatter
SC003	frontmatter-unclosed	error	error	-	Frontmatter must be closed with ---
SC004	frontmatter-invalid-yaml	error	error	-	Frontmatter must be valid strict YAML
SC005	frontmatter-not-mapping	error	error	-	Frontmatter must be a YAML mapping
SC006	name-missing	error	error	-	name is required
SC007	description-missing	error	error	-	description is required
SC008	name-empty	error	error	-	name must be a non-empty string
SC009	name-too-long	error	warning	-	name must be at most 64 characters
SC010	name-not-lowercase	error	error	safe	name must be lowercase
SC011	name-edge-hyphen	error	error	safe	name cannot start or end with a hyphen
SC012	name-consecutive-hyphens	error	error	safe	name cannot contain consecutive hyphens
SC013	name-invalid-chars	error	error	-	name may only contain letters, digits, and hyphens
SC014	name-dir-mismatch	error	warning	-	directory name must match skill name
SC015	description-empty	error	error	-	description must be a non-empty string
SC016	description-too-long	error	error	-	description must be at most 1024 characters
SC017	compatibility-invalid	error	error	-	compatibility must be a string of at most 500 characters
SC018	unknown-frontmatter-field	error	warning	-	frontmatter field is not in the spec or a known extension
SC019	metadata-not-string-map	warning	warning	-	metadata should be a string-to-string map
SC020	skill-md-lowercase-filename	warning	warning	safe	skill.md found; canonical filename is SKILL.md
SC021	unquoted-colon-description	warning	warning	safe	unquoted colon in name/description value breaks lenient parsers
SC101	broken-relative-reference	warning	warning	-	referenced bundled file does not exist
SC102	absolute-path-reference	warning	warning	-	body references an absolute path
SC103	deep-reference-chain	info	info	-	bundled reference chains deeper than one level
SC104	unreferenced-bundled-file	info	info	-	bundled file never referenced from SKILL.md
SC105	duplicate-skill-name	warning	warning	-	two skills resolve to the same name
SC106	non-utf8-encoding	warning	warning	-	SKILL.md is not valid UTF-8
SC107	hidden-unicode	warning	warning	unsafe	zero-width or bidi control characters present
SC108	legacy-basedir-placeholder	warning	warning	safe	deprecated {baseDir} placeholder
SC201	body-empty	warning	warning	-	SKILL.md body is empty
SC202	body-too-many-lines	warning	warning	-	body exceeds 500 lines
SC203	body-too-many-tokens	warning	warning	-	body exceeds ~5000 tokens
SC301	extension-field	warning	warning	-	client extension field (fails strict skills-ref validation)
SC302	extension-invalid-value	warning	warning	-	extension field has an invalid value
SC401	evals-invalid	error	error	-	evals/evals.json fails schema or semantic validation
SC402	evals-advisory	warning	warning	-	evals/evals.json advisory (coverage gaps)

Profiles

• --profile strict (default): full skills-ref parity. SC009 (name-too-long), SC014 (name-dir-mismatch), and SC018 (unknown-frontmatter-field) are errors.
• --profile lenient: client-implementation-guide behavior -- those three downgrade to warnings (clients warn and load anyway). Missing description and broken YAML stay fatal in both profiles.

Suppressions

Override any rule in skillcheck.config.json:

{
  "rules": {
    "SC104": "off",
    "extension-field": "error"
  }
}