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.

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

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:

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

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

---

Related

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