PromptLint

Your AI agent only follows the instructions it actually understands. PromptLint finds the ones it won't — vague rules, hedging language, bloated files, leaked secrets, conflicting constraints — and shows you exactly how to fix them. In your editor, on every save, before they cost you tokens or debugging time.

The first linter built specifically for AI agent instruction files.

The Problem

You write a 300-line CLAUDE.md. Claude ignores half of it. You don't know which half.

Anthropic's research shows instruction adherence degrades uniformly beyond ~200 lines. Hedging language like "try to" and "consider" is treated as optional. Vague instructions waste token budget on things Claude already does by default. And a single leaked API key in your instruction file is one git push away from a production incident.

You'd never ship code without a linter. Why are you shipping AI instructions without one?

What It Does

PromptLint runs two phases of analysis on your agent instruction files:

Phase 1 — Local Rules (free, instant, every save) 13 deterministic rules catch the most common problems with zero API cost:

Most rules have one-click quick-fixes — look for the lightbulb icon.

Phase 2 — Deep Analysis (optional, requires API key) Claude reviews your instruction file for semantic issues that rules can't catch: conflicting instructions, redundant linting rules, stale file references, missing verification steps, instruction overload.

Supported Files

Quick Start

1. Install from the VS Code marketplace (search "PromptLint")
2. Open any supported file — diagnostics appear instantly
3. That's it. No configuration required for local rules.

For deep analysis, add your Anthropic API key:

// .vscode/settings.json
{
  "promptlint.anthropicApiKey": "sk-ant-..."
}

Or set the ANTHROPIC_API_KEY environment variable.

AI-Readiness Report

Run PromptLint: AI-Readiness Report from the command palette to get a full workspace audit:

• Score (0-100) — bonus points for good practices, penalties for bad ones
• Maturity Level (L0-L6) — from Absent to Adaptive
• Token Budget — how many tokens your instruction files consume, per file
• Penalties Breakdown — which issues are actively hurting your score
• Adoption Roadmap — prioritized steps to improve, tailored to your current level

A bloated, poorly-written CLAUDE.md scores lower than having no CLAUDE.md at all. The score rewards quality, not quantity.

Maturity Levels

Cross-Tool Migration

Switching to Claude Code? Run PromptLint: Migrate to CLAUDE.md to convert:

• .cursorrules → CLAUDE.md
• .cursor/rules/*.mdc → CLAUDE.md
• .github/copilot-instructions.md → CLAUDE.md
• AGENTS.md → CLAUDE.md

PromptLint auto-categorizes your existing content into proper CLAUDE.md sections (Commands, Architecture, Constraints, Gotchas, Verification) and flags anything it can't classify for manual review.

Agent Context Export

Run PromptLint: Export Agent Context to see exactly what your AI agent reads — every instruction file in Claude's load order, with token counts per file.

Think of it as "View Source" for your agent's brain:

• Files shown in priority order (project CLAUDE.md → scoped rules → local overrides → skills)
• Each file tagged: always loaded, path-scoped, on-demand, or other-tool-only
• Full content with token estimates and metadata extraction

Templates

Start from best practices instead of a blank file:

All Commands

Settings

How It Works

PromptLint activates automatically when you open a workspace containing agent instruction files. On every file save and open:

1. Detects the file type (CLAUDE.md, .cursorrules, SKILL.md, etc.)
2. Runs local rules — 13 deterministic checks, instant, free
3. Shows diagnostics inline in the editor with severity icons
4. Offers quick-fixes via the lightbulb menu
5. Optionally enriches with Claude API deep analysis (if API key configured)
6. Updates the status bar with file type and issue count

The AI-Readiness Report scans your entire workspace, computes a weighted score with bonuses and penalties, determines your maturity level, and generates a prioritized adoption roadmap.

Built On Research

PromptLint's rules aren't opinions — they're based on documented findings:

• Anthropic's CLAUDE.md documentation — file hierarchy, recommended structure, line limits
• Boris Cherny's best practices (Claude Code tech lead) — verification gives 2-3x quality improvement
• Agent Skills specification (agentskills.io) — progressive disclosure, token budgets, frontmatter requirements
• LLM instruction adherence research — adherence degrades uniformly beyond recommended limits
• RFC 2119 keyword effectiveness — MUST/NEVER/ALWAYS followed more reliably than hedging language

Contributing

Issues and PRs welcome. See the GitHub repository.

License

MIT