Skills Review and Polish

An authoring-time linter and fixer for AI customization files — helps you catch contradictions, ambiguities, coverage gaps, persona conflicts, and quality issues in your SKILL.md, *.instructions.md, *.prompt.md, *.agent.md, and AGENTS.md files.

Uses your GitHub Copilot subscription via the VS Code Language Model API — no API keys required.

✅ Status: v0.1.35 (ready for marketplace)

• v0.1.35 — Recommended model qwen/qwen3-coder-30b-a3b-instruct (E29 benchmark), prompt fixes (-36% boilerplate at corpus scale), MCP analysisWaves param, deepModel config, cross-wave dedup rule. 459/459 tests pass.
• Core analyzer with 6-wave analysis ✅
• Surgical fixer with safety guards ✅
• VS Code integration (diagnostics, code actions, hovers) ✅
• Multi-provider support (Copilot, OpenRouter, GitHub Models) ✅
• MCP server with 7 tools ✅
• Analysis mode comparison (single/focused/multiWave) ✅
• Trace logging for LLM debugging ✅

Features

Analysis

• Detects contradictions, ambiguities, persona conflicts, structural issues, coverage gaps, and hygiene problems
• Real-time VS Code diagnostics with severity levels and explanations
• Smart multi-pass analysis with noise reduction (median-of-N scoring)
• Analyze With Options — two-step modal: choose mode (Single / Focused / Multi-Wave) then toggle individual waves with checkboxes
• Cancel — analysis can be cancelled any time via the VS Code progress notification Cancel button

Fixing

• One-issue-at-a-time surgical fixes with safety guards
• Human-in-the-loop: review each fix with a diff before applying
• Intelligent risk classification prevents over-correction

Integration

• Live VS Code squiggles, quick fixes ("Fix this issue"), and hover explanations
• Full MCP server with 7 tools (analyze, fix, score, verify_fix, accept_finding, list_accepted_findings, health)
• .skills-review.json config sync from VS Code settings
• Markdown linting for documentation quality
• Git hooks for pre-commit/pre-push validation

Quick Start

Install & Run

1. Clone: git clone https://github.com/mutl3y/skills-review-and-polish.git
2. Install: npm install
3. Debug: npm run compile then press F5 in VS Code

Analyze Your Files

1. Open any SKILL.md, *.instructions.md, *.prompt.md, or *.agent.md
2. Run: Skills Review: Analyze This File (Cmd/Ctrl+Shift+P)
3. View issues as VS Code squiggles
4. Click "Fix this issue" to preview and apply fixes

Configuration

Open VS Code Settings and search "Skills Review":

• enable — Turn on/off
• provider — Which LLM to use (Copilot by default, or OpenRouter/GitHub Models)
• model — Model id (use the Select Analysis Model command). For OpenRouter, the recommended model is qwen/qwen3-coder-30b-a3b-instruct (see Recommended OpenRouter Models)
• analysisMode — multiWave (recommended), focused (contradictions + ambiguities), or single combined pass
• logLevel — info (default), debug for detailed tracing, or trace for full LLM prompt/response logging

Tip: Use Analyze With Options (Command Palette) to pick mode and waves per-run without changing your settings.

Learn More

For End Users

• User Guide → — Complete guide on how to use the extension (best starting point)
• Tutorials → — Step-by-step walkthroughs (5–15 min each)
• FAQs → — Common questions and answers
• Architecture → — How the analyzer works and why we made these choices

MCP Server

The extension ships with a headless MCP (Model Context Protocol) server for CI/CD, automation, and external tooling.

Quick start:

npm run compile
npm run mcp   # starts stdio server

The server reads .skills-review.json from the workspace root (written by the Sync MCP Config command) or falls back to GITHUB_TOKEN env vars.

See src/mcp/README.md for full setup, client config examples, and the recommended agent workflow.

For Developers

Scripts

npm run compile        # TypeScript compilation
npm run lint           # ESLint check
npm run lint:md        # Markdown documentation lint
npm run test           # Run unit tests
npm run test:fixtures  # Regression suite on test corpus
npm run test:e2e       # Playwright smoke tests
npm run watch          # Watch mode

Core Modules

• src/core/ — Analysis engine (6-wave analyzer, scoring, surgical fixer)
• src/providers/ — LLM provider implementations (vscode.lm, OpenRouter, GitHub Models)
• src/ui/ — VS Code integration (diagnostics, code actions, hovers)
• src/extension.ts — Main activation and command wiring
• tests/ — Unit and E2E test suites

Git Workflow

• Pre-commit hooks enforce linting and type-checking
• Pre-push hooks run the full test suite
• Use git commit --no-verify only in emergencies

See DEVELOPMENT-STANDARDS.md for code quality guidelines, GIT-WORKFLOW.md for detailed git setup, and docs/plan/LEARNINGS.md for engineering context.

Contributing & Support

Report issues, request features, or contribute:

• Open an issue
• See CONTRIBUTING.md for contribution guidelines

Questions?

• Start a discussion
• Read DEVELOPMENT-STANDARDS.md for code patterns
• Check docs/plan/LEARNINGS.md for engineering decisions

Security

This extension handles LLM API interactions and file system access. Security measures applied after Gilfoyle code review (2026-06-09):

• API key redaction — Bearer tokens and API keys stripped from all error messages and status bar tooltips
• Path traversal guards — references/ directory loader validates resolved paths stay within expected boundary; rejects symlinks
• Workspace-root anchoring — Accepted findings and MCP config resolved from workspace root, not process.cwd()
• Input size limits — MCP tools enforce MAX_TEXT_LENGTH to prevent runaway LLM costs
• Concurrent analysis locks — Per-URI analysis serialization prevents race conditions on lastResults
• Safe text replacement — Function-as-replacement prevents $-pattern corruption in surgical fixes

Report vulnerabilities to security@example.com rather than the issue tracker. See SECURITY.md.

License & Conduct

• License: MIT — See LICENSE
• Code of Conduct: Contributor Covenant