Skill

A Skill is a bundle of files (documentation, reference material, scripts) that gets injected into an agent's filesystem at a declared path. Agent runtimes that watch a skills directory — such as OpenClaw — auto-discover and load the skill without any code changes or restarts.

Skills are created from a local directory and stored in Pai. The controller seeds the files into the agent container before it starts.

CLI usage

# Create a skill from a local directory
pai skill create harvest-api --from-dir ./harvest-api/

# Create in a specific namespace
pai skill create harvest-api --from-dir ./harvest-api/ --namespace benjy

# Update skill content
pai skill update harvest-api --from-dir ./harvest-api-v2/

# List skills
pai skill list

# List skills in a specific namespace
pai skill list --namespace benjy

# Inspect files in a skill
pai skill describe harvest-api

# Delete a skill
pai skill delete harvest-api

You never write Skill YAML by hand. The CLI packages the directory for you.

Platform skills

Pai ships pre-built platform skills (pdf-reader, csv-analyst, git-workflow, summarizer) that are available in all namespaces without pai skill create. See Platform skills for the full list.

Mounting a skill into an agent

Add spec.skills to your Agent:

apiVersion: pai.io/v1
kind: Agent
metadata:
  name: openclaw-amir
spec:
  type: service
  image: ghcr.io/openclaw/openclaw:latest
  models:
    - anthropic/claude-sonnet-4-6
  skills:
    - name: harvest-api
      mountPath: /home/node/.openclaw/workspace/skills
    - name: github-workflow
      mountPath: /home/node/.openclaw/workspace/skills

Each skill is placed at {mountPath}/{skill-name}/ inside the container. With the example above:

/home/node/.openclaw/workspace/skills/
├── harvest-api/
│   ├── SKILL.md
│   └── references/endpoints.md
└── github-workflow/
    └── SKILL.md

How it works

1. pai skill create reads all files from a local directory and stores them as a Skill resource in Pai.
2. When you attach the skill to an Agent, Pai writes the skill's files to the target directory inside the agent before the agent starts.
3. Agent runtimes that watch the skills directory (e.g. OpenClaw with skills.load.extraDirs) pick them up automatically — no restart needed after the initial mount.

Skill directory structure

A skill directory can contain any files — Markdown, scripts, JSON, or other formats. The structure is preserved as-is:

harvest-api/              ← this becomes {mountPath}/harvest-api/ in the agent
├── SKILL.md              ← primary instructions (for OpenClaw, Claude Code, etc.)
└── references/
    └── endpoints.md      ← supplementary reference material

One-time agent config (OpenClaw)

For OpenClaw to auto-discover the skills directory, add it to skills.load.extraDirs in openclaw.json once via configFiles:

spec:
  configFiles:
    - path: /home/node/.openclaw/openclaw.json
      content: |
        {
          "skills": {
            "load": {
              "extraDirs": [
                { "path": "/home/node/.openclaw/workspace/skills", "watch": true }
              ]
            }
          }
        }

After this one-time setup, any skill mounted at that path is loaded immediately — no further config changes needed.

Updating skills

Updating a skill requires restarting the agent so it picks up the new content on next start:

pai skill update harvest-api --from-dir ./harvest-api-v2/
pai restart openclaw-amir