Skill Quality Linter

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 | | updatesources | RECOMMENDED | Array with url + checkfrequency | | 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 | 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BuilderCed
• Source: BuilderCed/agent-skills
• License: MIT
• Homepage: https://skills.sh/BuilderCed/agent-skills

Install and usage instructions live in the source repository linked above.