Skip to main content
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: 
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: 
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: 
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

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

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

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

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