# Capabilities Generic AI agents are impressive demos. Then you ask them to work with *your* codebase. They don't know your custom component library exists. They use `` - Your API conventions, naming patterns, or architectural decisions - The tribal knowledge your team repeats in every code review You re-explain the same context. Fix the same mistakes. The knowledge lives in your head, not in the agent. ### The Valdr difference Capabilities persist. When you encode "always use our CustomDropdown" as a capability and assign it to your TypeScript agent, that knowledge **survives every session**. The agent knows before you ask. | Without capabilities | With capabilities | |---------------------|-------------------| | Repeat context every session | Context is always present | | Inconsistent outputs across agents | Uniform adherence to standards | | Review catches avoidable mistakes | Mistakes prevented at generation | | Tribal knowledge lives in heads | Tribal knowledge lives in prompts | ### The compound effect Every capability you encode: - Saves time on every future session - Reduces review burden - Improves consistency - Captures knowledge that might otherwise be lost Over time, you build a **capability library** that makes agents genuinely productive—not just impressive demos. ## The capability layering model Capabilities are designed to stack. Start with a generic foundation, then add team-specific overlays that encode your institutional knowledge. ``` ┌─────────────────────────────────────────────┐ │ Team-specific capability │ │ "Always use custom-dropdown.tsx" │ │ "Follow our API naming conventions" │ ├─────────────────────────────────────────────┤ │ Domain capability │ │ "TypeScript best practices" │ │ "React component patterns" │ ├─────────────────────────────────────────────┤ │ Base capability │ │ "Code review standards" │ │ "Testing requirements" │ └─────────────────────────────────────────────┘ ``` Each layer adds specificity without replacing what's below. The agent inherits general best practices *and* your team's specific conventions. Capabilities are applied deterministically based on their keys. See **[Prompt Ordering](../../valdr-packs/prompt-ordering/)** to understand how capability keys control instruction order. ## Anatomy of a capability Every capability has three components: | Component | What it is | Example | |-----------|-----------|---------| | **Key** | Unique identifier | `typescript.testing` | | **Category** | Grouping label | `testing`, `operations`, `marketing` | | **Prompt Binding** | The actual instructions | Link to a prompt with detailed guidance | When you assign a capability to an agent, the agent receives the bound prompt as part of its system context. The instructions become part of who the agent is. > [!NOTE] > **Capabilities are not task instructions or one-off prompts.** They encode reusable behavior that should apply consistently across many tasks. Use task descriptions for specific work; use capabilities for institutional rules. ## Example: TypeScript testing capability Here's what a real capability looks like: ```markdown # Capability: typescript.testing You are the TypeScript testing specialist who designs high-signal unit, integration, and contract tests so code stays deterministic and regression-safe. ## Instructions - Target ≥90% coverage on new or modified modules - Use Vitest with deterministic data builders - Guard against regressions by reproducing bugs with tests before patching - Run tests before handoff and capture evidence in task comments ``` Assign this capability to your TypeScript agent, and it *always* follows these testing standards. No prompting required. ## What to encode in capabilities ### Codebase conventions - Component libraries and when to use each component - API patterns (REST conventions, error handling, pagination) - File/folder structure expectations - Naming conventions (variables, files, routes) ### Architectural decisions - State management patterns (Redux, Zustand, context usage) - Data fetching strategies (React Query, SWR, custom hooks) - Error boundary placement - Feature flag conventions ### Quality standards - Testing requirements specific to your stack - Accessibility standards beyond WCAG defaults - Performance budgets and optimization patterns - Security practices for your domain ### Tribal knowledge - "We tried X approach and it failed because Y" - "Always check Z before deploying to production" - "The legacy module requires special handling" - Undocumented but critical integration points ## Get started in 60 seconds {{% steps %}} ### Navigate to Capabilities Click **Capabilities** in the left sidebar. You'll see your capability registry with assignment counts. ### Browse by category Use the filter to find capabilities in a specific domain—`typescript`, `operations`, `marketing`, `audit`. ### Open a capability Click any row to see the full definition, prompt binding, and which agents have this capability assigned. ### Create a new capability Click **Add Capability** and provide a key, category, and prompt binding. Start with one high-frequency pain point. {{% /steps %}} ## Local-first storage Capabilities live in your local workspace. They persist across sessions and survive agent restarts—but they're stored on your machine, not in the cloud. You control your capability library. > [!TIP] > **Version your capabilities.** Store capability prompts in your repo (`.valdr/valdr-packs/`) and version them alongside your code. Changes go through PR review like any other code. ## Next steps {{< cards >}} {{< card link="capability-list/" title="Capability List" icon="table" >}} {{< card link="capability-detail/" title="Capability Detail" icon="document-text" >}} {{< card link="/valdr/docs/valdr-packs/team-capabilities/" title="Team Capabilities Guide" icon="book-open" >}} {{< /cards >}} **Start building your capability library today.** Audit your last 10 agent sessions—what context did you repeat? Pick one high-frequency pain point and encode it as a capability. That's how institutional knowledge becomes agent infrastructure.