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.

Description Routing Quality (WARN)

Skill descriptions are routing logic, not documentation. They answer:

• When to use this skill (trigger conditions)
• When NOT to use (negative routing)
• What outputs to expect (success criteria)

Templates inside skills are encouraged — loaded only on trigger, essentially free tokens.

Skill Disambiguation (INFO)

When multiple skills cover similar domains, include negative routing:

Example (minitest vs rspec):

"Don't use when..." is as important as "Use when..." for routing accuracy.

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

uv run python scripts/validate_skills_tier1.py path/to/skill-name

Validate All Marketplace Skills

for skill in plugins/*/skills/*/; do
  uv run python scripts/validate_skills_tier1.py "$skill"
done

CI Integration

Add to pre-commit hook or CI pipeline:

- name: Lint Skills
  run: |
    for skill in plugins/*/skills/*/; do
      uv run python scripts/validate_skills_tier1.py "$skill" || exit 1
    done

Validation Script

The linter script at scripts/validate_skills_tier1.py 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 - box-drawing characters outside fenced code blocks (WARN)
9. No persona statements - "You are a/an/the" outside fenced code blocks (FAIL)
10. Description routing quality - routing keywords present (WARN)
11. Marketing copy detection - buzzwords in description (WARN)

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
[PASS] No ASCII art outside code blocks
[PASS] No persona statements
[PASS] Description has routing keywords
[PASS] No marketing copy in description

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