Agent Skills - PraisonAI Documentation

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:

Level 1 - Metadata (~100 tokens): Name and description loaded at startup
Level 2 - Instructions (<5000 tokens): Full SKILL.md body loaded when activated
Level 3 - Resources (as needed): Scripts, references, and assets loaded on demand

CLI Commands

List Available Skills

List all discovered skills in the configured directories.

# List all available skills
praisonai skills list

# List skills from specific directories
praisonai skills list --dirs ./my-skills ./other-skills

# List skills with verbose output
praisonai skills list --verbose

Output:

Available Skills:
├── pdf-processing
│   ├── Description: Process and extract information from PDF documents
│   ├── Path: /Users/user/.praison/skills/pdf-processing
│   └── Metadata: author=your-org, version=1.0
├── data-analysis
│   ├── Description: Analyze data using pandas and visualization
│   ├── Path: /Users/user/.praison/skills/data-analysis
│   └── Metadata: author=data-team, version=2.1
└── web-scraping
    ├── Description: Extract data from websites using various techniques
    ├── Path: ./skills/web-scraping
    └── Metadata: author=scraping-team, version=1.5

Validate a Skill

Validate that a skill directory conforms to the Agent Skills specification.

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

# Validate with detailed output
praisonai skills validate --path ./my-skill --verbose

# Validate multiple skills
praisonai skills validate --path ./skill1 --path ./skill2

Output:

✓ Skill validation passed for: ./my-skill
├── ✓ SKILL.md exists
├── ✓ Frontmatter valid
├── ✓ Name format correct (lowercase, hyphens only)
├── ✓ Description within limits (1-1024 chars)
├── ✓ Optional fields valid
└── ✓ Directory structure valid

Error Output:

✗ Skill validation failed for: ./my-skill
├── ✗ SKILL.md not found
├── ✗ Name contains invalid characters (use lowercase and hyphens only)
└── ✗ Description too long (1024 chars max, found 1500)

Create a New Skill

Create a new skill directory with AI-generated content (default) or from a template.

# Create with AI-generated content (uses OpenAI/Anthropic API)
praisonai skills create --name my-skill --description "Process and analyze CSV files"

# Create with all metadata options
praisonai skills create --name my-skill \
  --description "Process CSV files" \
  --author "my-team" \
  --license "MIT" \
  --compatibility "Works with PraisonAI Agents" \
  --output-dir ./custom-skills

# Create with template only (no AI, works without API key)
praisonai skills create --name my-skill --description "My skill" --template

# Create with auto-generated scripts/script.py
praisonai skills create --name my-skill --description "Data processor" --script

# Create CSV analyzer with relevant script
praisonai skills create --name csv-analyzer --description "Analyze CSV files" --script

# Create PDF processor with relevant script  
praisonai skills create --name pdf-processor --description "Extract text from PDF documents" --script

# Create API client with relevant script
praisonai skills create --name api-client --description "Make HTTP requests to REST APIs" --script

# Create CSV analyzer with template
praisonai skills create --name csv-analyzer --description "Analyze CSV files" --script --template
✓ scripts/script.py contains CSV analysis code with pandas

# Create PDF processor with template
praisonai skills create --name pdf-processor --description "Extract text from PDF documents" --script --template
✓ scripts/script.py contains PDF extraction code

# Create API client with template
praisonai skills create --name api-client --description "Make HTTP requests to REST APIs" --script --template
✓ scripts/script.py contains HTTP request code

# Create YAML config with AI generation
praisonai skills create --name yaml-config --description "Parse and validate YAML configuration files" --script
✓ AI generates comprehensive SKILL.md and script.py

# Create JSON parser
praisonai skills create --name json-parser --description "Parse JSON files" --script
✓ AI generates comprehensive SKILL.md and script.py

AI Generation Features:

Automatically generates comprehensive SKILL.md content based on description
Creates scripts/script.py with relevant Python code when needed
Falls back to template if no API key is available
Use --template flag to skip AI and use template only

Smart Script Generation (--script flag): When using --script, the generated scripts/script.py is tailored to the description:

Description Keywords	Generated Script Type
csv, spreadsheet, data analysis	Pandas-based CSV analyzer
pdf, document, extract text	PyPDF-based PDF processor
api, http, request, web	Requests-based API client
image, photo, resize	PIL-based image processor
json, yaml, config	JSON/YAML parser
text, regex, search	Text processing utilities
file, read, write	File operations

The SKILL.md automatically includes usage instructions for the generated script:

## Script Usage

This skill includes a Python script at `scripts/script.py` that provides the core functionality.

### Running the Script

\`\`\`bash
python scripts/script.py <input>
\`\`\`

### Using as a Module

\`\`\`python
from scripts.script import csv_analyzer

result = csv_analyzer(input_data)
print(result)
\`\`\`

Generated Structure:

my-skill/
├── SKILL.md
├── scripts/
│   └── script.py    # Generated when using --script flag
├── references/
└── assets/

Generated SKILL.md:

---
name: my-skill
description: A custom skill for data processing
license: MIT
compatibility: Works with PraisonAI Agents
metadata:
  author: my-team
  version: "1.0"
allowed-tools: Read Write
---

# My Skill

## Overview

This skill enables agents to...

## Instructions

1. First step...
2. Second step...
3. Final step...

## Usage

Use this skill when the user asks to...

Upload Skill to Anthropic

Upload a skill to Anthropic’s Skills API for use with Claude.

# Upload a skill to Anthropic
praisonai skills upload --path ./my-skill

# Upload with custom display title
praisonai skills upload --path ./my-skill --title "My Custom Skill"

Requirements:

ANTHROPIC_API_KEY environment variable must be set
anthropic Python package must be installed
Skill must have a valid SKILL.md file

Output:

Uploading skill 'my-skill' to Anthropic...
✓ Skill uploaded successfully!
  ID: skill_01AbCdEfGhIjKlMnOpQrStUv
  Title: My Custom Skill

Generate Prompt XML

Generate the XML prompt block for skills, useful for system prompt injection.

# Generate prompt XML for all discovered skills
praisonai skills prompt

# Generate for specific directories
praisonai skills prompt --dirs ./skills ./other-skills

# Generate for specific skill names
praisonai skills prompt --skills pdf-processing data-analysis

# Output to file
praisonai skills prompt --output skills-prompt.xml

Output:

<available_skills>
  <skill name="pdf-processing" path="/Users/user/.praison/skills/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.</description>
  </skill>
  <skill name="data-analysis" path="/Users/user/.praison/skills/data-analysis">
    <description>Analyze data using pandas, create visualizations, and generate insights from datasets. Use this skill when the user needs data analysis or visualization.</description>
  </skill>
</available_skills>

Skill Discovery Locations

PraisonAI searches for skills in these locations (in order of precedence):

Project: ./.praison/skills/ or ./.claude/skills/
User: ~/.praison/skills/
System: /etc/praison/skills/ (admin-managed)

Using Skills with Agents

Direct Skill Paths

from praisonaiagents import Agent

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

Skill Discovery

# Create agent that discovers skills from directories using SkillsConfig
from praisonaiagents.config.feature_configs import SkillsConfig

agent = Agent(
    name="Multi-Skill Agent",
    instructions="You are a versatile assistant.",
    skills=SkillsConfig(dirs=["./skills", "~/.praison/skills"])
)

Complete Example: CSV Analysis with Skills

Skills work automatically - the agent reads the SKILL.md, understands the instructions, and executes bundled scripts. No custom tools needed! Step 1: Create the skill

pip install praisonai
export OPENAI_API_KEY=xxxxxx
praisonai skills create --name csv-analyzer --description "Analyze CSV files" --script

Step 2: Create test data

echo "transaction_id,account_holder,account_number,transaction_type,amount,timestamp,status
1,John Doe,ACC001,deposit,1500.00,2024-01-15 09:30:00,completed
2,Jane Smith,ACC002,withdrawal,500.00,2024-01-15 10:15:00,completed
3,Bob Wilson,ACC003,transfer,2000.00,2024-01-15 11:00:00,pending
4,Alice Brown,ACC004,deposit,3500.00,2024-01-15 14:30:00,completed
5,Charlie Davis,ACC005,withdrawal,750.00,2024-01-15 15:45:00,failed" > data.csv

Step 3: Create app.py

from praisonai import Agent

agent = Agent(
    name="Data Analyst",
    instructions="Analyze data files",
    skills=["./csv-analyzer"]
)

agent.run("Analyze the data in this file: ./data.csv using the csv-analyzer skill.")

Step 4: Run

python app.py

How it works behind the scenes:

Skill Discovery: When skills=["./csv-analyzer"] is set, the agent loads skill metadata
Lazy Tool Injection: read_file and run_skill_script tools are added only when skills are accessed (zero performance impact when not used)
System Prompt: Skills are injected into the system prompt with their descriptions, locations, and current working directory
Path Resolution: The run_skill_script tool automatically resolves relative file paths (like data.csv) to absolute paths based on the working directory
Progressive Disclosure: Agent reads SKILL.md only when the skill is relevant to the task
Script Execution: Agent runs scripts from scripts/ directory using the modular skill_tools module

Skill Directory Structure:

csv-analyzer/
├── SKILL.md              # Required: instructions + metadata
└── scripts/
    └── skill.py          # Optional: executable scripts

SKILL.md Example:

---
name: csv-analyzer
description: Analyze CSV files to extract statistics and insights
license: Apache-2.0
metadata:
  author: praison
  version: "1.0"
---

# CSV Analyzer

## When to Use
Use this skill when the user needs to analyze CSV files.

## Instructions
1. Read the CSV file
2. Identify columns and data types
3. Calculate statistics for numeric columns
4. Report findings clearly

CLI with Skills

# Use skills with direct prompt
praisonai "Analyze this PDF" --skills ./skills/pdf-processing

# Use skills with discovery
praisonai "Process the data" --skills-dirs ./skills

# Combine with other features
praisonai "Extract and analyze" \
  --skills ./skills/pdf-processing \
  --skills-dirs ./skills \
  --verbose \
  --metrics

SKILL.md Format

Required Fields

Field	Description	Constraints
`name`	Skill identifier	1-64 chars, lowercase, hyphens only
`description`	What the skill does and when to use it	1-1024 chars

Optional Fields

Field	Description
`license`	License for the skill (e.g., Apache-2.0, MIT)
`compatibility`	Compatibility information (max 500 chars)
`metadata`	Key-value pairs for custom properties
`allowed-tools`	Space-delimited list of tools the skill requires

Example SKILL.md

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

# PDF Processing Skill

## Overview

This skill enables agents to process PDF documents, extract text, tables, and metadata from PDF files.

## Instructions

1. First, verify the PDF file exists and is accessible
2. Use appropriate tools to read the PDF content
3. Extract text while preserving structure and formatting
4. Identify and extract tables if present
5. Extract metadata like author, creation date, etc.
6. Provide a structured summary of the PDF content

## When to Use

- User asks to read or analyze PDF files
- Need to extract specific information from PDFs
- Converting PDF content to other formats
- Summarizing PDF documents

## Tools Required

- Read: To access PDF files
- Write: To save extracted content or summaries

Directory Structure

skill-name/
├── SKILL.md          # Required: Skill definition
├── scripts/          # Optional: Executable code
│   ├── extract.py    # Python scripts for the skill
│   └── process.sh    # Shell scripts
├── references/       # Optional: Additional documentation
│   ├── api.md        # API documentation
│   └── examples.md   # Usage examples
└── assets/           # Optional: Templates, data files
    ├── template.txt   # Text templates
    └── sample.json   # Sample data

Best Practices

Clear Descriptions: Be specific about when to use the skill
Structured Instructions: Use numbered steps for clarity
Tool Requirements: List all required tools in allowed-tools
Version Management: Use semantic versioning in metadata
Documentation: Include examples in references/
Testing: Validate skills before deployment

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

Troubleshooting

Common Issues

Skill not found
- Check if skill directory is in discovery path
- Verify SKILL.md exists in the skill directory
- Use praisonai skills list --verbose to debug
Validation errors
- Ensure name uses only lowercase and hyphens
- Check description length (1-1024 chars)
- Verify YAML frontmatter is valid
Skills not loading
- Check file permissions on skill directories
- Verify skill directory structure
- Use praisonai skills validate to check compliance

Debug Commands

# List with verbose output
praisonai skills list --verbose

# Validate with details
praisonai skills validate --path ./skill --verbose

# Check discovery paths
praisonai skills list --dirs ./test-skills --verbose

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

CLI

​Overview

​CLI Commands

​List Available Skills

​Validate a Skill

​Create a New Skill

​Upload Skill to Anthropic

​Generate Prompt XML

​Skill Discovery Locations

​Using Skills with Agents

​Direct Skill Paths

​Skill Discovery

​Complete Example: CSV Analysis with Skills

​CLI with Skills

​SKILL.md Format

​Required Fields

​Optional Fields

​Example SKILL.md

​Directory Structure

​Best Practices

​Compatibility

​Performance

​Troubleshooting

​Common Issues

​Debug Commands

​Examples

Overview

CLI Commands

List Available Skills

Validate a Skill

Create a New Skill

Upload Skill to Anthropic

Generate Prompt XML

Skill Discovery Locations

Using Skills with Agents

Direct Skill Paths

Skill Discovery

Complete Example: CSV Analysis with Skills

CLI with Skills

SKILL.md Format

Required Fields

Optional Fields

Example SKILL.md

Directory Structure

Best Practices

Compatibility

Performance

Troubleshooting

Common Issues

Debug Commands

Examples