Skills

Skills are discrete capabilities that agents can invoke during conversations — like looking up a contact, generating a quote, or booking a calendar slot. They are the primary extension mechanism for the Komand platform.

Skill Definition

A skill is defined by a contract that declares its identity, schemas, and required permissions:

{
  "skillId": "crm-contact-lookup",
  "name": "CRM Contact Lookup",
  "description": "Search and retrieve contact information from the CRM",
  "version": "1.0.0",
  "publisherId": "komand-official",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search term" }
    },
    "required": ["query"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "contacts": { "type": "array" },
      "totalCount": { "type": "integer" }
    }
  },
  "requiredPermissions": [
    { "resource": "crm", "access": "read", "scope": null }
  ],
  "declaredToolAccess": ["database"],
  "isVerified": true,
  "signatureHash": "sha256:abc..."
}

Contract Fields

Field	Description
`skillId`	Unique identifier, lowercase with hyphens
`name`	Human-readable display name
`version`	Semantic version (`major.minor.patch`)
`publisherId`	Publisher who created the skill
`description`	What the skill does (shown to agents and users)
`inputSchema`	JSON Schema for accepted input
`outputSchema`	JSON Schema for returned output
`requiredPermissions`	Permissions the skill needs to function
`declaredToolAccess`	Platform tools the skill may invoke
`isVerified`	Whether the skill has passed marketplace review
`signatureHash`	Cryptographic signature for integrity verification

Registering a Skill

curl -X POST http://localhost:5000/api/skills/ \
  -H "Content-Type: application/json" \
  -d @skill-definition.json

The registry enforces a maximum of 10,000 registered skills.

Listing Skills

# All skills
curl "http://localhost:5000/api/skills/"

# Filter by publisher
curl "http://localhost:5000/api/skills/?publisherId=komand-official"

# Verified only
curl "http://localhost:5000/api/skills/?verifiedOnly=true"

Response:

{
  "success": true,
  "data": [
    {
      "skillId": "crm-contact-lookup",
      "name": "CRM Contact Lookup",
      "version": "1.0.0",
      "publisherId": "komand-official",
      "isVerified": true,
      "publishedAt": "2026-01-15T00:00:00Z"
    }
  ],
  "meta": null
}

Retrieving a Skill

curl http://localhost:5000/api/skills/crm-contact-lookup

Enabling Skills for an Agent

Skills are enabled per-agent via the agent’s enabledSkillIds configuration:

curl -X POST http://localhost:5000/api/agents/ \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "sales-bot",
    "name": "Sales Assistant",
    "enabledSkillIds": ["crm-contact-lookup", "quote-builder", "calendar-book"]
  }'

When the LLM decides to invoke a tool during a conversation, the agent checks:

Is the skill in the agent’s enabledSkillIds?
Are the agent’s granted permissions sufficient for the skill’s requiredPermissions?
If both pass, a ToolGrain is created to execute the skill in isolation

Permission Model

Permissions are granular, with three components:

{
  "resource": "crm",
  "access": "read",
  "scope": null
}

Component	Description	Examples
`resource`	What the permission applies to	`crm`, `network`, `filesystem`, `api:salesforce`
`access`	Type of access	`read`, `write`, `execute`
`scope`	Optional narrowing	Specific URLs, paths, or resource IDs

Permission Validation

When a skill is invoked, the platform validates that the agent’s granted permissions cover all of the skill’s required permissions. Validation matches on resource:access pairs — the scope field is defined in the model but not yet enforced:

Skill requires: [{ resource: "crm", access: "read" },
                  { resource: "calendar", access: "write" }]
Agent grants:   [{ resource: "crm", access: "read" },
                  { resource: "calendar", access: "write" },
                  { resource: "email", access: "send" }]
Result:         All required permissions covered

Skill requires: [{ resource: "crm", access: "read" },
                  { resource: "crm", access: "write" }]
Agent grants:   [{ resource: "crm", access: "read" }]
Result:         Missing crm:write — execution blocked

If validation fails, the execution is blocked and a PermissionDenied audit event is logged.

Sandboxed Execution

Skills will run in isolated environments. This is a core security guarantee — not an optional feature.

Isolation Model (Planned)

Constraint	Enforcement
File system	No access outside the skill’s temp directory
Network	No outbound access unless `network:outbound` is declared
CPU / memory	Hard limits enforced by the container or WASM runtime
Timeout	Executions exceeding their timeout are terminated (max 30 minutes)
Input validation	All inputs validated against the declared schema
Output sanitization	Skill outputs sanitised before being fed back to the LLM

Execution Environments (Planned)

Container sandbox — Docker containers with restricted capabilities, no host access
WASM runtime — WebAssembly modules for lightweight, portable isolation

Execution Lifecycle

When an agent invokes a skill:

AgentGrain receives LLM tool_call
         │
Validates skill exists in SkillRegistryGrain
         │
Validates permissions against agent's grants
         │
Creates ToolGrain with unique executionId
         │
ToolGrain.ExecuteAsync()
├── Status: Pending → Running
├── Executes with enforced timeout
├── Status: Running → Completed | Failed | TimedOut | Cancelled
└── Returns ToolExecutionResult
         │
AgentGrain feeds result back to LLM

Unregistering a Skill

curl -X DELETE http://localhost:5000/api/skills/crm-contact-lookup

Unregistering a skill removes it from the global registry. Agents that had the skill enabled will no longer be able to invoke it.

Building Skills

To build your own skills, see the SDK Overview and Skill Development guides.

Limits

Setting	Default	Description
Max registered skills	10,000	Global registry capacity
Max tool execution timeout	30 minutes	Per-execution limit