Agent Skills

Extend agent capabilities with modular, reusable skill packages

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

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

Directory Structure

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

Loading Skills

graph TB
    subgraph "Skill Loading"
        Direct[📁 Direct Path<br/>skills=["./skill"]]
        Dirs[📂 Directory Scan<br/>skills_dirs=["./skills"]]
        Auto[🔍 Auto-discover<br/>Default locations]
    end

    Direct --> Agent[🤖 Agent]
    Dirs --> Agent
    Auto --> Agent

    classDef method fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff

    class Direct,Dirs,Auto method
    class Agent agent

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. ./.praisonai/skills/ or ./.claude/skills/ (project)
2. ~/.praisonai/skills/ (user)
3. /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

Related