Skill Inspector is a JetBrains IDE plugin that treats every
SKILL.md as a first-class linted document —
real-time inspections, quick fixes, and a Problems-panel
integration anchored to the official
Agent Skills specification,
with zero external dependencies.
Rules are grouped by determinism and risk, the same way IDEA groups inspection results. Every rule has a stable ID you can cite, suppress, or report against — no opaque "AI says so" heuristics.
| # | Rule ID | Severity | Description | Quick Fix |
|---|---|---|---|---|
| 2.01 | frontmatter.missing |
Error | No YAML frontmatter; all subsequent field checks are skipped. | ADD_FRONT_MATTER |
| 2.02 | frontmatter.name.mismatch |
Error | name field does not equal the parent directory name. |
SYNC_NAME_WITH_DIRECTORY |
| 2.03 | frontmatter.name.invalid |
Error | name does not match ^[a-z0-9]+(?:-[a-z0-9]+)*$. |
CONVERT_NAME_TO_KEBAB |
| 2.04 | frontmatter.description.missing |
Error | Missing or empty description; agents cannot trigger. |
ADD_DESCRIPTION |
| 2.05 | description.too-generic |
Warn | Description is one of helper, tool, skill, assistant, utility. |
— |
| 2.06 | description.missing-usage |
Warn | No trigger phrase ("use when", "when to use", etc.). | — |
| 2.07 | reference.missing-file |
Warn | Relative link target does not exist on disk. | CREATE_MISSING_REFERENCE |
| 2.08 | reference.case-mismatch |
Warn | Link case differs from on-disk entry (will break on Linux). | — |
| 2.09 | resource.unused-reference |
Warn | File under references/ is never linked from SKILL.md. |
— |
| 2.10 | security.dangerous-command |
Error | Detects rm -rf / or piped curl … | sh in body. |
— |
| 2.11 | security.secret-pattern |
Error | Suspected api_key, token, secret, password or high-entropy value. |
— |
| 2.12 | security.sensitive-path |
Warn | Body steers towards ~/.ssh, .env, ~/.aws. |
— |
↳ The complete table, with severities and quick-fix mappings, lives in docs/rules.md.
Every capability removes a real friction in writing
SKILL.md: missing fields shipped to production,
broken relative links, dangerous shell snippets, descriptions
Agents cannot trigger on.
A LocalInspectionTool attaches to every
SKILL.md file (gated strictly on file name, so other
Markdown stays untouched). Errors and warnings appear live in the
editor gutter and Problems panel — exactly like a Kotlin or Java
file would.
Add missing frontmatter, sync name with the parent
directory, convert to kebab-case, scaffold a missing reference —
one Alt+Enter away. The plugin never
rewrites your prose.
Right-click → Validate Skill. A background task
FilenameIndex-scans every SKILL.md,
aggregates a clean Error/Warning summary, and jumps to the first
failing file. Works in CI via headless inspection too.
Rules anchor on the official Agent Skills specification, not any single Agent's private extension. Agent-specific quirks become advisory profiles in V2 — never default errors. Your skills stay portable.
A status-bar widget toggles the whole inspection on or off with a single click — no hunting through Settings → Inspections. Fine-grained tuning lives at Tools → Skill Inspector.
Rules reference →
Pure IntelliJ Platform API — no third-party plugin kit, no
telemetry, no remote calls. Safe in air-gapped enterprise
environments; jar -tf the bundled plugin if you want
to verify.
SKILL.md actually looks like.
Three minimal examples drawn from the rule manifest above. Each pair shows the input that triggers the inspection, and the file after a single Alt+Enter.
Agents discover a skill by directory name. If name
drifts (snake_case, capitalisation, typo), the skill stops
being addressable.
Quick Fix · SYNC_NAME_WITH_DIRECTORY
The description field is what the discovery loader
reads before the body. Empty means the skill is invisible to
every Agent on every prompt.
Quick Fix · ADD_DESCRIPTION
Security rules locate and flag, never rewrite. A piped
curl … | sh is reported with a precise text range so
you can decide: pin a hash, swap the source, or accept the risk
with a noinspection comment.
Until the project has more shipped users, these are the scenarios Skill Inspector was built to serve. We refuse to invent quotes with stock photos — when real users speak up, the words below will be replaced verbatim.
I want my SKILL.md to fail loudly before I commit it.
Open the file in IDEA. Missing required fields, directory-name drift, or a dead relative link — all surface in the gutter before you push. Alt+Enter applies the deterministic fix; the prose stays yours.
My team writes skills for several agents. I need one quality bar.
Every developer's IDE sees the same inspection results because
the rules live in the plugin, not in personal configs. CI can run
the same Validate Skill sweep headlessly on every PR —
non-spec-compliant skills never reach main.
I publish skill bundles. Reviewers shouldn't waste time on mechanical mistakes.
Structural, quality and reference rules catch the boring stuff
automatically — name mismatches, dead links, descriptions too
vague to trigger, references/ files no one cites.
Reviewers get to focus on content, not format.
I need to know if a skill ships curl … | sh or leaks secrets.
Security rules flag dangerous commands, suspected API keys,
high-entropy strings, sensitive paths (~/.ssh,
.env) and prompt-injection phrases. V1 locates and
reports only — never auto-rewrites — so review stays human-led.
sinceBuild = 242.2 and untilBuild = 261.*.
CI builds & verifies against IC/IU 2024.2, 2024.3, 2025.1,
2025.2 and 2025.3; 2026.1 is covered by the declared
compatibility range. Other JetBrains IDEs on the same platform
(PyCharm, GoLand, WebStorm, …) usually work within that build
range, but only IDEA is tested by CI.
frontmatter.name.mismatch
or security.dangerous-command. Full table in
docs/rules.md.
SKILL.md inside the open project and runs every
inspection locally. Safe for air-gapped environments.
name field,
sync name with the parent directory,
convert name to kebab-case,
add a description stub, and
create the empty referenced file (with parent
directories). The plugin never rewrites your prose.
SkillFrontMatter record,
knows that name must equal the parent directory,
validates relative links inside the skill directory (with
cross-OS case-mismatch detection), and scans for security
risks. A generic Markdown linter does none of that.
SKILL.md?PsiFile.getName().equals("SKILL.md"). That keeps
readme.md, notes.md and any other
Markdown file completely untouched, so the plugin is invisible
until you actually open a skill file.
Install from JetBrains Marketplace, open any project that contains
a SKILL.md, and start seeing results in
the same second. That is the whole onboarding.