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

# Skill Modules

> Build and deploy skill modules in Kodexa that package prompts, configurations, and knowledge for AI agents to discover and use at runtime.

Skill modules (`moduleType: skill`) are file packs that agents can discover and use. Unlike Python modules, skills are not executed — they are downloaded into the agent's container and made available as readable directories.

Skills are ideal for packaging:

* Prompt templates and system instructions
* Configuration files (tool definitions, workflows)
* Knowledge files and reference data

## Project Structure

A skill module is a directory of files with a `module.yml` definition:

```text theme={null}
my-llm-skills/
├── module.yml              # Module definition
├── prompts/
│   ├── system.md           # System prompt template
│   └── extraction.md       # Extraction instructions
├── tools/
│   └── search.yml          # Tool definitions
└── config.yml              # Skill configuration
```

## Module Definition (module.yml)

A skill module is defined like a Python module, but with `moduleType: skill` and no runtime reference:

```yaml theme={null}
name: My LLM Skills
slug: my-llm-skills
orgSlug: my-org
type: module
moduleType: skill
metadata:
  type: skill
  contents:
    - prompts/**
    - tools/**
    - config.yml
```

Key differences from Python modules:

* **moduleType** is set to `skill` (not `model`)
* No `moduleRuntimeRef` needed — skills are not executed
* **contents** patterns specify which files to include in the deployment ZIP

## How Agents Use Skills

When an agent session starts, the platform:

1. Resolves any skill module references assigned to the agent
2. Downloads the implementation ZIP for each skill
3. Extracts them to the agent's container at:

```
/home/kodexa/skills/{org_slug}/{module_slug}/
```

The agent's system prompt includes the list of available skill directories, so it can read and use the files as needed.

## Deploying a Skill

Deploy with the same `kdx apply` command used for Python modules:

```bash theme={null}
kdx apply -f module.yml
```

The CLI reads the `contents` patterns from the metadata, creates a ZIP of matching files, and uploads them as the module's implementation.

## Assigning Skills to Agents

Skills are assigned to agents through `moduleRefs` in the agent's workspace context. This is configured at the project level — when a workspace is created, its context includes the module references that the agent should load.

The agent runtime resolves each module reference, checks its `moduleType`, downloads the implementation ZIP, and extracts it to the skills directory.

## Example: Extraction Skill

Here's a complete example of a skill module that provides extraction prompts and configuration to an agent:

### module.yml

```yaml theme={null}
name: Invoice Extraction Skills
slug: invoice-extraction-skills
orgSlug: my-org
type: module
moduleType: skill
metadata:
  type: skill
  contents:
    - prompts/**
    - config.yml
```

### prompts/system.md

```markdown theme={null}
You are an invoice extraction agent. Your job is to extract structured data
from invoice documents.

Extract the following fields:
- Invoice number
- Invoice date
- Vendor name
- Line items (description, quantity, unit price, total)
- Subtotal, tax, and total amount
```

### prompts/extraction.md

```markdown theme={null}
Given the following document text, extract all invoice fields according to
the system instructions. Return the data as structured JSON.

Document text:
{document_text}
```

### config.yml

```yaml theme={null}
extraction:
  max_retries: 3
  confidence_threshold: 0.8
  output_format: json
fields:
  - name: invoice_number
    required: true
  - name: invoice_date
    required: true
  - name: vendor_name
    required: true
  - name: line_items
    required: false
    type: array
  - name: total
    required: true
```

## Best Practices

* **Keep skills focused**: Each skill module should serve a single purpose or domain
* **Use clear file organization**: Separate prompts, tools, and configuration into distinct directories
* **Version your skills**: Use semantic versioning in module.yml to track changes
* **Document your files**: Include comments or a README so agents (and humans) understand the skill's purpose
* **Use glob patterns wisely**: Only include files that the agent needs — avoid packaging unnecessary files


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.