api-error-triage

SKILL.md Inspector

Write, validate, and review Agent SKILL.md's directly in Visual Studio Code.

SKILL.md Inspector provides live diagnostics for every file named exactly SKILL.md, guided quick fixes, detailed reports, and workspace-wide checks for naming and scope conflicts. All checks use deterministic static analysis, documented compatibility rules, and configurable heuristics. The extension does not run skills against an agent, so its findings are review guidance—not proof that a skill will be selected, executed correctly, or behave consistently across agent platforms.

Private and offline by default. All analysis runs locally unless you explicitly enable remote-link availability checks. The extension does not use an LLM (in future it will be implement as option, and disabled by default), start an agent, execute commands referenced by inspected files, or collect telemetry.

Features

• Catch invalid skills while you type — check YAML frontmatter, names, descriptions, Markdown links, bundled resources, body structure, and common platform compatibility problems.
• Apply guided fixes — insert required fields or a starter template, convert names to kebab-case, add trigger and boundary clauses, create missing linked files, reference untracked resources, and teach the heuristics new vocabulary.
• Understand what needs attention — keep specification errors, portability warnings, security findings, and optional quality advice clearly separated.
• Catch unsafe instructions — statically flag dangerous and risky shell commands, risky public services, hardcoded credentials, prompt-injection wording, hidden content, and sensitive-path references, in the SKILL.md and its bundled scripts. All offline; nothing is executed.
• Review a complete skill package — inspect description completeness, instruction and resource hygiene, token usage, links, and bundled files in one report.
• See how each agent treats the skill — project one validated skill against documented Claude Code, Codex, and OpenCode behavior (plus the skills-ref spec baseline) and get a per-agent verdict with the findings behind it.
• Compare a collection of skills — find duplicate or confusing names, detect overlapping scopes, review resource graphs, and export a machine-readable skills.index.json.
• Browse skills where your agents keep them — navigate workspace files, save favorites, and discover supported Codex, Claude Code, OpenCode, and GitHub Copilot locations.
• Inspect OpenCode session exports — search a tool timeline, review compatibility and sanitization notices, and match recorded skill calls to local skills by name.
• Tune the extension to your conventions — customize severities, templates, discovery rules, resource directories, heuristic dictionaries, and collision settings.

Quick start

1. Open a folder containing one or more Agent Skills.
2. Open a file named exactly SKILL.md.
3. Review findings in the editor and the Problems panel.
4. Use the lightbulb menu to apply an available fix.
5. Run SKILL.md Inspector: Show SKILL.md Report for a complete view of the active skill.
6. Open the SKILL.md Skills panel to review discovered skills together.

Any opened file named exactly SKILL.md can be validated, even when it is outside a conventional skills/<name>/ layout.

Common workflows

Write or improve one skill

Use the Command Palette or a SKILL.md editor context menu:

The bundled templates are Minimal, Standard, Detailed, and Workflow-oriented. In an empty file, the selected template fills the document. In a non-empty file, it is inserted at the cursor.

Quick fixes are offered for supported findings. Most edit the skill or its bundled files. The vocabulary fixes instead add a sanitized word to the workspace's recognized action verbs or artifacts; when no workspace is open, they use user settings.

Review all skills in a workspace

The SKILL.md Skills panel shows validation status, quality results, and resources for the first open workspace folder. These commands provide broader workflows:

Workspace reports and index exports are cancellable. They analyze saved files; live editor diagnostics and the single-skill report can include unsaved changes.

Browse workspace and installed agent files

Select SKILL.md INSPECTOR in the Activity Bar:

• FAVORITES keeps shortcuts to frequently used SKILL.md files.
• WORKSPACE provides a multi-root file browser with common create, rename, copy, compare, search, terminal, and Trash operations.
• INSTALLED AGENTS discovers supported local SKILL.md, AGENTS.md, and CLAUDE.md files.
• OPENCODE SESSIONS discovers and opens exported OpenCode session JSON.

The Installed Agents view checks declared locations such as ~/.codex/skills, ~/.agents/skills, ~/.claude/skills, ~/.config/opencode/skills, and ~/.copilot/skills. Right-click an agent, group, or skill folder to validate its skills or open a scoped report. Add other local roots with skillMdInspector.navigator.additionalRoots.

Discovery is bounded to known and configured locations. It does not scan your entire home directory or run an agent to locate files.

Inspect an OpenCode session export

1. Open OPENCODE SESSIONS.
2. Choose a folder containing exported OpenCode session JSON.
3. Select a session to open its interactive report.
4. Filter or search the timeline, then expand an event to load its details.

The importer preserve