Agent Skills - PraisonAI

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.

Agent-created skills are staged for approval by default. When an agent calls skill_manage to create, edit, or delete a skill, the mutation is held in a pending store until a human approves it — disk is not touched. Reading and using existing skills is unaffected. See Skill Manage for the full approval gate docs.

Want to group several skills under one name? See Skill Bundles — a single @bundle selector expands to a full set of skills.

Want to generate a skill from your own repo or docs? See Learn a Skill from Sources — one command turns code/docs/PDFs into a grounded SKILL.md.

Graceful fallback for missing tools? Use fallback_for_tools in a skill’s frontmatter to offer the skill only when a real tool is absent. See Skill Fallback.

Quick Start

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")

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:

Level	What Loads	Tokens
1 — Metadata	Name + description (at startup)	~100
2 — Instructions	Full `SKILL.md` body (when activated)	under 5,000
3 — Resources	Scripts, references, assets (on demand)	Variable

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

Field	Constraints
`name`	1–64 chars, lowercase, hyphens only, matches directory name
`description`	1–1024 chars — tells the agent when to use this skill

Optional Fields

Field	Description
`license`	License identifier (e.g., `Apache-2.0`, `MIT`)
`compatibility`	Compatibility notes (max 500 chars)
`metadata`	Key-value map for custom properties
`allowed-tools`	Space-delimited list of tools the skill requires

Configuration Options

SkillsConfig SDK Reference

Full parameter reference for SkillsConfig

The most common options at a glance:

Option	Type	Default	Description
`paths`	`List[str]`	`[]`	Direct skill directory paths to load
`dirs`	`List[str]`	`[]`	Directories to scan for skill subdirectories
`auto_discover`	`bool`	`False`	Auto-discover from default locations (`~/.praisonai/skills/`, etc.)

Default Discovery Locations

Skills auto-discovered (in order of precedence):

./.praisonai/skills/ or ./.claude/skills/
~/.praisonai/skills/
/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.

Best Practices

Write trigger-aware descriptions

The description field tells the agent when to activate the skill. Write it as a trigger sentence: “Use this skill when the user asks to process PDF files” — not just “Handles PDFs”.

Keep instructions focused

Level 2 instructions inject into the agent’s context. Keep them under 5,000 tokens and focused on the specific task — don’t repeat general knowledge the LLM already has.

Put heavy content in resources

Reference documentation, example data, and large scripts belong in references/ or scripts/ (Level 3). They load only when explicitly needed, keeping context lean.

Match directory name to skill name

The directory name must exactly match the name field in SKILL.md. Use praisonai skills validate --path ./my-skill to catch mismatches before deploying.

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.

Skill Bundles

Group skills into named bundles and select with @name

Skill Invocation

Slash commands, argument substitution, and invocation policy

Skill Manage

Let agents create and edit skills with human approval

Skills vs Tools

When to use SKILL.md knowledge vs executable tools

Knowledge

Give agents access to documents and vector search

AI Agents with Callbacks

Skill Bundles

​Quick Start

​How It Works

​SKILL.md Format

​Required Fields

​Optional Fields

​Configuration Options

SkillsConfig SDK Reference

​Default Discovery Locations

​Common Patterns

​Single Skill

​Multiple Skills from Directory

​Creating a SKILL.md

​Best Practices

​Group Skills into Bundles

​Related

Skill Bundles

Skill Invocation

Skill Manage

Skills vs Tools

Knowledge

Quick Start

How It Works

SKILL.md Format

Required Fields

Optional Fields

Configuration Options

Default Discovery Locations

Common Patterns

Single Skill

Multiple Skills from Directory

Creating a SKILL.md

Best Practices

Group Skills into Bundles

Related