Tag System
The infrastructure that makes prompts auditable
Raw prompts are opaque. You can’t version them reliably, you can’t score agent behavior against them, and you can’t adapt them to different models without forking. Valdr’s tag system solves all three.
Tags are structured metadata embedded in prompts and charters. They’re invisible to the model but visible to tooling—enabling automated scoring, hash-based version tracking, and model-specific content selection.
The tag system is Valdr’s governance layer—it’s how agent behavior becomes inspectable, enforceable, and evolvable over time.
Tip
Tags turn “a folder of prompts” into governed infrastructure. This is how you answer: “How do we know the AI did what it was supposed to?”
Who this is for: This page is for pack authors and advanced users who want to understand how Valdr governs prompts. Most users will only touch a subset of these concepts—the Tag reference exists for completeness and tooling integration.
What tags enable
| Capability | Without tags | With tags |
|---|---|---|
| Scoring | Manual review of transcripts | Automated compliance scoring across seven dimensions |
| Versioning | File timestamps, hope for the best | Hash-based drift detection between environments |
| Model targeting | Fork prompts per model | Single pack, model-adaptive behavior |
| Traceability | “It’s somewhere in the prompt” | Link findings to exact sections with line numbers |
| Auditability | Trust the operator | Evidence-backed verdicts with root cause analysis |
Tag syntax
All tags are embedded in HTML comments—invisible to the model, parseable by tooling:
<!--<capability id="auditor.base" pack="valdr" role="core">-->
# Capability Prompt — `auditor.base`
<!--<identity>-->
You are the Agent Session Auditor.
<!--</identity>-->
<!--<instructions>-->
- Validate agent sessions across seven dimensions...
<!--</instructions>-->
<!--</capability>-->Tags support attributes like id, version, pack, role, and model for fine-grained control.
Capability roles
The role attribute classifies how a capability behaves in prompt composition. Valdr supports six roles, ordered by their position in the final prompt:
| Role | Priority | Purpose |
|---|---|---|
core | 0 | Foundational system-level behavior and identity |
workflow | 1 | Operational instructions and execution patterns |
constraints | 2 | Rules, policies, and behavioral boundaries |
context | 3 | Background information and domain knowledge |
validation | 4 | Verification steps and completion criteria |
integration | 5 | External system interfaces and API behaviors |
Capabilities are sorted by role priority first, then alphabetically within each role—ensuring predictable prompt composition.
Three layers of tags
1. Charter-level tags
Structure full agent definitions. Used in agents/*.md files.
charter,metadata,purpose— agent identity and missionworkflow,tooling,tool_policy— how the agent operatessuccess_conditions,definition_of_done— completion criteria
When you need this: Required when defining new agents. Every agent charter should use these tags.
2. Behavioral fragment tags
Define reusable prompt components. Used in agents/prompts/**/*.md.
identity,instructions— core behavioral contentcommunication_guidelines,execution_loop— operational patternssafety_and_data,tool_usage_policy— guardrails
When you need this: Optional, for reuse. Use these when you want to share behavioral patterns across multiple agents without copy-pasting.
3. Capability metadata tags
Bind content to registered capabilities for scoring and versioning.
capability— wrap prompt content for hash-based version trackingguideline,checklist— normative rules and required stepsprompt,prompt_fragment— top-level prompts and reusable chunks
When you need this: Required for scoring and versioning. If you want auditors to validate behavior or tooling to detect drift, wrap content in these tags.
Model-specific targeting
Different models need different instructions. Tags support model selectors so you can ship one pack that adapts to Claude, Ollama, GPT, or any other model.
<!--<instructions>-->
Base instructions for all models.
<model type="claude-*">
Use extended thinking for complex reasoning.
</model>
<model type="ollama-*">
Break complex tasks into explicit steps.
</model>
<!--</instructions>-->The business case: Start with Ollama locally, scale to Claude in production—same pack, no prompt rewrites.
Learn more
The Tag reference is the canonical list of all supported tags and attributes. If it’s not documented there, it’s not part of the system.