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 token count using ~4 chars/token.
- 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 reference one or more prompts and define a skill boundary (e.g.,
typescript.testing.vitest). - Agents are assigned capabilities, which pull in the associated prompts automatically.
- At execution time, the agent’s full instruction set is assembled from its bound prompts — system prompts first, then guides, policies, checklists, and context in precedence order.
- Hot-loaded capabilities are not included in the initial instruction set. Instead, the agent’s system prompt contains instructions to load them on demand via
pm_capability { action: "prompt", key: "..." }when a specific situation arises. This keeps the base context lean and only pulls in detailed guidance (like scoring rubrics or severity classifications) at the moment it’s needed.
This composition model means you can update a single prompt and every agent that uses it picks up the change immediately — no manual propagation, no stale instructions, no drift between agents doing the same type of work. And with hot-loading, agents only consume context window for the capabilities they actually use during a run — so you can attach a deep library of skills without paying the token cost upfront.
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.