Skills vs Tools

Understand the distinction between Agent Skills (SKILL.md) and Tools (executable functions) in PraisonAI

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

from praisonaiagents import Agent

agent = Agent(
    name="Code Assistant",
    instructions="Review code and scan for vulnerabilities",
    skills=["./skills/code-review"],
    tools=["read_file"],
)
agent.start("Review app.py for security issues")

The user submits a task; skills supply knowledge while tools execute concrete actions.

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

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

PraisonAI Integration Paths

Discovery & Invocation

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

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

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

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

Related