promptocop: Instructions file for Claude Code

promptocop

A prompt linter for Claude Code and Cursor. Analyzes your prompts for anti-patterns and surfaces issues as context for the model — like ESLint, but for the prompts you type in your AI editor.

---

Project overview

promptocop is a Node.js CLI tool that analyzes prompts for anti-patterns known to cause correction loops, token waste, and task drift. It ships with a rule engine modeled after ESLint: rules have severity levels (error/warn/info), are individually configurable via a .promptocop.yml config file, and can be organized into shareable presets.

There are three integration modes:

1. Standalone CLI — promptocop lint "your prompt" run manually before sending
2. Agent Skill (Claude Code & Cursor) — a SKILL.md installed into the editor's skills directory that the editor loads automatically and uses to review prompts via AI reasoning
3. Editor Hook (Claude Code & Cursor) — wired into the editor's prompt submit lifecycle hook so it runs automatically before every message using static regex rules

---

Tech stack

• Runtime: Node.js (>=18)
• Language: TypeScript
• CLI framework: commander
• Config parsing: js-yaml
• Output formatting: chalk + ora
• Testing: vitest
• Distribution: npm package, executable via npx promptocop

---

Project structure

promptocop/
├── src/
│   ├── cli.ts              # Entry point, commander setup
│   ├── linter.ts           # Core lint runner — loads rules, runs them, collects results
│   ├── config.ts           # .promptocop.yml loader and resolver
│   ├── formatter.ts        # Output formatting (default, json, compact, directive)
│   ├── fixer.ts            # --fix mode: applies auto-fixes to prompt
│   ├── types.ts            # Shared TypeScript interfaces (Rule, RuleResult, LintResult, etc.)
│   ├── __tests__/          # Integration tests (cli-hook, config, formatter)
│   ├── rules/
│   │   ├── index.ts        # Rule registry + getRuleByName helper
│   │   ├── __tests__/      # Per-rule unit tests
│   │   ├── no-vague-verb.ts
│   │   ├── no-ambiguous-pronoun.ts
│   │   ├── no-file-context.ts
│   │   ├── no-constraints.ts
│   │   ├── multi-task.ts
│   │   ├── missing-success-criteria.ts
│   │   ├── context-dump-risk.ts
│   │   └── prefer-example.ts
│   ├── presets/
│   │   └── recommended.ts  # Default ruleset and severities
│   ├── skill/
│   │   ├── generate.ts     # Generates SKILL.md content from the rule registry
│   │   └── install.ts      # Claude Code skill installer / uninstaller
│   └── hook/
│       ├── install.ts      # Target-agnostic hook installer / uninstaller
│       ├── targets.ts      # Editor-specific hook targets (Claude Code, Cursor)
│       └── __tests__/      # Hook unit + integration tests
├── CLAUDE.md               # This file
├── package.json
├── tsconfig.json
└── vitest.config.ts