Team capabilities
{"content":"### Generic agents don't know your system\n\nOut-of-the-box agents are impressive—until you need them to work with *your* codebase. They don't know:\n\n- Your custom component library exists\n- That all dropdowns should use `custom-dropdown.tsx`, not native `\u003cselect\u003e`\n- Your API conventions, naming patterns, or architectural decisions\n- The tribal knowledge your team repeats in every code review\n\nWithout this context, agents produce technically correct but organizationally wrong outputs. You end up re-prompting the same instructions repeatedly—or worse, fixing the same mistakes in review.\n\n\u003e [!TIP]\n\u003e Team capabilities encode what your team already knows into prompts that agents always follow. No more \"remember to use our custom dropdown\" in every conversation.\n\n**Who this is for:** Teams with established codebases, internal libraries, or domain-specific conventions. Solo developers building personal productivity packs. Anyone tired of repeating context to AI.\n\n---\n\n## The capability layering model\n\nValdr capabilities are designed to stack. Start with a generic foundation, then add team-specific overlays that encode your institutional knowledge.\n\n```\n┌─────────────────────────────────────────────┐\n│ Team-specific capability │\n│ \"Always use custom-dropdown.tsx\" │\n│ \"Follow our API naming conventions\" │\n├─────────────────────────────────────────────┤\n│ Domain capability │\n│ \"TypeScript best practices\" │\n│ \"React component patterns\" │\n├─────────────────────────────────────────────┤\n│ Base capability │\n│ \"Code review standards\" │\n│ \"Testing requirements\" │\n└─────────────────────────────────────────────┘\n```\n\nEach layer adds specificity without replacing what's below. The agent inherits general best practices *and* your team's specific conventions.\n\n### Pack naming conventions\n\nThe `pack` attribute groups related capabilities together. Valdr uses these conventions:\n\n| Pack | Use for | Examples |\n| --- | --- | --- |\n| `valdr` | Valdr-provided capabilities and general-purpose prompts | `typescript.core`, `review.code` |\n| `{team}` | Team-specific capabilities | `acme.ui.components`, `mycompany.api` |\n| `{domain}` | Domain-specific packs you maintain | `healthcare.hipaa`, `fintech.compliance` |\n\n**Default pack:** Use `pack=\"valdr\"` for capabilities that follow Valdr's standard patterns and could be reused across projects. Use your team or domain name for capabilities encoding organization-specific knowledge.\n\n\u003e [!TIP]\n\u003e Pack names are normalized to lowercase. `pack=\"Valdr\"` and `pack=\"VALDR\"` both resolve to `valdr`.\n\n---\n\n## Example: TypeScript agent with UI specialization\n\n### The problem\n\nYou have a TypeScript codebase with a custom component library. Every time you ask an agent to build UI, it:\n\n- Uses native HTML elements instead of your components\n- Ignores your design tokens\n- Creates inconsistent patterns across the codebase\n\nYou keep saying \"use our CustomDropdown\" but it doesn't stick across sessions.\n\n### The solution: capability layering\n\n**Base agent:** Generic TypeScript capabilities\n\n```markdown\n\u003c!--\u003ccapability id=\"typescript.core\" pack=\"valdr\" role=\"core\"\u003e--\u003e\n# TypeScript Core\n\n- Use strict TypeScript with explicit return types\n- Prefer composition over inheritance\n- Follow ESLint rules defined in the repo\n\u003c!--\u003c/capability\u003e--\u003e\n```\n\n**Team overlay:** UI component conventions\n\n```markdown\n\u003c!--\u003ccapability id=\"acme.ui.components\" pack=\"acme\" role=\"context\"\u003e--\u003e\n# ACME UI Component Standards\n\n## Required components\nAlways use our custom components instead of native HTML or third-party libraries:\n\n| Instead of | Use |\n| --- | --- |\n| `\u003cselect\u003e` | `CustomDropdown` from `@acme/ui/custom-dropdown` |\n| `\u003cinput type=\"text\"\u003e` | `TextInput` from `@acme/ui/text-input` |\n| `\u003cbutton\u003e` | `Button` from `@acme/ui/button` |\n| `\u003cdialog\u003e` | `Modal` from `@acme/ui/modal` |\n\n## Design tokens\n- Colors: import from `@acme/tokens/colors`\n- Spacing: use `spacing.sm`, `spacing.md`, `spacing.lg`\n- Typography: use `Text` component with `variant` prop\n\n## Component patterns\n- All form fields must use `FormField` wrapper for consistent labels/errors\n- Modals must include `aria-labelledby` pointing to the title\n- Loading states use `Skeleton` component, not spinners\n\u003c!--\u003c/capability\u003e--\u003e\n```\n\n### The result\n\nWhen you bind both capabilities to your TypeScript agent:\n\n```yaml\ncapabilities:\n - typescript.core # Generic foundation\n - acme.ui.components # Team-specific overlay\n```\n\nThe agent now *always* knows to use `CustomDropdown`. No repeated prompting. No review corrections. The institutional knowledge is baked in.\n\n---\n\n## What to encode in team capabilities\n\n### Codebase conventions\n\n- Component libraries and when to use each component\n- API patterns (REST conventions, error handling, pagination)\n- File/folder structure expectations\n- Naming conventions (variables, files, routes)\n\n### Architectural decisions\n\n- State management patterns (Redux, Zustand, context usage)\n- Data fetching strategies (React Query, SWR, custom hooks)\n- Error boundary placement\n- Feature flag conventions\n\n### Quality standards\n\n- Testing requirements specific to your stack\n- Accessibility standards beyond WCAG defaults\n- Performance budgets and optimization patterns\n- Security practices for your domain\n\n### Tribal knowledge\n\n- \"We tried X approach and it failed because Y\"\n- \"Always check Z before deploying to production\"\n- \"The legacy module requires special handling\"\n- Undocumented but critical integration points\n\n---\n\n## Capability examples by team type\n\n### Frontend team\n\n```markdown\n\u003c!--\u003ccapability id=\"acme.frontend.react\" pack=\"acme\" role=\"context\"\u003e--\u003e\n# ACME React Conventions\n\n## State management\n- Global state: Zustand stores in `src/stores/`\n- Server state: React Query with custom hooks in `src/hooks/queries/`\n- Form state: React Hook Form with Zod validation\n\n## Component structure\n- Colocate styles with components using CSS modules\n- Props interfaces exported from component file\n- Storybook stories required for all shared components\n\n## Testing\n- Unit tests for hooks and utilities\n- Integration tests for user flows using Testing Library\n- E2E critical paths in Playwright\n\u003c!--\u003c/capability\u003e--\u003e\n```\n\n### Backend team\n\n```markdown\n\u003c!--\u003ccapability id=\"acme.backend.api\" pack=\"acme\" role=\"context\"\u003e--\u003e\n# ACME API Conventions\n\n## Endpoint patterns\n- RESTful routes: `/api/v1/{resource}/{id}`\n- List endpoints return `{ data: [], meta: { total, page, limit } }`\n- Errors return `{ error: { code, message, details } }`\n\n## Database access\n- All queries through repository pattern\n- Use transactions for multi-table writes\n- Soft deletes with `deleted_at` timestamp\n\n## Authentication\n- JWT validation middleware on all `/api/` routes\n- Rate limiting: 100 req/min for authenticated, 20 for anonymous\n- Audit logging for all write operations\n\u003c!--\u003c/capability\u003e--\u003e\n```\n\n### Platform/DevOps team\n\n```markdown\n\u003c!--\u003ccapability id=\"acme.platform.infra\" pack=\"acme\" role=\"context\"\u003e--\u003e\n# ACME Infrastructure Conventions\n\n## Deployment\n- All services deploy via GitHub Actions\n- Staging auto-deploys on merge to `main`\n- Production requires manual approval + tag\n\n## Observability\n- Structured logging with correlation IDs\n- Metrics exposed on `/metrics` for Prometheus\n- Distributed tracing with OpenTelemetry\n\n## Secrets\n- Never hardcode secrets; use environment variables\n- Secrets stored in AWS Secrets Manager\n- Rotate credentials quarterly\n\u003c!--\u003c/capability\u003e--\u003e\n```\n\n---\n\n## Building your first team capability\n\n### 1. Identify repeated instructions\n\nStart with pain points:\n- What do you keep telling the AI?\n- What mistakes do reviewers catch repeatedly?\n- What context does every new team member need?\n\n### 2. Write the capability prompt\n\nKeep it focused. One capability = one domain. Use tables for quick reference, prose for nuance. Don't try to encode everything at once—capabilities work best when they capture high-frequency, high-impact rules.\n\n```markdown\n\u003c!--\u003ccapability id=\"yourteam.domain.focus\" pack=\"yourteam\" role=\"context\"\u003e--\u003e\n# Your Team Domain Focus\n\n## Quick reference\n| Rule | Implementation |\n| --- | --- |\n| ... | ... |\n\n## Detailed guidance\n...\n\u003c!--\u003c/capability\u003e--\u003e\n```\n\n### 3. Register and bind\n\nRegister the capability in PM MCP, then bind it to relevant agents:\n\n```yaml\n# Agent charter binds capabilities\ncapabilities:\n - typescript.core # Generic\n - review.code # Generic\n - yourteam.domain.focus # Team-specific\n```\n\n### 4. Iterate based on results\n\nAfter a few sessions:\n- Did the agent follow the new rules?\n- Were there edge cases you didn't cover?\n- Does the capability need to be split or combined?\n\nCapabilities evolve with your team's knowledge.\n\n---\n\n## Why this matters\n\n| Without team capabilities | With team capabilities |\n| --- | --- |\n| Repeat context every session | Context is always present |\n| Inconsistent outputs across agents | Uniform adherence to standards |\n| Review catches avoidable mistakes | Mistakes prevented at generation |\n| New team members need onboarding | Knowledge is encoded and enforced |\n| Tribal knowledge lives in heads | Tribal knowledge lives in prompts |\n\n### The compound effect\n\nEvery capability you encode:\n- Saves time on every future session\n- Reduces review burden\n- Improves consistency\n- Captures knowledge that might otherwise be lost\n\nOver time, your team builds a **capability library** that makes agents genuinely productive—not just impressive demos.\n\n### Verified, not just declared\n\nWhen team capabilities use [structured tags](../tag-system/), Valdr's [scoring system](../tag-system/scoring/) can verify that agents actually followed your conventions. You don't just *hope* the agent used your custom dropdown—you can *prove* it did.\n\n---\n\n## Sharing and evolving capabilities\n\n### Within your team\n\n- Store capabilities in your repo (`agents/prompts/team/`)\n- Version alongside code\n- Review changes like any other PR\n\n### Across teams\n\n- Extract common patterns into shared packs\n- Publish to internal capability registry\n- Let other teams benefit from your knowledge\n\n### Contributing to the community\n\nWhen you've battle-tested a capability:\n- Generalize team-specific details\n- Contribute to the open-source Valdr Packs repository\n- Help others skip the learning curve you already climbed\n\n---\n\n## Getting started\n\n1. **Audit your last 10 agent sessions** — what context did you repeat?\n2. **Pick one high-frequency pain point** — start small\n3. **Write a focused capability** — 50-200 words is often enough\n4. **Bind it to your agent and test** — does behavior improve?\n5. **Iterate and expand** — build your capability library over time\n\nThe goal isn't to encode everything on day one. It's to capture knowledge incrementally, turning your team's expertise into agent infrastructure.\n\nThe goal isn't to make agents smarter—it's to make them *aligned* with how you already work.\n\n## Product view\n\nRead [Team Capabilities for AI Agents](/valdr/docs/features/team-capabilities/) for the platform-level positioning behind this feature.","description":"Build agents that know your codebase, conventions, and institutional knowledge.","title":"Team capabilities"}
Generic agents don’t know your system
Out-of-the-box agents are impressive—until you need them to work with your codebase. They don’t know:
- Your custom component library exists
- That all dropdowns should use
custom-dropdown.tsx, not native<select> - Your API conventions, naming patterns, or architectural decisions
- The tribal knowledge your team repeats in every code review
Without this context, agents produce technically correct but organizationally wrong outputs. You end up re-prompting the same instructions repeatedly—or worse, fixing the same mistakes in review.
Tip
Team capabilities encode what your team already knows into prompts that agents always follow. No more “remember to use our custom dropdown” in every conversation.
Who this is for: Teams with established codebases, internal libraries, or domain-specific conventions. Solo developers building personal productivity packs. Anyone tired of repeating context to AI.
The capability layering model
Valdr 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.
Pack naming conventions
The pack attribute groups related capabilities together. Valdr uses these conventions:
| Pack | Use for | Examples |
|---|---|---|
valdr | Valdr-provided capabilities and general-purpose prompts | typescript.core, review.code |
{team} | Team-specific capabilities | acme.ui.components, mycompany.api |
{domain} | Domain-specific packs you maintain | healthcare.hipaa, fintech.compliance |
Default pack: Use pack="valdr" for capabilities that follow Valdr’s standard patterns and could be reused across projects. Use your team or domain name for capabilities encoding organization-specific knowledge.
Tip
Pack names are normalized to lowercase. pack="Valdr" and pack="VALDR" both resolve to valdr.
Example: TypeScript agent with UI specialization
The problem
You have a TypeScript codebase with a custom component library. Every time you ask an agent to build UI, it:
- Uses native HTML elements instead of your components
- Ignores your design tokens
- Creates inconsistent patterns across the codebase
You keep saying “use our CustomDropdown” but it doesn’t stick across sessions.
The solution: capability layering
Base agent: Generic TypeScript capabilities
<!--<capability id="typescript.core" pack="valdr" role="core">-->
# TypeScript Core
- Use strict TypeScript with explicit return types
- Prefer composition over inheritance
- Follow ESLint rules defined in the repo
<!--</capability>-->Team overlay: UI component conventions
<!--<capability id="acme.ui.components" pack="acme" role="context">-->
# ACME UI Component Standards
## Required components
Always use our custom components instead of native HTML or third-party libraries:
| Instead of | Use |
| --- | --- |
| `<select>` | `CustomDropdown` from `@acme/ui/custom-dropdown` |
| `<input type="text">` | `TextInput` from `@acme/ui/text-input` |
| `<button>` | `Button` from `@acme/ui/button` |
| `<dialog>` | `Modal` from `@acme/ui/modal` |
## Design tokens
- Colors: import from `@acme/tokens/colors`
- Spacing: use `spacing.sm`, `spacing.md`, `spacing.lg`
- Typography: use `Text` component with `variant` prop
## Component patterns
- All form fields must use `FormField` wrapper for consistent labels/errors
- Modals must include `aria-labelledby` pointing to the title
- Loading states use `Skeleton` component, not spinners
<!--</capability>-->The result
When you bind both capabilities to your TypeScript agent:
capabilities:
- typescript.core # Generic foundation
- acme.ui.components # Team-specific overlayThe agent now always knows to use CustomDropdown. No repeated prompting. No review corrections. The institutional knowledge is baked in.
What to encode in team 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
Capability examples by team type
Frontend team
<!--<capability id="acme.frontend.react" pack="acme" role="context">-->
# ACME React Conventions
## State management
- Global state: Zustand stores in `src/stores/`
- Server state: React Query with custom hooks in `src/hooks/queries/`
- Form state: React Hook Form with Zod validation
## Component structure
- Colocate styles with components using CSS modules
- Props interfaces exported from component file
- Storybook stories required for all shared components
## Testing
- Unit tests for hooks and utilities
- Integration tests for user flows using Testing Library
- E2E critical paths in Playwright
<!--</capability>-->Backend team
<!--<capability id="acme.backend.api" pack="acme" role="context">-->
# ACME API Conventions
## Endpoint patterns
- RESTful routes: `/api/v1/{resource}/{id}`
- List endpoints return `{ data: [], meta: { total, page, limit } }`
- Errors return `{ error: { code, message, details } }`
## Database access
- All queries through repository pattern
- Use transactions for multi-table writes
- Soft deletes with `deleted_at` timestamp
## Authentication
- JWT validation middleware on all `/api/` routes
- Rate limiting: 100 req/min for authenticated, 20 for anonymous
- Audit logging for all write operations
<!--</capability>-->Platform/DevOps team
<!--<capability id="acme.platform.infra" pack="acme" role="context">-->
# ACME Infrastructure Conventions
## Deployment
- All services deploy via GitHub Actions
- Staging auto-deploys on merge to `main`
- Production requires manual approval + tag
## Observability
- Structured logging with correlation IDs
- Metrics exposed on `/metrics` for Prometheus
- Distributed tracing with OpenTelemetry
## Secrets
- Never hardcode secrets; use environment variables
- Secrets stored in AWS Secrets Manager
- Rotate credentials quarterly
<!--</capability>-->Building your first team capability
1. Identify repeated instructions
Start with pain points:
- What do you keep telling the AI?
- What mistakes do reviewers catch repeatedly?
- What context does every new team member need?
2. Write the capability prompt
Keep it focused. One capability = one domain. Use tables for quick reference, prose for nuance. Don’t try to encode everything at once—capabilities work best when they capture high-frequency, high-impact rules.
<!--<capability id="yourteam.domain.focus" pack="yourteam" role="context">-->
# Your Team Domain Focus
## Quick reference
| Rule | Implementation |
| --- | --- |
| ... | ... |
## Detailed guidance
...
<!--</capability>-->3. Register and bind
Register the capability in PM MCP, then bind it to relevant agents:
# Agent charter binds capabilities
capabilities:
- typescript.core # Generic
- review.code # Generic
- yourteam.domain.focus # Team-specific4. Iterate based on results
After a few sessions:
- Did the agent follow the new rules?
- Were there edge cases you didn’t cover?
- Does the capability need to be split or combined?
Capabilities evolve with your team’s knowledge.
Why this matters
| Without team capabilities | With team 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 |
| New team members need onboarding | Knowledge is encoded and enforced |
| 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, your team builds a capability library that makes agents genuinely productive—not just impressive demos.
Verified, not just declared
When team capabilities use structured tags, Valdr’s scoring system can verify that agents actually followed your conventions. You don’t just hope the agent used your custom dropdown—you can prove it did.
Sharing and evolving capabilities
Within your team
- Store capabilities in your repo (
agents/prompts/team/) - Version alongside code
- Review changes like any other PR
Across teams
- Extract common patterns into shared packs
- Publish to internal capability registry
- Let other teams benefit from your knowledge
Contributing to the community
When you’ve battle-tested a capability:
- Generalize team-specific details
- Contribute to the open-source Valdr Packs repository
- Help others skip the learning curve you already climbed
Getting started
- Audit your last 10 agent sessions — what context did you repeat?
- Pick one high-frequency pain point — start small
- Write a focused capability — 50-200 words is often enough
- Bind it to your agent and test — does behavior improve?
- Iterate and expand — build your capability library over time
The goal isn’t to encode everything on day one. It’s to capture knowledge incrementally, turning your team’s expertise into agent infrastructure.
The goal isn’t to make agents smarter—it’s to make them aligned with how you already work.
Product view
Read Team Capabilities for AI Agents for the platform-level positioning behind this feature.