Platform skills

Pai ships a curated set of platform skills that are available in every namespace without running pai skill create. Reference them by name in any Agent — the controller resolves them automatically from the pai-system namespace.

Available platform skills

Skill	Description
pdf-reader	Extract text, metadata, and structure from PDF files
csv-analyst	Parse, analyze, and summarize CSV and tabular data using pandas
git-workflow	Common git operations — clone, branch, commit, push, and PR summaries
summarizer	Summarize long documents, files, web pages, and structured data

Using a platform skill

Reference platform skills exactly like custom skills — no extra configuration needed:

apiVersion: pai.io/v1
kind: Agent
metadata:
  name: research-agent
spec:
  models:
    - anthropic/claude-sonnet-4-6
  skills:
    - name: pdf-reader
      mountPath: /skills
    - name: summarizer
      mountPath: /skills
  packages:
    apt:
      - poppler-utils   # required by pdf-reader for pdftotext
  tools:
    - type: bash
    - type: read
    - type: write
    - type: web_fetch

Skills land at {mountPath}/{skill-name}/SKILL.md. The agent reads this file to understand what tools and patterns are available.

Example: PDF extraction with pdf-reader

This end-to-end example creates a task agent that reads a PDF from S3, extracts its text, and writes a structured summary to a file.

1. Create the Agent

apiVersion: pai.io/v1
kind: Agent
metadata:
  name: pdf-extractor
  namespace: my-team
spec:
  models:
    - anthropic/claude-sonnet-4-6
  skills:
    - name: pdf-reader
      mountPath: /skills
  packages:
    apt:
      - poppler-utils       # provides pdftotext and pdfinfo
    pip:
      - pypdf               # for structured/form data extraction
  tools:
    - type: bash
    - type: read
    - type: write
  system: |
    You are a PDF extraction agent. A PDF file will be provided to you at /workspace/input.pdf.

    Read /skills/pdf-reader/SKILL.md first to understand the available tools and patterns,
    then extract the document's content and write a structured summary to /workspace/summary.md.

    Your summary must include:
    - Document title and author (from metadata)
    - Total page count
    - A TL;DR of the document (2-3 sentences)
    - Key points as a bullet list
    - Any tables or structured data found, rendered as markdown tables

Apply it:

pai apply -f pdf-extractor.yaml

2. Run a task against a PDF

pai run extract-q1-report \
  --agent pdf-extractor \
  --task "Extract and summarize the PDF at /workspace/input.pdf. The file has already been placed there."

Or pass the file path directly in the task prompt if it's accessible via a mounted volume:

pai run extract-contract \
  --agent pdf-extractor \
  --task "Extract key clauses and obligations from /workspace/contracts/vendor-agreement.pdf"

3. Stream the output

pai sessions logs extract-q1-report --follow

You'll see the agent:

1. Read /skills/pdf-reader/SKILL.md to orient itself
2. Run pdfinfo to get page count and metadata
3. Run pdftotext to extract the full text
4. Write the structured summary to /workspace/summary.md

4. Retrieve the result

If the agent writes to a volume, retrieve the output:

pai cp extract-q1-report:/workspace/summary.md ./summary.md

Or add a write step to the system prompt to send the result via Telegram, email, or any other channel the agent has access to.

Full example with a PVC

For repeatable runs where you want to keep both the input PDFs and output summaries:

apiVersion: pai.io/v1
kind: Agent
metadata:
  name: extract-q1-report
  namespace: my-team
spec:
  type: task
  agentDefinition: pdf-extractor
  title: "Extract and summarize /workspace/pdfs/q1-report.pdf and save to /workspace/summaries/q1-report.md"
  volumes:
    - name: workspace
      mountPath: /workspace
      size: 2Gi

pai apply -f extract-q1-report.yaml
pai sessions logs extract-q1-report --follow

How resolution works

When the controller reconciles a workload or session and encounters a skill name in spec.skills:

1. It first looks for the Skill CRD in the workload's namespace
2. If not found, it falls back to the pai-system namespace
3. If still not found, the skill is skipped (with a warning in controller logs)

Custom skills in your namespace always take precedence over platform skills with the same name. This lets you override a platform skill with a customized version if needed.

Combining platform and custom skills

skills:
  - name: pdf-reader        # platform skill (resolved from pai-system)
    mountPath: /skills
  - name: my-company-style  # custom skill (in your namespace)
    mountPath: /skills
  - name: summarizer        # platform skill
    mountPath: /skills

Overriding a platform skill

To customize a platform skill, create a skill with the same name in your namespace:

# Copy the platform skill content locally
pai skill describe pdf-reader > ./pdf-reader/SKILL.md

# Edit to your needs, then create in your namespace
pai skill create pdf-reader --from-dir ./pdf-reader/

Your namespace's pdf-reader will now take precedence over the platform version.

For platform operators

Platform skills are stored as Skill CRDs in pai-system with the label pai.io/platform-skill: "true". They are deployed as part of the platform bootstrap:

# From the platform/ directory
kubectl apply -n pai-system -f config/skills/platform/

To add a new platform skill:

1. Create a directory under platform/config/skills/platform/<skill-name>/
2. Add a SKILL.md with instructions for the agent
3. Create a <skill-name>.skill.yaml Skill CRD manifest
4. Apply with kubectl apply -n pai-system -f config/skills/platform/<skill-name>.skill.yaml