Skip to main content

​
Agent Skills

Agent Skills is an open standard for extending AI agent capabilities with specialized knowledge and workflows. PraisonAI Agents fully supports the Agent Skills specification, enabling agents to load and use modular capabilities through SKILL.md files.

​
Overview

Skills provide a way to give agents specialized knowledge and instructions without bloating the main system prompt. They use progressive disclosure to efficiently manage context:
  1. Level 1 - Metadata (~100 tokens): Name and description loaded at startup
  2. Level 2 - Instructions (<5000 tokens): Full SKILL.md body loaded when activated
  3. Level 3 - Resources (as needed): Scripts, references, and assets loaded on demand

​
Quick Start

​
Using Skills with an Agent

from praisonaiagents import Agent

# Create an agent with specific skills
agent = Agent(
    name="PDF Assistant",
    instructions="You are a helpful assistant.",
    skills=["./skills/pdf-processing"],  # Direct skill paths
)

# Or discover skills from directories
agent = Agent(
    name="Multi-Skill Agent",
    instructions="You are a versatile assistant.",
    skills_dirs=["./skills"],  # Scan for skill subdirectories
)

​
Using SkillManager Directly

from praisonaiagents import SkillManager

# Create a skill manager
manager = SkillManager()

# Discover skills from directories
manager.discover(["./skills"])

# Generate prompt XML for system prompt injection
prompt_xml = manager.to_prompt()
print(prompt_xml)

​
SKILL.md Format

Each skill is a directory containing a SKILL.md file with YAML frontmatter: 
---
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
compatibility: Works with PraisonAI Agents
metadata:
  author: your-org
  version: "1.0"
allowed-tools: Read Write  # Optional: space-delimited tool list
---

# PDF Processing Skill

## Overview

This skill enables agents to process PDF documents...

## Instructions

1. First, verify the PDF file exists
2. Use appropriate tools to read the PDF content
3. Extract text while preserving structure

​
Required Fields

FieldDescriptionConstraints
nameSkill identifier1-64 chars, lowercase, hyphens only
descriptionWhat the skill does and when to use it1-1024 chars

​
Optional Fields

FieldDescription
licenseLicense for the skill (e.g., Apache-2.0, MIT)
compatibilityCompatibility information (max 500 chars)
metadataKey-value pairs for custom properties
allowed-toolsSpace-delimited list of tools the skill requires

​
Directory Structure

my-skill/
├── SKILL.md          # Required: Skill definition
├── scripts/          # Optional: Executable code
├── references/       # Optional: Additional documentation
└── assets/           # Optional: Templates, data files

​
Skill Discovery Locations

PraisonAI searches for skills in these locations (in order of precedence):
  1. Project: ./.praison/skills/ or ./.claude/skills/
  2. User: ~/.praison/skills/
  3. System: /etc/praison/skills/

​
CLI Commands

​
List Available Skills

praisonai skills list
praisonai skills list --dirs ./my-skills ./other-skills

​
Validate a Skill

praisonai skills validate --path ./my-skill

​
Create a New Skill

praisonai skills create --name my-new-skill --description "A custom skill"

​
Generate Prompt XML

praisonai skills prompt --dirs ./skills

​
API Reference

​
SkillManager

The main class for managing skills. 
from praisonaiagents import SkillManager

manager = SkillManager()

# Discover skills
count = manager.discover(["./skills"], include_defaults=True)

# Add a single skill
skill = manager.add_skill("./path/to/skill")

# Get a skill by name
skill = manager.get_skill("pdf-processing")

# Activate a skill (load instructions)
manager.activate_by_name("pdf-processing")

# Get instructions
instructions = manager.get_instructions("pdf-processing")

# Generate prompt XML
prompt = manager.to_prompt()

​
SkillLoader

For progressive loading of skills. 
from praisonaiagents.skills import SkillLoader

loader = SkillLoader()

# Level 1: Load metadata only
skill = loader.load_metadata("./my-skill")

# Level 2: Activate (load instructions)
loader.activate(skill)
print(skill.instructions)

# Level 3: Load resources
scripts = loader.load_scripts(skill)
references = loader.load_references(skill)
assets = loader.load_assets(skill)

​
Validation

from praisonaiagents.skills import validate, validate_metadata

# Validate a skill directory
errors = validate("./my-skill")
if errors:
    for error in errors:
        print(f"Error: {error}")
else:
    print("Skill is valid!")

# Validate metadata dict
errors = validate_metadata({"name": "test", "description": "Test skill"})

​
Compatibility

PraisonAI’s Agent Skills implementation follows the open standard, ensuring compatibility with:
  • Claude Code (.claude/skills/)
  • GitHub Copilot (.github/skills/)
  • Cursor (Agent Skills support)
  • OpenAI Codex CLI
PraisonAI supports both .praison/skills/ and .claude/skills/ for maximum compatibility.

​
Performance

Agent Skills are designed for zero performance impact when not in use:
  • Lazy Loading: Skills are only loaded when explicitly accessed
  • No Auto-discovery: Discovery runs only when requested
  • Minimal Memory: Skills not in use consume no memory
  • Progressive Disclosure: Only load what’s needed

​
Examples

See the examples/skills/ directory for complete examples:
  • basic_skill_usage.py - Basic skill discovery and usage
  • custom_skill_example.py - Creating custom skills programmatically
  • pdf-processing/ - Example skill directory