Agent Skills - PraisonAI

Skills are modular capability packages that extend agents with specialized knowledge and workflows without bloating the system prompt.

Looking for how to run skills (/slash commands, $ARGUMENTS substitution, inline shell)? See Skill Invocation.

Quick Start

Create a Skill

Create a directory with a SKILL.md file:

my-skill/
└── SKILL.md

---
name: code-review
description: Review code for bugs, security issues, and best practices. Use when asked to review or analyze code.
---

# Code Review Instructions

When reviewing code:
1. Check for security vulnerabilities
2. Identify potential bugs
3. Suggest improvements

Use with Agent

from praisonaiagents import Agent

agent = Agent(
    name="Code Assistant",
    instructions="You help with coding tasks",
    skills=["./my-skill"]  # Load skill
)

agent.start("Review this Python code for issues")

How Skills Work

Progressive Disclosure

Level	What’s Loaded	When	Token Cost
1. Metadata	Name + description	At startup	~100 tokens
2. Instructions	Full SKILL.md body	When triggered	Up to 5000 tokens
3. Resources	Scripts, assets	On demand	Variable

SKILL.md Format

---
name: skill-name              # Required: lowercase, hyphens only
description: What it does...  # Required: when to use this skill
license: Apache-2.0           # Optional
compatibility: PraisonAI      # Optional
metadata:                     # Optional
  author: your-org
  version: "1.0"
allowed-tools: Read Write     # Optional: required tools
---

# Skill Instructions

Your detailed instructions here...

Required Fields

Field	Constraints	Example
`name`	1-64 chars, lowercase, hyphens	`code-review`
`description`	1-1024 chars	`Review code for bugs...`

Directory Structure

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, data

Loading Skills

Direct Paths

agent = Agent(
    skills=["./skills/code-review", "./skills/testing"]
)

Directory Scan

agent = Agent(
    skills_dirs=["./skills"]  # Scans for subdirectories with SKILL.md
)

Default Locations

Skills are auto-discovered from:

./.praisonai/skills/ or ./.claude/skills/ (project)
~/.praisonai/skills/ (user)
/etc/praisonai/skills/ (system)

Using SkillManager

from praisonaiagents import SkillManager

manager = SkillManager()

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

# Add single skill
manager.add_skill("./my-skill")

# Get skill by name
skill = manager.get_skill("code-review")

# Activate (load instructions)
manager.activate_by_name("code-review")

# Generate prompt XML
prompt_xml = manager.to_prompt()

CLI Commands

# List available skills
praisonai skills list

# Validate a skill
praisonai skills validate --path ./my-skill

# Create new skill
praisonai skills create --name my-skill

# Generate prompt XML
praisonai skills prompt --dirs ./skills

Compatibility

Skills follow the open agentskills.io standard: PraisonAI supports both .praisonai/skills/ and .claude/skills/ directories.

Performance

Skills have zero performance impact when not used:

Lazy Loading: Only loaded when accessed
No Auto-discovery: Discovery runs only when requested
Minimal Memory: Unused skills consume no memory

Best Practices

Write clear descriptions

The description tells the agent WHEN to use the skill. Be specific about triggers.

Keep instructions focused

Each skill should do one thing well. Split complex capabilities into multiple skills.

Use progressive disclosure

Put essential info in instructions, detailed references in the references/ folder.

Tools

Function-based capabilities

Knowledge

Document-based context

Agent Reflection

Agent Hooks

​Quick Start

​How Skills Work

​Progressive Disclosure

​SKILL.md Format

​Required Fields

​Directory Structure

​Loading Skills

​Direct Paths

​Directory Scan

​Default Locations

​Using SkillManager

​CLI Commands

​Compatibility

​Performance

​Best Practices

​Related

Tools

Knowledge

Quick Start

How Skills Work

Progressive Disclosure

SKILL.md Format

Required Fields

Directory Structure

Loading Skills

Direct Paths

Directory Scan

Default Locations

Using SkillManager

CLI Commands

Compatibility

Performance

Best Practices

Related