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

​
Quick Start

1

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
2

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

LevelWhat’s LoadedWhenToken Cost
1. MetadataName + descriptionAt startup~100 tokens
2. InstructionsFull SKILL.md bodyWhen triggeredUp to 5000 tokens
3. ResourcesScripts, assetsOn demandVariable

​
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

FieldConstraintsExample
name1-64 chars, lowercase, hyphenscode-review
description1-1024 charsReview 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:
  1. ./.praison/skills/ or ./.claude/skills/ (project)
  2. ~/.praison/skills/ (user)
  3. /etc/praison/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 .praison/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

The description tells the agent WHEN to use the skill. Be specific about triggers.
Each skill should do one thing well. Split complex capabilities into multiple skills.
Put essential info in instructions, detailed references in the references/ folder.

Tools

Function-based capabilities

Knowledge

Document-based context