Validate SKILL.md structure, frontmatter completeness, token budget, freshness, naming conventions, and cross-platform portability before publishing.
name: skill-quality-linter
description: Validate SKILL.md structure, frontmatter completeness, token budget, freshness, naming conventions, and cross-platform portability before publishing.
version: "1.0.0"
last-updated: "2026-04-22"
model_tested: "claude-sonnet-4-6"
category: security
platforms: [claude-code, codex, gemini-cli, cursor, copilot, windsurf, cline]
language: en
geo_relevance: [global]
priority: medium
dependencies:
mcp: []
skills: [skill-security-audit]
apis: []
data: []
update_sources:
- url: "https://code.claude.com/docs/en/skills"
check_frequency: "quarterly"
last_checked: "2026-04-22"
license: MIT
Skill Quality Linter
When to Use
- Before publishing a new skill to a registry
- Reviewing a skill PR
- Auditing existing skill quality
- Setting up CI for a skill repository
Lint Checks
1. Frontmatter (Required Fields)
| Field | Required | Format |
|---|
| name | YES | kebab-case, matches directory name |
| description | YES | 1 line, max 250 chars, starts with verb |
| version | YES | Semver (X.Y.Z) |
| last-updated | YES | YYYY-MM-DD, not in future |
| platforms | YES | Array of known platform names |
| license | YES | Valid SPDX identifier |
| dependencies | RECOMMENDED | Object with mcp, skills, apis, data |
| update_sources | RECOMMENDED | Array with url + check_frequency |
| language | RECOMMENDED | ISO 639-1 (en, fr, etc.) |
| geo_relevance | RECOMMENDED | Array (global, fr, eu, africa, etc.) |
| category | RECOMMENDED | Matches parent directory name |
| priority | OPTIONAL | critical, high, medium, low |
2. Structure
| Check | Rule |
|---|
Starts with --- | Valid YAML frontmatter |
Has # Title | H1 heading after frontmatter |
Has ## When to Use | Trigger conditions documented |
Has ## What This Skill Does NOT Do | Limitations section present |
| No H1 other than title | Single H1 only |
Sections use H2 (##) | Consistent hierarchy |
3. Size Budget
| Metric | Limit | Rationale |
|---|
| SKILL.md lines | < 800 | ETH Zurich: more = worse perf |
| SKILL.md tokens | < 2500 | Context window budget |
| SKILL.md + references/ | < 3000 tokens | Total load budget |
| references/ file count | < 5 | Keep focused |
4. Portability
| Check | Rule |
|---|
| No tool-specific syntax | No Read, Write, Bash, Edit references |
| No platform-specific imports | No import, require, from in instructions |
| Natural language instructions | Steps readable by any agent |
| Graceful degradation | "If terminal available... otherwise..." pattern |
5. Freshness
| Age | Status |
|---|
| < 60 days | PASS |
| 60-90 days | WARN — review needed |
| > 90 days | FAIL — must update before use |
6. Naming
| Check | Rule |
|---|
| Directory name | kebab-case, no uppercase |
| name field | Matches directory exactly |
| description | Starts with action verb (Guide, Build, Detect, Generate...) |
| No emoji in name/description | Plain text only |
Output Format
LINT: {skill-name}
Status: PASS | WARN | FAIL
[PASS] Frontmatter: all required fields present
[PASS] Structure: all sections present
[WARN] Size: 2800 tokens (approaching 3000 limit)
[PASS] Portability: no platform-specific syntax
[PASS] Freshness: 5 days old
[PASS] Naming: matches conventions
Verdict: PASS (1 warning)
What This Skill Does NOT Do
- Does not check factual accuracy of content
- Does not validate referenced URLs (use separate check)
- Does not scan for security issues (see
skill-security-audit)
- Does not auto-fix issues (reports only)