This page documents the quick_validate.py script located in skills/skill-creator/scripts/, which provides a command-line tool for statically validating a skill directory against the SKILL.md specification. The script checks structural and content constraints and exits with a non-zero code on failure, making it suitable for CI integration.
For the full SKILL.md format specification (field definitions, allowed values, and semantic meaning), see SKILL.md Format Specification. For guidance on creating a new skill from scratch, see Creating a New Skill.
The script accepts a single positional argument: the path to the skill directory to validate.
python quick_validate.py <skill_directory>
Exit codes:
| Exit Code | Meaning |
|---|---|
0 | Skill passed all validation gates |
1 | At least one validation gate failed |
Example output (passing):
Skill is valid!
Example output (failing):
Name 'My Skill' should be kebab-case (lowercase letters, digits, and hyphens only)
The script always prints exactly one message to stdout describing the outcome. On failure, the message identifies the specific gate that was violated.
Sources: skills/skill-creator/scripts/quick_validate.py96-103
The validator applies checks sequentially. The first failed check terminates validation and returns its error message. All gates must pass for the skill to be considered valid.
Validation gate overview:
Sources: skills/skill-creator/scripts/quick_validate.py12-94
Checks that a file named SKILL.md exists directly inside the provided skill directory path.
SKILL.md not foundThe full file content is read and checked to ensure it begins with the string ---, indicating the start of YAML frontmatter.
No YAML frontmatter foundA regex match extracts the frontmatter block. The pattern ^---\n(.*?)\n--- is applied with re.DOTALL. If no match is found, the frontmatter is considered malformed.
Invalid frontmatter formatThe extracted frontmatter text is parsed using yaml.safe_load. Two failure conditions exist:
yaml.YAMLError is raised).dict (e.g., a bare scalar or list).| Condition | Error Message |
|---|---|
| YAML syntax error | Invalid YAML in frontmatter: <exception> |
| Not a dict | Frontmatter must be a YAML dictionary |
The set of keys present in the parsed frontmatter is compared against the hardcoded ALLOWED_PROPERTIES set:
{'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
Any key not in this set causes a failure. The error message lists all unexpected keys and the full set of allowed properties. Note that nested keys under metadata are not checked; only top-level keys are validated.
Unexpected key(s) in SKILL.md frontmatter: <keys>. Allowed properties are: <allowed>nameChecks that a name key exists in the parsed frontmatter dictionary.
Missing 'name' in frontmatterdescriptionChecks that a description key exists in the parsed frontmatter dictionary.
Missing 'description' in frontmatterIf the name field is non-empty after stripping whitespace, four sub-checks are applied in order:
| Sub-check | Rule | Error |
|---|---|---|
| Type | Must be a str | Name must be a string, got <type> |
| Character set | Must match ^[a-z0-9-]+$ (kebab-case) | Name '<name>' should be kebab-case (lowercase letters, digits, and hyphens only) |
| Hyphen position | Cannot start or end with -, cannot contain -- | Name '<name>' cannot start/end with hyphen or contain consecutive hyphens |
| Length | Maximum 64 characters | Name is too long (<n> characters). Maximum is 64 characters. |
If the description field is non-empty after stripping whitespace, three sub-checks apply:
| Sub-check | Rule | Error |
|---|---|---|
| Type | Must be a str | Description must be a string, got <type> |
| Angle brackets | Must not contain < or > | Description cannot contain angle brackets (< or >) |
| Length | Maximum 1024 characters | Description is too long (<n> characters). Maximum is 1024 characters. |
The angle bracket restriction exists because < and > are commonly used as placeholder syntax (e.g., <skill-name>) and can cause ambiguity when descriptions are parsed at runtime.
The compatibility field is optional. If it is present and non-empty, two sub-checks apply:
| Sub-check | Rule | Error |
|---|---|---|
| Type | Must be a str | Compatibility must be a string, got <type> |
| Length | Maximum 500 characters | Compatibility is too long (<n> characters). Maximum is 500 characters. |
The following table summarizes all field-level constraints enforced by quick_validate.py:
| Field | Required | Type | Max Length | Additional Constraints |
|---|---|---|---|---|
name | Yes | str | 64 chars | kebab-case only ([a-z0-9-]+); no leading/trailing/double hyphens |
description | Yes | str | 1024 chars | No angle brackets (<, >) |
license | No | (unchecked) | — | Presence allowed; value not validated |
allowed-tools | No | (unchecked) | — | Presence allowed; value not validated |
metadata | No | (unchecked) | — | Top-level key allowed; nested keys not inspected |
compatibility | No | str | 500 chars | — |
Sources: skills/skill-creator/scripts/quick_validate.py42-92
The script exposes a single public function and a __main__ entry point.
Sources: skills/skill-creator/scripts/quick_validate.py1-103
The quick_validate.py script is part of the skill-creator skill's utility scripts. It is a standalone tool — it does not import from other skill scripts and has no runtime dependency on the skill-creator's evaluation pipeline. Its only dependencies are the Python standard library (sys, os, re, pathlib) and PyYAML.
It is designed to be run before submitting a skill to the marketplace or packaging it as a .skill file. For the full skill packaging and evaluation workflow, see Skill Creator Workflow.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.