> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Capabilities & Governance

> Define agent capabilities and enforce governance policies

## Overview

Capabilities and governance resources define what agents can do and enforce rules around how they operate. These resources ensure agents have the right tools while maintaining security and compliance.

## Tool Sets (Skills)

Tool sets, also known as skills, define collections of tools and capabilities that agents can use. They package related functionality together for reusability.

**Tool sets include:**

* Tool definitions and schemas
* API integrations
* Custom functions
* MCP (Model Context Protocol) servers

**Common tool sets:**

* **Kubernetes**: kubectl commands, cluster operations
* **Cloud Providers**: AWS, GCP, Azure operations
* **DevOps**: CI/CD, monitoring, deployment tools
* **Communication**: Slack, email, notifications
* **Data**: SQL queries, data analysis, reporting

**Benefits:**

* **Reusability**: Define once, use across multiple agents
* **Versioning**: Manage tool versions and updates
* **Governance**: Control which tools are available to which agents
* **Testing**: Test tools independently before deployment

## Policies

Policies enforce governance rules using Open Policy Agent (OPA). They control:

* Which tools agents can use
* What resources agents can access
* What actions require approval
* Compliance and security rules

**Policy types:**

* **Permission policies**: Control access to tools and resources
* **Approval policies**: Require human approval for sensitive operations
* **Rate limiting policies**: Prevent abuse and control costs
* **Data policies**: Enforce data handling and privacy rules

## Policy Language

Policies are written in Rego (OPA's policy language):

```rego theme={null}
package kubiya.agent.permissions

# Allow agent to use kubectl
allow {
    input.agent.team == "devops"
    input.tool.name == "kubectl"
}

# Require approval for production deployments
requires_approval {
    input.tool.name == "kubectl"
    input.args.namespace == "production"
    input.command contains "apply"
}
```

## Common Patterns

### List Available Skill Definitions

```bash theme={null}
# Get all available skill types
GET /api/v1/skills/definitions

# Get specific skill definition
GET /api/v1/skills/definitions/{skill_type}

# Get skill variants/presets
GET /api/v1/skills/definitions/{skill_type}/variants
```

### Create a Skill

```bash theme={null}
POST /api/v1/skills
{
  "name": "kubernetes-ops",
  "type": "kubernetes",
  "configuration": {
    "cluster_url": "https://k8s.example.com",
    "namespace": "default"
  }
}
```

### Validate Skill Configuration

```bash theme={null}
POST /api/v1/skills/definitions/{skill_type}/validate
{
  "configuration": {
    "cluster_url": "https://k8s.example.com"
  }
}
```

### Associate Skills with Entities

```bash theme={null}
# Add skill to an agent
POST /api/v1/skills/associations/agents/{agent_id}/skills
{
  "skill_id": "skill-uuid"
}

# List agent's skills (with inheritance)
GET /api/v1/skills/associations/agents/{agent_id}/skills/resolved

# Add skill to a team
POST /api/v1/skills/associations/teams/{team_id}/skills
{
  "skill_id": "skill-uuid"
}
```

### Create a Policy

```bash theme={null}
POST /api/v1/policies
{
  "name": "production-deployment-approval",
  "description": "Require approval for production deployments",
  "policy_text": "package kubiya.agent.approval\n\nrequires_approval {\n  input.tool.name == \"kubectl\"\n  input.args.namespace == \"production\"\n}",
  "policy_type": "approval"
}
```

### Associate Policies

```bash theme={null}
# Create policy association
POST /api/v1/policies/associations
{
  "policy_id": "policy-uuid",
  "entity_type": "agent",
  "entity_id": "agent-uuid",
  "enabled": true,
  "priority": 100
}

# Get resolved policies for an entity (with inheritance)
GET /api/v1/policies/resolved/agents/{agent_id}

# Evaluate policies
POST /api/v1/policies/evaluate/agents/{agent_id}
{
  "input": {
    "tool": {"name": "kubectl"},
    "args": {"namespace": "production"}
  }
}
```

## Tool Discovery

Agents can discover available tools through:

* Tool set catalogs
* Dynamic tool loading
* MCP server discovery
* Integration-based tools

## Policy Evaluation

Policies are evaluated in real-time:

1. Agent requests to use a tool
2. System evaluates applicable policies
3. If allowed, tool executes
4. If approval required, creates approval request
5. If denied, returns error to agent

## Best Practices

### Tool Set Design

1. **Focused functionality**: Group related tools together
2. **Clear documentation**: Document each tool's purpose and parameters
3. **Versioning**: Use semantic versioning for tool sets
4. **Testing**: Test tools thoroughly before deployment

### Policy Management

1. **Least privilege**: Start with minimal permissions, add as needed
2. **Audit logging**: Log all policy evaluations
3. **Testing**: Test policies in development before production
4. **Documentation**: Document policy intent and scope
5. **Regular review**: Review and update policies regularly

### Security

1. **Input validation**: Validate all tool inputs
2. **Secrets management**: Never hardcode credentials in tools
3. **Rate limiting**: Prevent abuse through rate limits
4. **Monitoring**: Monitor tool usage for anomalies

## Next Steps

Explore the API endpoints for tool sets and policies to learn how to define capabilities and enforce governance rules.