skill-linter

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

Optional Frontmatter

Structure Requirements

Content Quality Rules

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:

✅ 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:

1. Directory exists with SKILL.md file
2. Frontmatter present with YAML delimiters
3. Name field valid - pattern, length, matches directory
4. Description field valid - present, length constraints
5. Optional fields valid - if present, match constraints
6. Line count - under 500 lines
7. Subdirectory names - only allowed directories
8. No ASCII art - detects box-drawing characters and decorative diagrams

Error Codes

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