AI & agents

Prompt and Agent Instruction Linter

Review AI prompts and agent instructions locally for vague goals, conflicting requirements, risky permissions, missing success criteria, and weak safety boundaries.

Runs locally in your browser

Prompt or agent instruction

StatusHigh ambiguity

Instruction score1/100

Findings7

High severity2

Goal may be too thinMEDIUM · Short agent instructions often leave too much room for interpretation. Fix: Add the desired outcome, relevant context, constraints, and what a good final answer should contain.

Missing success criteriaHIGH · An agent can keep working or stop too early when the definition of done is unclear. Fix: Add acceptance checks, required tests, expected files, or concrete conditions that prove the task is finished.

Conflicting verbosity requestMEDIUM · The instruction asks for both short and highly detailed output. Fix: Choose one output style, or split it into `brief summary first, detailed appendix only if needed`.

Risky action without approval boundaryHIGH · The instruction mentions destructive, production, or deployment-related work without saying when to ask first. Fix: Add a rule requiring confirmation before destructive commands, production changes, credential rotation, or irreversible operations.

Tool permissions are broadMEDIUM · Agents behave better when tool permissions are scoped to specific files, commands, systems, or safety rules. Fix: Define the allowed write scope, forbidden actions, and what should be reported instead of executed.

Output format is undefinedLOW · A clear output format makes agent responses easier to evaluate and reuse. Fix: Specify whether the agent should return a checklist, patch summary, JSON object, table, or short final answer.

Context source is unclearLOW · Agents need to know what material is authoritative. Fix: Point to the relevant files, docs, examples, logs, URLs, or say what assumptions are allowed.

Safer instruction template

Goal:
Run commands and fix the production bug. Be brief but give a thorough explanation. You can deploy when done. The logs may contain tokens.

Context:
- Use the attached files, docs, logs, or links as the source of truth.
- State assumptions before acting when context is incomplete.

Boundaries:
- Do not expose secrets, tokens, passwords, private keys, or private user data.
- Ask before destructive commands, production changes, credential rotation, or irreversible operations.
- Keep edits scoped to the requested files and behavior.

Output format:
- Start with findings or completed changes.
- Include verification results and any remaining risks.

Acceptance checks:
- The requested behavior is implemented or the blocker is clearly explained.
- Relevant tests, build checks, or manual checks are listed.
- Address these lint findings: Goal may be too thin; Missing success criteria; Conflicting verbosity request; Risky action without approval boundary; Tool permissions are broad; Output format is undefined; Context source is unclear.

How to use this tool

Paste the prompt, system-style instruction, agent task, or coding-agent handoff you want to review.

Check warnings about unclear goals, missing acceptance criteria, broad tool permissions, risky production actions, and weak secret-handling rules.

Copy the safer instruction template and adapt it before giving the task to an AI assistant or autonomous agent.

What makes agent instructions fail

Agents tend to fail when the task is vague, the success criteria are missing, or the instruction gives broad tool access without safety boundaries.

Conflicting directions such as `be brief` and `be exhaustive` can also make the final output harder to evaluate.

A useful instruction names the goal, source of truth, allowed actions, forbidden actions, output format, and checks that prove completion.

Safety boundaries for coding agents

Coding agents should know when to ask before destructive commands, production deploys, credential rotation, database changes, or irreversible edits.

The prompt should also explain how to handle secrets, logs, tokens, private URLs, and user data.

A good boundary does not block useful work; it makes autonomous work easier to trust.

How to use the lint score

The score is a heuristic signal, not a universal prompt quality metric.

Use high-severity findings as blockers and medium findings as improvements before handing work to an agent.

After editing the prompt, rerun the linter and check that acceptance criteria, permissions, and output format are explicit.

Examples

Risky agent handoff

This mixes production authority, vague scope, and conflicting output expectations.

Input

Fix production. You can deploy. Be brief but explain everything.

Safer instruction pattern

Output

Goal: fix the failing login test.
Context: use the attached repo and CI log.
Boundaries: ask before production changes or destructive commands.
Acceptance checks: tests pass and the final answer lists verification.

FAQ

Does this use an AI model to judge my prompt?

No. The linter runs deterministic checks locally in your browser and does not send the instruction to an external AI service.

Can this guarantee an agent will behave correctly?

No. It catches common instruction problems, but agent behavior still depends on the model, tools, environment, policies, and available context.

What should every agent instruction include?

At minimum: goal, context, allowed scope, forbidden actions, secret-handling rules, output format, and acceptance checks.

Why are destructive or production actions flagged?

Autonomous agents need explicit approval boundaries before irreversible operations, production deploys, data deletion, or credential changes.