Prompt Refiner Skill
HenrikBrehm/prompt-refiner-skill
Linter determinístico de prompts: detecta bugs sem reescrever
Ver no GitHubLinter híbrido para detecção de bugs em prompts contra um catálogo estável de 20 regras (PR001-PR-INJ03). Combina análise determinística por regex com verificação semântica por modelo, apenas sinalizando problemas sem reescrever. Sem frameworks impostos, sem fluxo de entrevista, sem mudança de idioma.
Instalação
npx convez-ai HenrikBrehm/prompt-refiner-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validar qualidade de prompts antes de usar em produção
- Detectar padrões de injeção de prompt e confusão de papéis
- Melhorar clareza, especificidade e ergonomia de saídas
- Integrar verificação de prompts em pipelines CI/CD
Veredito

Ferramenta prática e minimalista para linting de prompts com 25 testes passando. Ideal para times que querem controle granular sem imposições de framework — aponta o problema, você decide a solução.
README
A tradução para o português deste README ainda está na fila.
prompt-refiner-skill
A hybrid prompt linter — deterministic Node detector for the regex-able rules, model for the semantic ones. Lint, don't rewrite. No framework imposition. No interview flow. No language switching.
Contents
- What it does (and doesn't)
- How the engine works
- Install
- Usage
- Example
- When NOT to use this skill
- How it compares to framework-based prompt tools
- CI integration
- Cost & footprint
- Star history
- Contributing
- License & changelog
What it does (and doesn't)
This skill flags prompt-engineering bugs against a stable, citeable rule catalog (references/lint-rules.md). It does not rewrite your prompt, does not ask clarifying questions, and does not impose a framework. You stay in control of the words; the skill points at the bugs.
Output is Markdown by default. Append --json (or ask for "JSON output") to get a report that validates against schemas/report.schema.json. Every finding is tagged with the engine that produced it.
The catalog ships 20 rules across three families:
- Clarity & specificity —
PR001vague verb,PR002mixed intent,PR003ambiguous pronoun,PR004scale conflict,PR005contradictory constraints,PR006unbounded numeric,PR007implicit format,PR008placeholder leakage,PR009conflicting persona,PR010untestable success criterion. - Output hygiene & ergonomics —
PR011stale relative date,PR012politeness padding,PR013missing input delimiter,PR014reasoning-then-answer without delimiter,PR015unscaled rating,PR016open-ended creative length,PR017negation-only prompt. - Prompt injection / role confusion —
PR-INJ01"ignore previous" pattern,PR-INJ02post-input role switch,PR-INJ03unbounded tool authority.
How the engine works
The skill is a hybrid linter, not a pure LLM rubric:
| Pass | Implementation | Rules covered | Reproducible? |
|---|---|---|---|
| Pure deterministic | scripts/lint.js — zero-dep Node | PR001, PR004, PR006, PR007, PR008, PR011, PR012, PR013, PR014, PR015, PR016, PR017, PR-INJ01, PR-INJ02, PR-INJ03 (15 of 20) | Yes — same input → same findings |
| Hybrid | Deterministic basic case in scripts/lint.js + semantic case in the model layer | PR002, PR005, PR010 (3 of 20) | Basic case: yes. Semantic case: run-to-run drift. |
| Pure model | The LLM at skill activation time | PR003 (antecedent resolution), PR009 (persona / domain comparison) (2 of 20) | No — semantic analysis, run-to-run drift |
18 of 20 rules have deterministic detection (15 pure + 3 hybrid basic case). Run-to-run drift on the model layer is bounded to the 2 pure-model rules and the semantic surplus of the 3 hybrid rules.
Each finding is tagged with the engine that produced it (_(deterministic)_ or _(model)_) so you can tell which line numbers to trust as stable across re-runs. The deterministic pass is independently runnable in CI without an LLM — see the CI integration section.
Install
Option 1 — As a Claude Code plugin (recommended)
/plugin marketplace add HenrikBrehm/prompt-refiner-skill
/plugin install prompt-refiner@prompt-refiner-marketplace
Option 2 — Manual copy (per project)
git clone https://github.com/HenrikBrehm/prompt-refiner-skill.git /tmp/prompt-refiner-skill
mkdir -p .claude/skills
cp -r /tmp/prompt-refiner-skill/skills/prompt-refiner .claude/skills/
The copied skills/prompt-refiner/ directory is self-contained: it includes SKILL.md, the deterministic detector, the rule catalog, JSON schema, and CI recipes.
Option 3 — Manual copy (user-level, all projects)
git clone https://github.com/HenrikBrehm/prompt-refiner-skill.git /tmp/prompt-refiner-skill
mkdir -p ~/.claude/skills
cp -r /tmp/prompt-refiner-skill/skills/prompt-refiner ~/.claude/skills/
Usage
Invoke the skill with any of these phrasings — auto-routing picks it up via the trigger keywords in SKILL.md:
- "Lint this prompt: <your prompt>"
- "Review my prompt for bugs: <your prompt>"
- "Audit prompt: <your prompt>"
- Append
--jsonfor machine-readable output: "lint --json: <your prompt>"
The skill reads your prompt, applies the rule catalog, and emits a Markdown report (or JSON, with --json) — one finding per rule that fired, with line:col citations, quoted evidence, and engine tags.
Example
Prompt:
Handle the customer feedback we got last week and write a tweet about it.
Skill output:
# Prompt-refiner report
`PR001` [warning] 1:1 - `Handle` - vague action verb; name the transformation (e.g. classify, summarize). _(deterministic)_
`PR002` [error] 1:1 - `Handle ... and write a tweet ...` - two distinct intents in one instruction; split into separate steps. _(deterministic)_
`PR003` [warning] 1:60 - `it` - ambiguous antecedent (feedback or tweet?). _(model)_
**summary:** 1 error, 2 warnings, 0 info
The skill quotes literal evidence, cites the rule by ID, and stops. It does not propose a rewrite — that decision stays with you.
When NOT to use this skill
- You're writing a brand-new prompt from scratch. Reach for a framework-based skill instead — for example
prompt-architect(27 frameworks: CO-STAR, RISEN, RTF, RACE, …). It's the right shape for "I have an idea, help me prompt it well." - You want the AI to rewrite the prompt for you. This skill flags; it does not author. Copy the rule rationale and edit by hand, or use a framework-based refiner for a rewrite.
- You want the AI to interview you. This skill is silent until it has a prompt to lint.
How it compares to framework-based prompt tools
prompt-refiner (this skill) | Framework refiners (e.g. prompt-architect, CO-STAR / RISEN / RTF builders) | |
|---|---|---|
| Best for | Auditing a prompt you already wrote | Authoring a new prompt from scratch |
| Output | Lint report (rule citations + evidence) | A rewritten prompt, often 5–10× longer |
| Frameworks (CO-STAR / RISEN / RTF / RACE) | Never imposed — explicitly forbidden | Core feature |
| Language handling | Preserves original (DE → DE, JP → JP, mixed → mixed) | Often switches to English |
| Clarifying questions | Almost never | Often (interview-style) |
| Output shape | Markdown lint report or JSON (--json) | Variable, framework-shaped |
| Behavior on a clean prompt | Reports zero findings | Still imposes structure |
These tools complement each other: use prompt-architect to write a prompt, prompt-refiner to audit it before you ship.
CI integration
The deterministic detector runs without an LLM, so you can wire it directly into git hooks and CI:
# Block commits with errors
node scripts/lint.js --fail-on=error path/to/prompt.md
# JSON output for downstream tools
node scripts/lint.js --format=json path/to/prompt.md
# Lock current findings, fail only on new ones
node scripts/lint.js --write-baseline=.prompt-refiner-baseline.json path/to/prompt.md
node scripts/lint.js --baseline=.prompt-refiner-baseline.json --fail-on=warning path/to/prompt.md
Suppress findings inline:
<!-- prompt-refiner-disable PR001 -->— file-wide.<!-- prompt-refiner-disable-next-line PR001 -->— only the following line.<!-- prompt-refiner-disable-line PR001 -->— only the line it appears on.
Drop-in recipes:
recipes/pre-commit.md— block commits witherror-severity findings.recipes/github-action.md— comment the report on every PR that touches*.prompt.md.
Cost & footprint
The skill loads the lint catalog plus frontmatter on activation (≈ a few KB of Markdown). The deterministic detector (scripts/lint.js) is a single zero-dependency Node file using only the Node stdlib. It calls no external APIs and ships no binaries. The conformance suite (scripts/run-tests.sh) runs all 25 corpus cases in under a second; see scripts/bench.sh to reproduce.
Star history
If this skill saves you from prompt-bloat, a star is the cheapest way to help others find it.
Contributing
PRs welcome — see CONTRIBUTING.md. The bar is high: each change should make the skill more reliable or more discoverable without bloating it. Structural validation lives in scripts/validate-skill.sh and runs on every push and PR via GitHub Actions; conformance lives in scripts/run-tests.sh and tests/corpus/.
License & changelog
- License: MIT © 2026 Henrik Brehm
- Release notes: CHANGELOG.md