Validation Rules
Every skill generated or saved in Smidge is validated against 8 checks. These ensure compliance with the Agent Skills specification and maximize compatibility across platforms.
Validation Checks
1. Frontmatter Present and Valid
The file must begin with valid YAML frontmatter enclosed in triple dashes (---). The YAML must parse without errors.
| Severity | Condition |
|---|---|
| Error | No frontmatter delimiters found |
| Error | YAML parsing fails (syntax error) |
| Error | Frontmatter is empty (no fields) |
2. Name: Lowercase-Hyphenated
The name field must be lowercase, hyphenated, and between 2-64 characters. It must match the pattern /^[a-z0-9][a-z0-9-]*[a-z0-9]$/.
| Severity | Condition |
|---|---|
| Error | Name field missing |
| Error | Contains uppercase, spaces, or underscores |
| Error | Starts or ends with a hyphen |
| Error | Exceeds 64 characters |
3. Description: Max 200 Characters
The description field must be present and no longer than 200 characters.
| Severity | Condition |
|---|---|
| Error | Description field missing |
| Error | Exceeds 200 characters |
| Warning | Under 20 characters (likely too vague) |
4. Word Count: Under 5,000 Words
The body (everything after frontmatter) should be under 5,000 words. This ensures agents can process the skill within typical context windows.
| Severity | Condition |
|---|---|
| Warning | Body exceeds 5,000 words |
| Info | Body exceeds 3,500 words (approaching limit) |
references/ directory.5. Instructions Section Present
The file must contain an ## Instructions section with substantive content (at least 50 words).
| Severity | Condition |
|---|---|
| Error | No ## Instructions heading found |
| Warning | Instructions section has fewer than 50 words |
6. Examples Section Present
The file must contain an ## Examples section with at least one input/output pair.
| Severity | Condition |
|---|---|
| Error | No ## Examples heading found |
| Warning | Examples section has no Input/Output pairs |
| Warning | Examples section has fewer than 50 words |
7. Imperative Voice in Instructions
Instructions must use imperative voice — direct commands rather than suggestions. The validator scans for hedging phrases and flags them.
| Severity | Flagged Phrase |
|---|---|
| Warning | "you should" |
| Warning | "you could" |
| Warning | "consider" |
| Warning | "it's recommended" |
| Warning | "you might want to" |
| Warning | "try to" |
8. No Secrets or API Keys
The validator scans for patterns that look like API keys, tokens, passwords, or other sensitive data. This prevents accidental inclusion of secrets in shared skills.
| Severity | Pattern |
|---|---|
| Error | Strings matching API key patterns (sk_live_..., AKIA..., ghp_..., etc.) |
| Error | Password-like strings in configuration blocks |
| Warning | Environment variable values that look like secrets |
Error vs Warning
Validation results are categorized by severity:
- ●Error — the skill is non-compliant and may not work correctly. Errors block auto-install and show a prominent warning in the UI.
- ●Warning — the skill could be improved. Warnings are shown as suggestions but do not block usage.
- ●Info — informational notes about approaching limits or optional improvements.
A skill with zero errors passes validation even if it has warnings. The web app and CLI both display the full validation report after generation.