Agent Skills

Give agents modular, reusable capabilities through SKILL.md files — load specialised knowledge on demand

Skills extend agents with specialised knowledge and instructions loaded on demand, keeping context lean until the skill is needed.

from praisonaiagents import Agent

agent = Agent(
    name="PDF Assistant",
    instructions="You are a helpful assistant.",
    skills=["./skills/pdf-processing"],
)
agent.start("Extract the main findings from report.pdf")

The user asks about a document; the agent loads the matching skill only when the task needs it.

Quick Start

1. Simple Usage

   Pass skill directory paths to skills:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="PDF Assistant",
       instructions="You are a helpful assistant.",
       skills=["./skills/pdf-processing"]
   )
   
   result = agent.start("Extract the main findings from report.pdf")

2. With Configuration

   Use SkillsConfig for auto-discovery from multiple directories:

   from praisonaiagents import Agent, SkillsConfig
   
   agent = Agent(
       name="Multi-Skill Agent",
       instructions="You are a versatile assistant.",
       skills=SkillsConfig(
           paths=["./skills/pdf-processing"],
           dirs=["./skills"],
           auto_discover=True,
       )
   )
   
   result = agent.start("Process the quarterly report")

How It Works

Skills use three levels of progressive disclosure:

SKILL.md Format

Each skill is a directory containing a SKILL.md file:

pdf-processing/
├── SKILL.md          # Required
├── scripts/          # Optional
├── references/       # Optional
└── assets/           # Optional

---
name: pdf-processing
description: Process and extract information from PDF documents. Use this skill when the user asks to read, analyze, or extract data from PDF files.
license: Apache-2.0
---

# PDF Processing Skill

## Instructions

1. Verify the PDF file exists
2. Read the PDF content
3. Extract text while preserving structure

Required Fields

Optional Fields

Configuration Options

The most common options at a glance:

Default Discovery Locations

Skills auto-discovered (in order of precedence):

1. ./.praisonai/skills/ or ./.claude/skills/
2. ~/.praisonai/skills/
3. ~/.praisonai/cache/remote-skills/*/current/ (populated by praisonai skills sync — see Remote Skill Sources)
4. /etc/praison/skills/

Common Patterns

Single Skill

from praisonaiagents import Agent

agent = Agent(
    name="Code Reviewer",
    instructions="You are a code review expert.",
    skills=["./skills/code-review"]
)

result = agent.start("Review this Python function for potential bugs")

Multiple Skills from Directory

from praisonaiagents import Agent

agent = Agent(
    name="Multi-Expert",
    instructions="You are an expert assistant.",
    skills=SkillsConfig(dirs=["./company-skills"])
)

result = agent.start("Summarize the latest sales data from report.pdf")

Creating a SKILL.md

praisonai skills create --name my-skill --description "My custom capability"

This creates the directory structure and template SKILL.md you can fill in.

Skills from Plugins

A plugin declared PluginType.SKILL that returns filesystem path strings from get_skills() has those paths appended to the Agent’s _skills. SkillManager then loads them as real SKILL.md sources — the same as user-configured skill dirs.

from praisonaiagents import Agent, Plugin, PluginInfo, PluginType
from praisonaiagents.plugins import get_plugin_manager

class PdfSkillPlugin(Plugin):
    @property
    def info(self):
        return PluginInfo(name="pdf_skill", plugin_type=PluginType.SKILL)
    def get_skills(self):
        return ["./skills/pdf-processing"]   # a dir containing SKILL.md

get_plugin_manager().register(PdfSkillPlugin())
get_plugin_manager().enable("pdf_skill")

agent = Agent(name="PDF Assistant", instructions="You are a helpful assistant.")
# ./skills/pdf-processing is now on agent._skills — no skills= parameter needed.
agent.start("Extract the main findings from report.pdf")

On Agent.__init__, _merge_plugin_subsystems() calls PluginManager.get_all_skills() and appends each string path to self._skills:

Rules

• Entries must be string paths to skill directories (each containing SKILL.md). Non-string entries (e.g. objects) are logged and skipped — SkillManager.add_skill(path) resolves each entry via Path(...).
• Duplicate paths are de-duplicated on merge (the append checks if skill not in current).

See Typed Plugins (Guardrail / Policy / Skill) for the full plugin-side reference.

Best Practices

Group Skills into Bundles

Bundle multiple skills into a named set and select them with a single @name selector.

from praisonaiagents import Agent

agent = Agent(
    name="Backend Dev",
    instructions="Help with backend engineering tasks.",
    skills=["@backend-dev"],
)
agent.start("Refactor the users table migration.")

Create a bundles/backend-dev.yaml in your skills directory to define the bundle:

name: backend-dev
description: Everything a backend engineer needs
skills:
  - pdf-processing
  - sql-runner
  - repo-search

See Skill Bundles for the full guide.

Related