Agent Skill Lint

Lint SKILL.md files directly in VS Code using skillscheck.

Save a SKILL.md and see errors, warnings, and suggestions inline — no terminal needed.

Features

• Lints on save and on open
• Inline diagnostics placed on the relevant frontmatter field or body line
• Per-skill-root scoping — errors from one skill never leak into another
• Multi-root workspace support with per-folder configuration
• Auto-detects skillscheck via uvx, pipx, or global install
• Status bar indicator with error/warning counts

Requirements

You need skillscheck available on your system. The extension tries these in order:

1. uvx skillscheck — recommended, zero-install via uv
2. pipx run skillscheck
3. skillscheck — globally installed via pip install skillscheck

Or point to a specific binary with the agentSkillLint.executable setting.

Quick Start

1. Install the extension
2. Open a folder containing one or more SKILL.md files
3. Save a SKILL.md — diagnostics appear inline
4. If nothing happens, open View > Output > Agent Skill Lint to check for errors

Commands

Settings

Example workspace settings:

{
  "agentSkillLint.checks": "spec,quality",
  "agentSkillLint.agents": "copilot",
  "agentSkillLint.executable": "/home/me/.local/bin/skillscheck"
}

How It Works

When you save or open a SKILL.md, the extension:

1. Resolves the skill root (parent directory of the SKILL.md)
2. Runs skillscheck --format json <skill-root>
3. Parses the JSON output and maps findings to VS Code diagnostics
4. Highlights the relevant line — frontmatter field checks land on the YAML key, body checks on the first line after frontmatter

Diagnostics are scoped per skill root, so errors from one skill never appear in another. When a workspace-wide run stops reporting a skill, its stale diagnostics are automatically cleared.

How Diagnostics Are Placed

skillscheck reports findings at file level. The extension infers line numbers:

• Frontmatter field checks (e.g. 1b.name.dir-match) — placed on the matching YAML key
• Body checks (e.g. 1e.body.no-heading) — placed on the first line after the closing ---
• Missing fields — placed on the frontmatter opening ---
• Everything else — line 1

Troubleshooting

If diagnostics don't appear:

1. Open View > Output and select Agent Skill Lint — command output and errors are logged there
2. Verify skillscheck is installed: uvx skillscheck --help
3. If using a custom executable, verify the path in settings

Local Development

npm install
npm run compile

Press F5 in VS Code to launch an Extension Development Host.

npm test              # unit tests
npm run test:integration  # VS Code integration tests
npm run lint          # eslint
npm run format:check  # prettier
npm run package       # build .vsix

License

MIT