skill-linter

技能检查器

使用场景

• 向市场添加新技能
• 审查技能 PR
• 合并前运行质量门禁
• 检查现有技能是否合规

验证规则

必需的 Frontmatter

字段	限制
name	1–64 个字符，仅限小写字母、数字和连字符；不能以连字符开头或结尾，也不能包含连续连字符；必须与父目录名称一致。不能包含 “claude” 或 “anthropic”（保留词）。
description	1–1024 个字符，不能为空，应包含便于发现的关键词。不能包含 XML 尖括号（< >）。

可选的 Frontmatter

字段	限制
compatibility	1–500 个字符，环境要求
metadata	键值对（仅限字符串值）
allowed-tools	以空格分隔的工具列表（遇到逗号或数组语法时判定为失败）

结构要求

规则	要求
目录名称	必须与 name 字段完全一致
SKILL.md	必需，必须存在
README.md	技能文件夹内不得存在（文档应放在 SKILL.md 或 references/ 中）
行数限制	SKILL.md 最多 500 行
子目录	仅允许 scripts/、references/、assets/

内容质量规则

规则	要求
不使用 ASCII 艺术字	框线字符（─│┌┐└┘├┤┬┴┼）、箭头（↑↓←→↔）和装饰性图示会浪费 token。大模型按字符逐个切分 token，而不是按视觉效果。请改用普通列表或表格。
不使用装饰性引言	励志名言或出处引用（“正如 X 所说……”）对大模型执行没有实际价值。
不使用人格设定语句	“你是一位专家……”会浪费 token。请改用 受众： / 目标： 的表述方式。
仅保留功能性内容	每一行都应有助于改善大模型行为。请思考：“这能帮助 Claude 更好地执行任务吗？”

受众/目标表述（必需）

使用面向受众的表述方式，替代角色扮演式的人格设定：

❌ 不佳（人格设定）：

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

✅ 良好（受众/目标）：

**Audience:** Developers needing test coverage for new or changed code.

**Goal:** Generate comprehensive tests based on specified test type and framework.

原因： 与“扮演 Z 角色”相比，“面向 Y 受众解释 X”能生成更贴合需求的输出。

ASCII 艺术字检测模式：

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

匹配此模式的文件应标记出来以供审查。

描述路由质量（警告）

技能描述是路由逻辑，而非文档。它们应说明：

• 何时使用此技能（触发条件）
• 何时不使用（负向路由）
• 预期输出是什么（成功标准）

质量等级	示例
良好	“实现 Stimulus 控制器时使用。不适用于 React 组件。输出包含 targets 和 actions 的控制器。”
合格	“在 Rails 应用中处理 Stimulus 控制器时使用。”
较差	“Stimulus 控制器开发技能。”
反面模式	“用于构建尖端 Stimulus 控制器的全面、强大工具包。”

鼓励在技能中使用模板——仅在触发时加载，实质上不消耗 token。

技能消歧（信息）

当多个技能覆盖相似领域时，应加入负向路由：

示例（minitest 与 rspec）：

技能	描述路由
minitest-coder	“编写 Minitest 测试时使用。不适用于 RSpec——请改用 rspec-coder。”
rspec-coder	“编写 RSpec 测试时使用。不适用于 Minitest——请改用 minitest-coder。”

对于路由准确性，“不适用于……时使用”与“……时使用”同样重要。

名称模式

^[a-z][a-z0-9]*(-[a-z0-9]+)*$

有效： my-skill、skill1、api-v2-handler 无效： -skill、skill-、my--skill、MySkill、my_skill

命令/Agent 调用模式

Skill 应主要提供知识，而不是编排。如果需要调用：

模式	状态	改用
Skill("command", args: "...")	❌ 已弃用	/command args
SlashCommand("command", ...)	❌ 已弃用	/command args
Task(subagent_type="agent", ...)	✅ 正确	（无需更改）

✅ 首选的命令调用方式：

/majestic-engineer:tdd-workflow
/majestic-engineer:workflows:build-task "T1"

配置读取使用函数调用形式（调用 config-reader 技能）：

TECH_STACK = config_read("tech_stack", "generic")

❌ 已弃用的模式：

Skill("config-reader", args: "tech_stack generic")
SlashCommand("majestic:build-task", args: "...")

**注意：**通过 Task() 调用 Agent 是正确的——不存在 @agent 语法。

用法

验证单个 Skill

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

验证所有 Marketplace Skill

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

CI 集成

添加到 pre-commit 钩子或 CI 流水线：

- name: Lint Skills
  run: |
    for skill in plugins/*/skills/*/; do
      .claude/skills/skill-linter/scripts/validate-skill.sh "$skill" || exit 1
    done

验证脚本

scripts/validate-skill.sh 中的 lint 脚本会执行以下检查：

1. 目录存在，且包含 SKILL.md 文件
2. 存在 Frontmatter，且包含 YAML 分隔符
3. 名称字段有效——符合模式和长度要求，且与目录名匹配
4. 保留词——名称不能包含 "claude" 或 "anthropic"（失败）
5. 描述字段有效——字段存在，且符合长度限制
6. Frontmatter 中的 XML 标签——不含尖括号 < >（安全问题，失败）
7. 无 README.md——Skill 文件夹内不存在（警告）
8. 可选字段有效——若存在，则符合约束
9. 行数——少于 500 行
10. 子目录名称——仅使用允许的目录
11. 无 ASCII 艺术字——围栏代码块之外不得包含框线字符（警告）
12. 无角色设定语句——围栏代码块之外不得出现 "You are a/an/the"（失败）
13. 描述的路由质量——包含路由关键词（警告）
14. 营销文案检测——描述中包含流行词（警告）

错误代码

代码	含义
0	所有验证均已通过
1	缺少 SKILL.md
2	Frontmatter 无效
3	名称验证失败
4	描述验证失败
5	可选字段验证失败
6	超出行数限制
7	子目录无效
8	检测到 ASCII 艺术字（警告）
9	检测到角色设定语句
10	描述的路由质量（警告）
11	检测到营销文案（警告）

输出示例

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

规范参考

基于 agentskills.io/specification：

• 渐进式披露——启动时元数据约 100 个 token，激活后完整内容少于 5000 个 token
• 参考文件——与 SKILL.md 的目录层级保持在一层以内
• Token 预算——建议主 SKILL.md 少于 500 行