Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

Skills and Tools are two distinct capability systems in PraisonAI that serve different purposes and operate at different levels.

​
Quick Start

1

Skills: Load Knowledge

Create a skill to provide specialized knowledge to agents:
from praisonaiagents import Agent

# Create skill directory with SKILL.md
agent = Agent(
    name="Code Assistant",
    instructions="You help with coding tasks",
    skills=["./code-review-skill"]  # Load declarative knowledge
)

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

Tools: Execute Actions

Create a tool to perform runtime actions:
from praisonaiagents import Agent

def search_vulnerabilities(code: str) -> str:
    """Search for security vulnerabilities in code."""
    # Tool implementation
    return "Found 3 potential SQL injection vulnerabilities"

agent = Agent(
    name="Security Agent",
    tools=[search_vulnerabilities]  # Add executable function
)

agent.start("Scan this code for vulnerabilities")

​
Conceptual Difference

​
Comparison Table

DimensionSkillsTools
ArtifactSKILL.md filePython function
PurposeProvide knowledge & contextExecute actions
InvocationLoad into system promptLLM function calls
TimingLoad time (progressive)Runtime on-demand
CostToken usageExecution time
StorageFile systemCode registry
SafetyStatic allowlistsRuntime validation
Portabilityagentskills.io standardFramework-specific

​
Skills: Declarative Knowledge Packages

Skills are SKILL.md files that provide specialized knowledge and instructions to agents without bloating the system prompt.

​
Skills in PraisonAI

from praisonaiagents import Agent

# Direct skill paths
agent = Agent(
    name="Code Assistant",
    skills=["./skills/code-review", "./skills/testing"]
)

# Directory scanning
agent = Agent(
    name="Assistant", 
    skills_dirs=["./skills"]  # Auto-discover SKILL.md files
)

# Auto-discovery from default locations:
# 1. ./.praisonai/skills/ (project)
# 2. ~/.praisonai/skills/ (user)  
# 3. /etc/praisonai/skills/ (system)

​
SKILL.md Format

---
name: code-review
description: Review code for bugs, security issues, and best practices
allowed-tools: read_file write_file  # Hint for required tools
---

# Code Review Instructions

When reviewing code:
1. Check for security vulnerabilities
2. Identify potential bugs  
3. Suggest improvements
4. Follow language-specific best practices

​
Tools: Executable Functions

Tools are Python functions that agents can call to perform actions and interact with external systems.

​
Tools in PraisonAI

from praisonaiagents import Agent
from typing import List, Dict

def search_code(pattern: str, directory: str = ".") -> List[Dict]:
    """Search for code patterns in files."""
    # Tool implementation
    return [{"file": "app.py", "line": 42, "match": "vulnerable code"}]

# Assign tools to agents
agent = Agent(
    name="Code Scanner",
    tools=[search_code]  # Executable functions
)

# Tool with built-in capabilities
agent = Agent(
    name="Web Researcher",
    tools=["tavily", "web_search"]  # Built-in tool names
)

​
Tool Categories

CategoryExamplesPurpose
Searchtavily, web_search, exaFind information
File Operationsread_file, write_file, list_filesManage files
Code Analysisast_grep_search, execute_codeAnalyze code
Data Processingpandas_tools, csv_toolsProcess data
Systemshell_tools, execute_commandSystem operations

​
PraisonAI Integration Paths

​
Discovery & Invocation

FeatureSkillsTools
DiscoveryFile system scanImport registry
Activation/skill slash commandsAgent assignment
ExecutionPrompt injectionFunction calls
Controlallowed-tools hintstool_choice parameter

​
CLI Commands

# Skills management
praisonai skills list
praisonai skills create --name my-skill
praisonai skills validate --path ./skill

# Tools management  
praisonai tools list
praisonai tools discover
praisonai tools resolve --name web_search

​
When to Use Each

​
Use Skills When:

  • Providing specialized knowledge
  • Sharing best practices
  • Template instructions
  • Domain-specific guidance
  • Static reference material

​
Use Tools When:

  • Executing dynamic actions
  • Interacting with APIs
  • Processing data
  • File operations
  • Real-time information

​
Best Practices

Write skills that provide specific, actionable knowledge. Use progressive disclosure - put essential info in SKILL.md, detailed references in references/ folder.
---
name: api-testing  
description: Test REST APIs for security and functionality
allowed-tools: http_client json_tools
---

# API Testing Guidelines

## Quick Checks
1. Authentication validation
2. Input sanitization  
3. Rate limiting

## Detailed procedures in references/security-checklist.md
Create tools with clear interfaces, proper error handling, and type hints. Each tool should have a single responsibility.
def validate_api_endpoint(url: str, method: str = "GET") -> Dict[str, Any]:
    """
    Validate API endpoint for security issues.
    
    Args:
        url: API endpoint URL
        method: HTTP method to test
        
    Returns:
        Dict with validation results
    """
    try:
        # Tool implementation with proper error handling
        return {"status": "valid", "issues": []}
    except Exception as e:
        return {"status": "error", "message": str(e)}
Skills: Don’t put secrets in SKILL.md files. Use environment variables for sensitive data.Tools: Always validate inputs and sanitize outputs. Use approval decorators for high-risk operations.
from praisonaiagents.approval import require_approval

@require_approval(risk_level="critical")
def execute_shell_command(command: str) -> str:
    """Execute shell command with approval."""
    # Implementation with security checks
    pass

Agent Skills

Detailed skills documentation and API

Agent Tools

Complete tools reference and built-ins