---

name: skill-linter description: Validate skills against agentskills.io specification. Use when adding new skills to the marketplace, reviewing skill PRs, checking skill compliance, or running quality gates on skills. Validates frontmatter fields (name, description, license, compatibility, metadata, allowed-tools), directory naming, line limits, and structure. allowed-tools: Bash Read Glob Grep

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

CopyYou are an expert software engineer with deep expertise in testing.
Your role is to analyze code and generate thorough test coverage.

✅ Good (audience/goal):

Copy**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:

Copy[─│┌┐└┘├┤┬┴┼╭╮╯╰═║╔╗╚╝╠╣╦╩╬↑↓←→↔⇒⇐⇔▲▼◄►]{3,}

Files matching this pattern should be flagged for review.

Name Pattern

Copy^[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:

Copy/majestic:config tech_stack generic
/majestic-engineer:tdd-workflow
/majestic-ralph:start "task" --max-iterations 50

❌ Deprecated patterns:

CopySkill("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

Copy./scripts/validate-skill.sh path/to/skill-name

Validate All Marketplace Skills

Copyfor skill in plugins/*/skills/*/; do
  ./scripts/validate-skill.sh "$skill"
done

CI Integration

Add to pre-commit hook or CI pipeline:

Copy- 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

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