vibe-check — Linter & Security Scanner for Claude Skills and Agents

vibe-check

Install Usage Rules Config Scoring GitHub ↗

MIT · Node ≥ 18

You vibe-coded
your agents.
Time for a vibe check.

A linter and security scanner for Claude skills, agents, and AI workspaces. Checks SKILL.md files, agent instruction files (CLAUDE.md, AGENTS.md, rules), harness configs (MCP servers, hooks, permissions), and entire workspaces — including prompt-injection payloads, hidden-unicode smuggling, leaked secrets, and token bloat.

Read the docs →

Inspired by skillscore and agentlinter — extends both with agent file support, workspace diagnosis, injection scanning, GitHub URL analysis, SARIF output, and configurable rule suppression.

$ vibe-check .

Score 58.3 / 100 Grade F

✗ hardcoded AWS key

✗ hidden instruction in HTML comment

❌ Failed the vibe check.

Skills

7 categories: metadata, routing, structure, content, robustness, security, portability.

Agent files

CLAUDE.md, AGENTS.md, Claude Code subagents, OpenCode & Copilot agents — purpose, boundaries, token budget, security.

Workspace

Broken refs, routing conflicts, token budget, security rollup — across Claude Code, OpenCode, Copilot, and APM repo layouts.

Installation

$ npm install -g @femmefatalerror/vibe-check

Or from source:

$ git clone https://github.com/femmefatalerror/vibe-check.git

$ cd vibe-check && npm install

$ npm run build && npm install -g .

Either way, the command is vibe-check. Requires Node ≥ 18.

Usage

Just point it at something

vibe-check <path> figures out what it's looking at:

vibe-check skills/my-skill/ # skill directory → skill lint

vibe-check CLAUDE.md # agent file → agent lint

vibe-check . # plain directory → workspace diagnosis

vibe-check https://github.com/owner/repo/tree/main/skills/my-skill

Example output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

my-skill/SKILL.md

type: skill

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Score 79.8 / 100 Grade C+

Identity & Metadata ███████░░░ 7.0/10

Routing & Discovery ███████░░░ 7.0/10

Structure ██████████ 10.0/10

Content Quality ███████░░░ 6.5/10

Robustness ██████████ 10.0/10

Security ███████░░░ 7.0/10

Portability ██████████ 10.0/10

Tokens (est.) ~154 grade A

⚠ 3 filler phrase(s) — wasted tokens

Findings

✗ [ERROR] skill/meta/name-format :2

name "Claude Helper Tools" must contain only lowercase letters, numbers, and hyphens

→ Try: claude-helper-tools

✗ [ERROR] security/secrets/hardcoded-api-key :21

Possible hardcoded secret: Hardcoded API key

→ Use a placeholder like <YOUR_API_KEY> in docs; never commit real credentials

Companion skill: lint → fix → verify

The linter tells you what is wrong; the bundled agent skill teaches your coding agent to fix it. It runs vibe-check, applies per-rule fix recipes (routing descriptions, structure, content, token optimization), then re-runs the linter and shows the before → after score. Security findings are the exception: the skill explains them and lets you decide — it never silently rewrites flagged content, and it treats scanned files as untrusted data.

Install it

$ vibe-check install-skill # Claude Code → ~/.claude/skills

$ vibe-check install-skill --target opencode # → ~/.config/opencode/skills

$ vibe-check install-skill --target copilot # → ~/.copilot/skills

$ vibe-check install-skill --target agents # cross-client ~/.agents/skills

Installs user-level by default so it works in every project; add --project to install into the current repo instead, and --force to overwrite an existing copy (e.g. after upgrading vibe-check). The agents target covers Copilot, Cursor, OpenCode, Codex, Gemini, and Windsurf in one install.

Use it

No commands to learn — the skill triggers on natural requests in your agent chat:

> vibe check my skills

> why does skills/pdf-tools score so badly?

> fix the vibe-check findings in .claude/skills/deploy

> reduce the token cost of my CLAUDE.md

The agent then reports the baseline score, fixes errors first and warnings second, re-runs the linter to prove the improvement, and accounts for anything it deliberately left alone (with a suggested .vibe-check.json suppression for accepted findings). The skill itself scores 100/100 on its own linter — enforced in CI.

What it checks

Scoring

Each category scores 0–10 based on finding severity, then a weighted average gives a 0–100 score.

SEVERITY

DEDUCTION

GRADE

TOKENS (EST.)

Security cap: any security/* error caps the score at 59 (Grade F) — including findings from companion scripts and referenced markdown. A leaked credential or injection payload can't be averaged away by otherwise-clean categories.

Grades: A+ (≥97) → A → A− → B+ → B → B− → C+ → C → C− → D+ → D → D− → F (<60). Token counts estimated as ceil(bytes / 4). Exit code is 1 when any errors are found — usable in CI quality gates.

Configuration

Create .vibe-check.json in your project root (also accepted: .skill-linter.json, .agentlinter.json, .claude/linter.json):

{

"suppress": [

"skill/content/no-code-examples",

"agent/boundaries/no-stopping-condition"

"severity": {

"skill/content/filler-phrase": "warn",

"agent/instructions/time-sensitive": "error"

}

Or suppress inline, like eslint:

api_key = "sk-example-for-docs-only"

Rule reference

All rule IDs follow the pattern <type>/<category>/<name>.

RULE

SEVERITY

DESCRIPTION

{{ row.id }}

Development

npm run build # compile TypeScript → dist/

npm test # run the test suite

What's not here yet

Custom rules — user-defined rule functions via config (planned for v2)
Auto-fix — automated fixes for safe issues
Cross-file contradiction detection — conflicting instructions between agent files

MIT License · github.com/femmefatalerror/vibe-check

You vibe-coded
your agents.
Time for a vibe check.

Installation

Usage

Just point it at something

{{ block.title }}

Example output

Companion skill: lint → fix → verify

Install it

Use it

What it checks

{{ grp.title }}

Scoring

Configuration

Rule reference

{{ tbl.title }}

Development

What's not here yet

You vibe-codedyour agents.Time for a vibe check.

Installation

Usage

Just point it at something

{{ block.title }}

Example output

Companion skill: lint → fix → verify

Install it

Use it

What it checks

{{ grp.title }}

Scoring

Configuration

Rule reference

{{ tbl.title }}

Development

What's not here yet

You vibe-coded
your agents.
Time for a vibe check.