skill-linter
32
总安装量
18
周安装量
#11595
全站排名
安装命令
npx skills add https://github.com/majesticlabs-dev/majestic-marketplace --skill skill-linter
Agent 安装分布
claude-code
12
opencode
12
gemini-cli
11
github-copilot
9
codex
9
Skill 文档
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