Prompts
Prompts are the building blocks of agent behavior. Every agent in Valdr runs on prompts — from system-level identity definitions to workflow guides, policy constraints, and contextual knowledge. The Prompts screen is where you browse, create, and refine the instruction library that shapes how your agents think and act.
Instead of scattering prompt fragments across markdown files, config repos, or chat histories, Valdr gives you a single, searchable catalog with role classification, token sizing, and usage tracking. Write a prompt once, bind it to agents through capabilities, and see exactly where it’s used.
Prompt list
The prompt list is a filterable, paginated catalog of every prompt in your workspace.
Role filter bar
Five role buttons span the top, each showing a count:
| Role | Purpose |
|---|---|
| System | Agent identity and core behavior. Defines who the agent is and how it operates. Every agent needs at least one. |
| Guide | Step-by-step workflows and procedures. Loaded when an agent needs to follow a specific process. |
| Checklist | Validation criteria and acceptance gates. Used during reviews and quality checks. |
| Policy | Hard constraints and guardrails. Enforced rules that agents must follow — build standards, security policies, coding conventions. |
| Context | Reference material and domain knowledge. Background information agents can hot-load on demand. |
Click a role button to filter the table to that role. Click again to clear the filter.
Table columns
| Column | What it shows |
|---|---|
| Name | Display name and key (the stable identifier used in bindings and lookups). Click to open the detail view. |
| Role | The prompt’s role classification. |
| Usage | How many agents use this prompt — either directly or through capability bindings. |
| Content | A preview of the first line of markdown content. Useful for scanning without opening each prompt. |
| Tags | Metadata tags for organization and search. |
Search and pagination
The filter box searches across prompt names, keys, roles, and tags. Results update as you type.
Pagination controls at the bottom let you choose 10, 25, or 50 rows per page, with page navigation.
Prompt detail
Click any prompt to open its detail view. The layout splits into two areas: rendered content on the left, and metadata on the right.
Markdown content
The main area renders the full prompt body as formatted markdown. Click Edit to open the inline editor and modify the content directly.
Prompts use structured comment tags (<!--<identity>-->, <!--<instructions>-->) to delineate sections. These tags help the system identify prompt boundaries when assembling the final instruction set for an agent.
Metadata sidebar
The right sidebar surfaces key attributes at a glance:
Prompt ID and Key — The unique identifier and stable key used for lookups and bindings. The key is editable (double-click).
Role — The prompt’s role classification (System, Guide, Checklist, Policy, Context). Change it from the dropdown.
Tags — Metadata tags for categorization. Double-click to add or edit tags.
Prompt Size — Token and character counts help you understand the context window impact of each prompt:
- Tokens (estimated) — approximate input size to help you compare prompts.
- Characters — exact character count.
- KB — file size in UTF-8 bytes.
Usage — Shows exactly where this prompt is used:
- Capability definitions — how many capabilities reference this prompt.
- Agents (direct) — agents bound to this prompt directly.
- Agents (via capability) — agents that inherit this prompt through a capability binding.
Danger zone
At the bottom of the sidebar, the delete action shows exactly what will be affected — how many agent bindings will be removed and how many capability references will be cleared. This impact summary prevents accidental deletions that could break agent configurations.
Creating a prompt
Click Add Prompt from the list view to open the creation form.
Step 1 — Set name and key
Enter a display Name and a stable Key. The key is the identifier used in capability bindings and agent lookups — choose something descriptive and consistent with your naming convention (e.g., valdr-executor-workflow-blocker).
Step 2 — Select a role
Choose the prompt’s role from the dropdown: System, Guide, Checklist, Policy, or Context. This determines where the prompt appears in role-filtered views and how it’s assembled into agent instructions.
Step 3 — Add tags
Optional comma-separated tags for organization. Tags are searchable from the list view.
Step 4 — Write the markdown body
The editor supports full markdown with a Source and Preview toggle. Write your prompt content in source mode, then switch to preview to verify formatting. A character counter (up to 20,000) tracks content length.
Step 5 — Create
Click Create Prompt to save. The prompt is immediately available for binding to capabilities and agents.
How prompts flow to agents
Understanding the prompt-to-agent pipeline is key to getting the most out of Valdr’s instruction system:
- Prompts are standalone markdown documents with a role, key, and content.
- Capabilities can reference a backing prompt and define a skill boundary (e.g.,
typescript.testing.vitest). - Agents use the prompts and capabilities you assign to them.
- The agent starts with Agent System Charter, Guidance, Capability Playbooks, and Checklists, in that order. See Prompt ordering when you need to control the order of capability instructions.
- Hot-loaded capabilities are fetched when needed. Include instructions that tell the agent when to load them, for example with
pm_capability { action: "prompt", key: "..." }. This keeps detailed rubrics and specialist guidance available without adding them to every starting prompt.
Updated prompts are used by new sessions and when an agent next fetches that prompt. Instructions already sent to an active session stay unchanged. Inspect System Prompt Preview before a new launch to check the content.
Next steps
- Use Capabilities to bundle prompts into reusable skills and bind them to agents.
- See Agents to configure which capabilities (and therefore which prompts) each agent runs.
- Learn about Prompt ordering to understand how role precedence determines the final instruction assembly.