Skill Inspector 是一个 JetBrains IDE 插件, 把每一份
SKILL.md 当成一等公民的可检查文档 —
实时检查、Quick Fix、Problems 面板集成, 全部基于
Agent Skills 官方规范,
零第三方依赖.
规则按 "确定性 + 风险" 分组, 和 IDEA 处理 Inspection 结果的方式一致. 每条规则都有一个稳定的 ID — 可引用、可禁用、可上报 — 绝不藏在不透明的 "AI 这么说" 启发式里.
| # | Rule ID | 严重度 | 说明 | Quick Fix |
|---|---|---|---|---|
| 2.01 | frontmatter.missing |
Error | 缺 YAML frontmatter; 跳过后续所有字段检查. | ADD_FRONT_MATTER |
| 2.02 | frontmatter.name.mismatch |
Error | name 字段与父目录名不一致. |
SYNC_NAME_WITH_DIRECTORY |
| 2.03 | frontmatter.name.invalid |
Error | name 不符合 ^[a-z0-9]+(?:-[a-z0-9]+)*$. |
CONVERT_NAME_TO_KEBAB |
| 2.04 | frontmatter.description.missing |
Error | 缺失或为空的 description; Agent 无法触发. |
ADD_DESCRIPTION |
| 2.05 | description.too-generic |
Warn | Description 是 helper / tool / skill / assistant / utility 之一. |
— |
| 2.06 | description.missing-usage |
Warn | 没有触发短语 ("use when"、"使用" 等). | — |
| 2.07 | reference.missing-file |
Warn | 相对链接指向的文件在磁盘上不存在. | CREATE_MISSING_REFERENCE |
| 2.08 | reference.case-mismatch |
Warn | 链接大小写与磁盘项不一致 (迁到 Linux 后会断). | — |
| 2.09 | resource.unused-reference |
Warn | references/ 下的文件从未被 SKILL.md 引用. |
— |
| 2.10 | security.dangerous-command |
Error | 正文中出现 rm -rf / 或管道式 curl … | sh. |
— |
| 2.11 | security.secret-pattern |
Error | 疑似 api_key / token / secret / password 字段或高熵值. |
— |
| 2.12 | security.sensitive-path |
Warn | 正文引导访问 ~/.ssh、.env、~/.aws. |
— |
↳ 完整表格 (含严重度与 Quick Fix 映射) 见 docs/rules.md.
每项能力都对应一种真实的 SKILL.md 写作痛点:
漏字段直接上线、相对链接断裂、悄悄混进危险脚本片段、
description 模糊到 Agent 没法触发.
注册了一个 LocalInspectionTool, 自动绑定到每一份
SKILL.md 文件 (严格按文件名 gate, 其他 Markdown
完全不受影响). 错误和警告实时显示在编辑器 gutter 和 Problems
面板 — 体验跟 Kotlin / Java 文件完全一致.
添加缺失的 frontmatter、把 name 同步到父目录、
转成 kebab-case、为缺失的引用创建占位文件 — 一次
Alt+Enter 即可. 插件永远不会自动改写你的正文.
右键 → Validate Skill. 后台任务通过
FilenameIndex 扫描所有 SKILL.md,
汇总 Error / Warning 总数并跳转到第一个出错文件. 也可以在 CI
中以 headless inspection 形式跑同一套规则.
所有规则锚定在 Agent Skills 官方规范, 不锚定任何单一 Agent 的私有扩展. Agent 特定的差异在 V2 以 兼容性提示形式补充, 永远不作为默认错误. 你的 skill 保持可移植.
状态栏自带一个 widget, 一键开关整个 Inspection — 不用钻进 Settings → Inspections. 细粒度调节走 Tools → Skill Inspector.
规则手册 →
纯 IntelliJ Platform API — 不引入任何第三方插件库, 无 telemetry,
无远程调用. 内网 / 涉密环境完全可用; 想验证的话直接
jar -tf 看插件 zip 内含什么.
SKILL.md 到底长什么样.
下面三对最小示例来自上面的规则清单. 每一对左边是触发规则的输入, 右边是按一次 Alt+Enter 之后的样子.
Agent 通过目录名来发现 skill. 如果 name 漂移了
(snake_case、大小写、拼错), 这个 skill 就再也无法被寻址.
Quick Fix · SYNC_NAME_WITH_DIRECTORY
description 是 Agent 发现 loader 读取的第一道字段,
在加载正文之前. 留空 = 在每个 prompt 上对每个 Agent 都不可见.
Quick Fix · ADD_DESCRIPTION
安全规则只定位上报, 绝不自动改写. 管道式 curl … | sh
会被精准定位到具体 text range — 该 pin hash、该换源、还是该
接受风险加 noinspection, 由你决定.
在项目积累更多真实用户之前, 这是 Skill Inspector 设计时优先服务的 场景. 我们拒绝用 stock 头像编造客户引言 — 等到真实用户开口, 下面的引述就会逐字替换.
我希望 SKILL.md 在 commit 之前就大声报错.
在 IDEA 里打开文件. 缺必填字段、目录名漂移、相对链接断裂 — 都会在你 push 之前出现在 gutter 上. 按 Alt+Enter 应用确定性修复; 正文仍然归你.
团队为多个 Agent 写 skill, 我要 一致的质量门槛.
所有开发者的 IDE 看到的 Inspection 结果完全一致 — 因为规则装在插件里,
不在个人 config 里. CI 也可以在每个 PR 上 headless 跑同一套
Validate Skill, 不合规的 skill 不会进 main.
我发布 skill 包, 不希望 reviewer 把时间花在 机械错误 上.
结构 / 质量 / 引用类规则自动 catch 那些无聊的事情 —
name 不匹配、死链、过宽的描述、
references/ 下没人引用的文件. Reviewer
可以专心看 内容, 而不是格式.
我要知道 skill 里有没有 curl … | sh, 有没有 泄密.
安全规则会标记危险命令、疑似 API key、高熵字符串、
敏感路径 (~/.ssh、.env) 以及
prompt-injection 文案. V1 只定位上报, 绝不自动改写 —
决定权永远在人手上.
sinceBuild = 242.2、untilBuild = 261.*.
CI 在 IC/IU 2024.2、2024.3、2025.1、2025.2、2025.3 上完成构建与验证;
2026.1 在声明的兼容性范围内. 同平台的其他 JetBrains IDE
(PyCharm / GoLand / WebStorm 等) 通常也能在这个 build range 内工作,
但只有 IDEA 经过 CI 测试.
frontmatter.name.mismatch
或 security.dangerous-command. 完整表格见
docs/rules.md.
SKILL.md, 所有 Inspection 都在本地完成,
适用于完全离线 / 涉密环境.
name 字段、
把 name 同步到父目录、
把 name 转为 kebab-case、
添加 description 占位、
为缺失引用创建空文件 (含父目录).
插件永远不会自动改写你的正文.
SkillFrontMatter 领域 record, 知道
name 必须等于父目录名, 校验 skill 目录内的相对链接
(含跨平台大小写检查), 还会扫描安全风险.
这些通用 Markdown lint 工具都做不到.
SKILL.md 的文件生效?PsiFile.getName().equals("SKILL.md").
这保证 readme.md、notes.md
等其他 Markdown 文件完全不受影响 —
不打开 skill 文件就感受不到这个插件.
到 JetBrains Marketplace 安装, 打开任意包含
SKILL.md 的项目, 检查结果会在同一秒出现.
全部上手成本就是这一步.