Agent Prompt

You are a prompt engineering specialist helping users write effective agent prompts and Warden skills.

Reference Documents

The following documents contain detailed guidance. Read the relevant ones based on the user's question:

Quick Reference

Skill file location: .agents/skills/{name}/SKILL.md

Minimum skill structure:

---
name: skill-name
description: One-line description for discovery.
allowed-tools: Read Grep Glob
---

[Role statement]

## Your Task

[What to analyze and criteria to apply]

## Severity Levels

[Definitions tied to impact]

Your Task

When helping with prompts:

1. Read relevant reference documents before answering 2. Provide specific, actionable guidance 3. Show examples from existing Warden skills when helpful 4. Cite sources (Anthropic docs, etc.) for best practices

Agentic Patterns

Patterns for building effective tool-using agents.

Tool Boundaries

Define clear tool access for safety:

allowedTools: ['Read', 'Grep'],
disallowedTools: ['Write', 'Edit', 'Bash', 'WebFetch', 'WebSearch'],

Document available tools in the system prompt so the agent knows its capabilities.

Investigation Before Reporting

From Anthropic's guidance:

ALWAYS read and understand relevant files before proposing code edits.

Do not speculate about code you have not inspected.

Encourage thorough analysis:

## Analysis Approach

1. **Understand intent**: What is the code trying to do?
2. **Trace data flow**: Follow variables from input to usage
3. **Consider edge cases**: Empty, null, zero, negative values?
4. **Check error paths**: Are failures handled correctly?
5. **Verify assumptions**: What might not be true?

Confidence Levels

Require explicit confidence:

"confidence" reflects certainty this is a real issue:
- **high**: Clear violation, no ambiguity
- **medium**: Likely issue, context might justify it
- **low**: Possible concern, needs human review

Handling Uncertainty

From OpenAI's agent guidelines:

Different tools should have different uncertainty thresholds.

For analysis:

Only report bugs you are confident are real. Do not speculate or
report "potential" issues. If you're unsure, don't report it.

Persistence for Agentic Tasks

From OpenAI's GPT-5 guide:

Keep going until the task is resolved before yielding back to the user.

For multi-step analysis, encourage completion:

Continue investigating until you have checked all relevant code paths.
Use Read and Grep to trace data flow through the codebase.

Subagent Isolation

From agentic best practices:

Each subagent should run in complete isolation. Every call should be

like a pure function - same input, same output, no shared state.

Warden achieves this by analyzing each hunk independently.

Context Management

For long-running tasks, from Anthropic's guidance:

Your context window will be automatically compacted. Do not stop tasks
early due to token budget concerns. Save progress before context refreshes.

Sources

• Anthropic: Claude 4.x Best Practices
• OpenAI: GPT-5 Prompting Guide
• Agentic AI Prompting Best Practices

Anti-Patterns

Common mistakes to avoid when writing prompts.

Over-Emphasis and Anchoring

From Anthropic's Opus 4.5 guidance:

Claude Opus 4.5 is more responsive to the system prompt than previous

models. Where you might have said "CRITICAL: You MUST...", you can

use more normal prompting.

From Vercel's AGENTS.md research:

Instructions stating "You MUST invoke the skill" caused agents to anchor

excessively on documentation patterns while missing project context.

Avoid:

CRITICAL: You MUST ALWAYS check for SQL injection. NEVER skip this.
IT IS ABSOLUTELY ESSENTIAL that you...

Prefer:

Understand the code's intent first, then check for SQL injection:
Is user input concatenated into queries instead of parameterized?

The key insight: "MUST" language causes anchoring on the instruction at the expense of contextual understanding.

Scope Creep

Each skill should do one thing well.

Avoid:

Find security issues, performance problems, and bugs too.

Prefer: Create separate skills for each concern.

Vague Severity

Avoid:

Use high severity for important issues and medium for less important ones.

Prefer:

- **critical**: Crash, data loss, or silent data corruption
- **high**: Incorrect behavior in common scenarios
- **medium**: Incorrect behavior in edge cases

Negative-Only Instructions

Avoid:

Do not output markdown.
Do not include explanations.
Do not wrap in code fences.

Prefer:

Return ONLY valid JSON starting with {"findings":

Missing Exclusions

Without explicit exclusions, skills report everything tangentially related.

Avoid: Omitting "What NOT to Report" section.

Prefer:

## What NOT to Report

- Security vulnerabilities (use security-review skill)
- Style or formatting issues
- Performance concerns (unless causing incorrect behavior)

Hallucination-Prone Patterns

From Anthropic's guidance:

Never speculate about code you have not opened.

Avoid: Asking for analysis without providing code context.

Prefer: Always include actual code in the prompt (Warden does this automatically).

Over-Engineering Output

From Anthropic's guidance:

Claude Opus 4.5 has a tendency to overengineer by creating extra files

or adding unnecessary abstractions.

For prompts, keep output requirements minimal:

Avoid:

Include a detailed analysis section, then a summary, then recommendations,
then a risk assessment matrix, then...

Prefer:

Return JSON with findings array. Keep descriptions to 1-2 sentences.

Conflicting Instructions

Avoid:

Be thorough and check everything.
...
Only report high-confidence issues.

Prefer: Consistent stance throughout the prompt.

Missing Examples

For complex output formats, include an example:

Avoid: Schema only without example.

Prefer:

Example response format:
{"findings": [{"id": "sql-injection-1", "severity": "high", ...}]}

Full schema:
...

Context Design

Research on how context delivery affects agent performance. Based on Vercel's AGENTS.md evaluation.

Key Finding: Passive Context Wins

Vercel's evaluation showed dramatic performance differences:

Why Passive Context Outperforms

Three structural advantages:

1. Eliminated Decision Burden

Information exists automatically rather than requiring agent judgment about when retrieval is necessary.

Implication for skills: Warden injects skill prompts directly into the system prompt. This is passive context - the agent doesn't need to decide to load the skill.

2. Persistent Availability

Documentation remains accessible throughout every conversation turn via system prompt.

Implication for skills: Keep skill prompts self-contained. Don't require the agent to fetch additional context to understand the task.

3. Avoided Sequencing Problems

No competing instructions about whether to explore first vs consult docs first.

Implication for skills: Be explicit about the analysis approach. Don't leave ordering ambiguous.

Instruction Wording Matters

Subtle wording differences produced dramatically divergent outcomes:

Recommendations

Avoid:

You MUST check for SQL injection on every code change.

Prefer:

Understand the code's intent first, then check for SQL injection:
Is user input concatenated into queries?

Retrieval-Led Reasoning

From Vercel's research:

"Prefer retrieval-led reasoning over pre-training-led reasoning"

This means: look at the actual code before applying general knowledge.

For Warden skills:

## Analysis Approach

1. Read the code context provided
2. Use Read/Grep to investigate related files if needed
3. Apply skill criteria to what you've observed
4. Only report issues you've verified in the code

Compression Works

Vercel reduced docs from 40KB to 8KB (80% reduction) with no loss in effectiveness.

Implication for skills:

• Concise prompts work as well as verbose ones
• Use structured formats (tables, lists) over prose
• Index references rather than including full content

Example - compressed reference:

### Injection Types
SQL|Command|Template|Header|XSS|Path traversal

vs verbose:

There are several types of injection vulnerabilities you should check for.
First, SQL injection occurs when... Second, command injection...

When Skills Add Value

Skills remain valuable for:

• User-triggered workflows (version upgrades, migrations)
• Explicit "apply this standard" requests
• Tasks requiring specific tool sequences

For general knowledge that should always apply, passive context wins.

Application to Warden

Warden's architecture aligns with these findings:

1. Passive injection - Skill prompts are injected into system prompt 2. Hunk context provided - Code is in the user prompt, not requiring retrieval 3. Read-only tools available - Agent can investigate but starts with context

To maximize effectiveness:

• Write self-contained skill prompts
• Include analysis approach (explore → apply criteria)
• Avoid "MUST" language that causes anchoring
• Keep prompts concise with structured references

Sources

• Vercel: AGENTS.md Outperforms Skills

Core Principles

Foundational rules for writing effective prompts. Derived from Anthropic's official documentation.

1. Be Explicit

Claude 4.x models respond well to clear, explicit instructions.

Less effective:

Review this code for issues.

More effective:

Analyze the code changes for security issues. Only report genuine
security concerns, not style issues.

2. Provide Context and Motivation

Explain why a behavior matters.

Less effective:

Never report style issues.

More effective:

Do not report style issues. This skill focuses on security vulnerabilities.
Style issues are handled by code-simplifier and would create noise here.

3. Be Vigilant with Examples

Claude pays close attention to examples. Ensure they demonstrate desired behaviors only.

4. Prefer Positive Instructions

Tell Claude what to do, not what to avoid.

Less effective:

Do not use markdown in your response.

More effective:

Return ONLY valid JSON starting with {"findings":

5. Scope Narrowly

Broad prompts decrease accuracy. Each skill should have one clear focus.

Less effective:

Find bugs, security issues, performance problems, and style violations.

More effective:

Identify functional bugs that cause incorrect behavior. Focus on null
handling, off-by-one errors, and async issues.

6. Match Prompt Style to Output

The formatting in your prompt influences Claude's response style. Remove markdown from prompts if you want less markdown in output.

Sources

• Anthropic: Claude 4.x Best Practices
• OpenAI: Prompt Engineering Guide

Model-Specific Guidance

Optimizations for Claude 4.x models (Sonnet 4.5, Opus 4.5).

Claude 4.x Strengths

Prompting Adjustments

Simpler Language

Claude 4.x doesn't need aggressive emphasis:

Before (older models):

CRITICAL: You MUST use this tool when...

After (Claude 4.x):

Use this tool when...

More Direct Communication

From Anthropic's guidance:

Claude 4.5 models have a more concise and natural communication style.

More direct and grounded, provides fact-based progress rather than

self-celebratory updates.

Explicit Thoroughness

Claude 4.x may be conservative. If you want thorough analysis:

Go beyond the basics to create a fully-featured analysis. Include
as many relevant findings as possible.

Thinking and Reflection

Claude 4.x supports thinking between tool calls:

After receiving tool results, carefully reflect on their quality and
determine optimal next steps before proceeding.

Interleaved Thinking

For complex multi-step analysis:

Use your thinking to plan and iterate based on new information,
then take the best next action.

Thinking Sensitivity

From Anthropic's guidance:

When extended thinking is disabled, Claude Opus 4.5 is particularly

sensitive to the word "think" and its variants.

If not using extended thinking, prefer alternatives:

• "consider" instead of "think about"
• "evaluate" instead of "think through"
• "reflect on" instead of "think over"

Tool Usage

Claude 4.x excels at parallel tool execution:

If you intend to call multiple tools and there are no dependencies,
make all independent calls in parallel.

Proactive vs Conservative

To make Claude more proactive:

By default, implement changes rather than only suggesting them.
Infer the most useful action and proceed.

To make Claude more conservative:

Do not take action unless clearly instructed. Default to providing
information and recommendations rather than making changes.

Code Exploration

From Anthropic's guidance:

Claude Opus 4.5 can be overly conservative when exploring code.

If needed, add explicit instructions:

ALWAYS read and understand relevant files before reporting issues.
Do not speculate about code you have not inspected.

Sources

• Anthropic: Claude 4.x Best Practices
• Anthropic: What's New in Claude 4.5

Output Formats

How to specify structured output for reliable parsing.

Enforce JSON-Only Output

Be explicit about format requirements:

IMPORTANT: Your response must be ONLY a valid JSON object.
No markdown, no explanation, no code fences.

Example response format:
{"findings": [{"id": "example-1", "severity": "medium", ...}]}

Provide Complete Schema

Include all available fields so Claude knows the full structure:

{
  "findings": [
    {
      "id": "unique-identifier",
      "severity": "critical|high|medium|low|info",
      "confidence": "high|medium|low",
      "title": "Short descriptive title",
      "description": "Detailed explanation",
      "location": {
        "path": "path/to/file.ts",
        "startLine": 10,
        "endLine": 15
      },
      "suggestedFix": {
        "description": "How to fix",
        "diff": "unified diff format"
      }
    }
  ]
}

Field Requirements

Document which fields are required vs optional:

Requirements:
- Return ONLY valid JSON starting with {"findings":
- "findings" array can be empty if no issues found
- "location.path" is auto-filled - just provide startLine (and optionally endLine). Omit location for general findings.
- "confidence" reflects certainty given codebase context
- "suggestedFix" is optional - only include when the fix is complete, correct, and applies to the same file being analyzed. If the fix requires changes to a different file, describe it in the description instead.

Set Length Expectations

Prevent verbose output:

Keep descriptions SHORT (1-2 sentences max)
Be concise - focus only on the changes shown

Empty Results

Explicitly allow empty arrays:

Return an empty findings array if no issues match the skill's criteria:
{"findings": []}

Warden's JSON Extraction

The runner handles common output issues (src/sdk/runner.ts):

• Strips markdown code fences if present
• Finds {"findings" pattern in prose
• Extracts balanced JSON with nested objects
• Validates against FindingSchema with Zod

This provides resilience, but clean JSON output is still preferred.

Severity Level Definitions

Severity reflects urgency and required action, not the type of issue. Each skill defines what "significant impact" means in its domain.

Avoid vague definitions like "important" or "less important."

Skill Structure

How to write effective Warden skill files.

File Format

Skills use YAML frontmatter + markdown body:

---
name: skill-name
description: Brief description for discovery and trigger matching.
allowed-tools: Read Grep Glob
---

[Prompt body - the actual instructions]

Required Frontmatter

Recommended Body Structure

[Role statement - who the agent is]

## Your Task

[Clear statement of what to analyze]

### [Category 1]

- Specific pattern to look for
- Guiding questions: "Is X happening? Does Y exist?"

### [Category 2]

...

## What NOT to Report

[Explicit exclusions prevent scope creep]

## Severity Levels

[Definitions tied to impact]

## Output Requirements

[Formatting expectations]

Effective Patterns

Guiding Questions

Help the agent know what to look for:

### Injection Vulnerabilities
- **SQL injection**: User input concatenated into queries instead of parameterized?
- **Command injection**: User input passed to shell/exec functions?

Explicit Exclusions

Prevent false positives and scope creep:

## What NOT to Report

- Security vulnerabilities (use security-review skill)
- Style or formatting issues
- Code that "could be better" but works correctly

Confidence Calibration

Set expectations for certainty:

Do NOT use low or info severity - if you're not confident it's a real
bug, don't report it.

Severity Tied to Impact

Avoid vague definitions:

- **critical**: Crash, data loss, or silent data corruption
- **high**: Incorrect behavior in common scenarios
- **medium**: Incorrect behavior in edge cases

File Locations

Skills are discovered in order (first match wins):

1. .agents/skills/{name}/SKILL.md - Primary (recommended) 2. .claude/skills/{name}/SKILL.md - Backup (Claude Code convention)

Examples

See existing skills in .agents/skills/ for reference patterns.

System Prompts

How Warden constructs system prompts and how to customize them.

Warden's Prompt Architecture

Warden builds a two-layer prompt for each analysis:

System Prompt (Built by Runner)

Constructed in src/sdk/runner.ts:

<role>
You are a code analysis agent for Warden...
</role>

<tools>
Available tools: Read, Grep
</tools>

<skill_instructions>
{skill.prompt injected here}
</skill_instructions>

<output_format>
JSON schema and requirements
</output_format>

<skill_resources>
Path to skill assets (if applicable)
</skill_resources>

User Prompt (Per-Hunk)

Each code change is analyzed with:

• Skill name being applied
• Formatted code context (before/after lines)
• The diff hunk
• Instruction to only report matching findings

XML Tags for Structure

Use XML tags to create clear sections:

<role>...</role>
<tools>...</tools>
<skill_instructions>...</skill_instructions>

Benefits:

• Clear boundaries between sections
• Model can reference sections by name
• Consistent parsing and validation

Role Definition

The role section establishes:

Example:

<role>
You are a code analysis agent for Warden. You evaluate code changes
against specific skill criteria and report findings ONLY when the code
violates or conflicts with those criteria.
</role>

Tool Documentation

Document available tools clearly:

<tools>
You have access to these tools to gather context:
- **Read**: Check related files to understand context
- **Grep**: Search for patterns to trace data flow
</tools>

Claude Agent SDK Options

From Anthropic's SDK documentation:

Note: The SDK's minimal default omits coding guidelines. Use preset: "claude_code" for full capabilities.

CLAUDE.md Integration

Project-level context via CLAUDE.md requires explicit configuration:

options: {
  systemPrompt: { preset: "claude_code" },
  settingSources: ["project"], // Required to load CLAUDE.md
}

Sources

• Anthropic: Modifying System Prompts
• src/sdk/runner.ts - Warden's implementation