Skill Linter
When to Use
- Adding new skills to the marketplace
- Reviewing skill PRs
- Running quality gates before merge
- Checking existing skills for compliance
Validation Rules
Required Frontmatter
| Field | Constraints |
|---|---|
name | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match parent directory name |
description | 1-1024 chars, non-empty, should include keywords for discoverability |
Optional Frontmatter
| Field | Constraints |
|---|---|
license | Short license name or file reference |
compatibility | 1-500 chars, environment requirements |
metadata | Key-value pairs (string values only) |
allowed-tools | Space-delimited tool list |
Structure Requirements
| Rule | Requirement |
|---|---|
| Directory name | Must match name field exactly |
| SKILL.md | Required, must exist |
| Line limit | Max 500 lines in SKILL.md |
| Subdirectories | Only scripts/, references/, assets/ allowed |
Content Quality Rules
| Rule | Requirement |
|---|---|
| No ASCII art | Box-drawing characters (─│┌┐└┘├┤┬┴┼), arrows (↑↓←→↔), and decorative diagrams waste tokens. LLMs tokenize character-by-character, not visually. Use plain lists or tables instead. |
| No decorative quotes | Inspirational quotes or attributions ("As X said...") have no functional value for LLM execution. |
| No persona statements | "You are an expert..." wastes tokens. Use Audience: / Goal: framing instead. |
| Functional content only | Every line should improve LLM behavior. Ask: "Does this help Claude execute better?" |
Audience/Goal Framing (Required)
Replace persona roleplay with audience-focused framing:
❌ Bad (persona):
You are an expert software engineer with deep expertise in testing.
Your role is to analyze code and generate thorough test coverage.
✅ Good (audience/goal):
**Audience:** Developers needing test coverage for new or changed code.
**Goal:** Generate comprehensive tests based on specified test type and framework.
Rationale: "Explain X for audience Y" yields better-tailored outputs than "Act as persona Z".
ASCII Art Detection Pattern:
[─│┌┐└┘├┤┬┴┼╭╮╯╰═║╔╗╚╝╠╣╦╩╬↑↓←→↔⇒⇐⇔▲▼◄►]{3,}
Files matching this pattern should be flagged for review.
Name Pattern
^[a-z][a-z0-9]*(-[a-z0-9]+)*$
Valid: my-skill, skill1, api-v2-handler
Invalid: -skill, skill-, my--skill, MySkill, my_skill
Command/Agent Invocation Patterns
Skills should primarily provide knowledge, not orchestration. If invocations are needed:
| Pattern | Status | Use Instead |
|---|---|---|
Skill("command", args: "...") | ❌ Deprecated | /command args |
SlashCommand("command", ...) | ❌ Deprecated | /command args |
Task(subagent_type="agent", ...) | ✅ Correct | (no change) |
✅ Preferred command invocation:
/majestic:config tech_stack generic
/majestic-engineer:tdd-workflow
/majestic-ralph:start "task" --max-iterations 50
❌ Deprecated patterns:
Skill("config-reader", args: "tech_stack generic")
SlashCommand("majestic:build-task", args: "...")
Note: Agent invocation via Task() is correct - there is no @agent syntax.
Usage
Validate Single Skill
./scripts/validate-skill.sh path/to/skill-name
Validate All Marketplace Skills
for skill in plugins/*/skills/*/; do
./scripts/validate-skill.sh "$skill"
done
CI Integration
Add to pre-commit hook or CI pipeline:
- name: Lint Skills
run: |
for skill in plugins/*/skills/*/; do
.claude/skills/skill-linter/scripts/validate-skill.sh "$skill" || exit 1
done
Validation Script
The linter script at scripts/validate-skill.sh performs these checks:
- Directory exists with SKILL.md file
- Frontmatter present with YAML delimiters
- Name field valid - pattern, length, matches directory
- Description field valid - present, length constraints
- Optional fields valid - if present, match constraints
- Line count - under 500 lines
- Subdirectory names - only allowed directories
- No ASCII art - detects box-drawing characters and decorative diagrams
Error Codes
| Code | Meaning |
|---|---|
| 0 | All validations passed |
| 1 | Missing SKILL.md |
| 2 | Invalid frontmatter |
| 3 | Name validation failed |
| 4 | Description validation failed |
| 5 | Optional field validation failed |
| 6 | Line limit exceeded |
| 7 | Invalid subdirectory |
| 8 | ASCII art detected (warning) |
Example Output
Validating: plugins/majestic-tools/skills/brainstorming
[PASS] SKILL.md exists
[PASS] Frontmatter present
[PASS] Name 'brainstorming' valid (12 chars)
[PASS] Name matches directory
[PASS] Description valid (156 chars)
[PASS] Line count: 87/500
[PASS] Subdirectories valid
Result: ALL CHECKS PASSED
Spec Reference
Based on agentskills.io/specification:
- Progressive disclosure - Metadata ~100 tokens at startup, full content <5000 tokens when activated
- Reference files - Keep one level deep from SKILL.md
- Token budget - Main SKILL.md recommended under 500 lines