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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Skills vs Tools Overview"
        User[📱 User Request] --> Router{🧠 Agent Router}
        
        Router --> |"Load context"| Skill[📋 SKILL.md<br/>Declarative Knowledge]
        Router --> |"Execute action"| Tool[⚙️ Function<br/>Executable Capability]
        
        Skill --> Prompt[📝 System Prompt]
        Tool --> Action[🎯 Runtime Action]
        
        Prompt --> Response[💬 LLM Response]
        Action --> Response
    end
    
    classDef skill fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef flow fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class Skill skill
    class Tool tool
    class Router,User flow
    class Prompt,Action,Response result
```

## Quick Start

<Steps>
  <Step title="Skills: Load Knowledge">
    Create a skill to provide specialized knowledge to agents:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>

  <Step title="Tools: Execute Actions">
    Create a tool to perform runtime actions:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>
</Steps>

***

## Conceptual Difference

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Skills: Declarative Knowledge"
        S1[📄 SKILL.md] --> S2[📝 Instructions]
        S2 --> S3[🔍 Progressive Disclosure]
        S3 --> S4[💾 Static Content]
    end
    
    subgraph "Tools: Executable Functions"
        T1[⚙️ Python Function] --> T2[🎯 Runtime Execution]
        T2 --> T3[🔄 Dynamic Results]
        T3 --> T4[💡 Side Effects]
    end
    
    classDef skill fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class S1,S2,S3,S4 skill
    class T1,T2,T3,T4 tool
```

### Comparison Table

| Dimension       | Skills                      | Tools              |
| --------------- | --------------------------- | ------------------ |
| **Artifact**    | `SKILL.md` file             | Python function    |
| **Purpose**     | Provide knowledge & context | Execute actions    |
| **Invocation**  | Load into system prompt     | LLM function calls |
| **Timing**      | Load time (progressive)     | Runtime on-demand  |
| **Cost**        | Token usage                 | Execution time     |
| **Storage**     | File system                 | Code registry      |
| **Safety**      | Static allowlists           | Runtime validation |
| **Portability** | agentskills.io standard     | Framework-specific |

***

## Skills: Declarative Knowledge Packages

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant SkillManager
    participant Skill
    
    Note over SkillManager: Level 1: Metadata (~100 tokens)
    Agent->>SkillManager: Load skills
    SkillManager->>Skill: Read frontmatter
    
    Note over SkillManager: Level 2: Instructions (<5k tokens)
    Agent->>SkillManager: Task matches skill
    SkillManager->>Skill: Load full content
    Skill-->>Agent: Inject into prompt
    
    Note over SkillManager: Level 3: Resources (on demand)
    Agent->>SkillManager: Need scripts/assets
    SkillManager->>Skill: Load resources
```

### Skills in PraisonAI

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Tool Execution Flow"
        LLM[🤖 LLM] --> Call[📞 tool_calls]
        Call --> Function[⚙️ Python Function]
        Function --> Action[🎯 Execute Action]
        Action --> Result[📊 Return Result]
        Result --> LLM
    end
    
    classDef llm fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    
    class LLM llm
    class Call,Function,Action tool
    class Result result
```

### Tools in PraisonAI

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

| Category            | Examples                                | Purpose           |
| ------------------- | --------------------------------------- | ----------------- |
| **Search**          | `tavily`, `web_search`, `exa`           | Find information  |
| **File Operations** | `read_file`, `write_file`, `list_files` | Manage files      |
| **Code Analysis**   | `ast_grep_search`, `execute_code`       | Analyze code      |
| **Data Processing** | `pandas_tools`, `csv_tools`             | Process data      |
| **System**          | `shell_tools`, `execute_command`        | System operations |

***

## PraisonAI Integration Paths

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Skills Integration"
        SD[📁 Skill Discovery] --> SM[📦 SkillManager]
        SM --> SP[📝 System Prompt]
        SP --> LLM[🤖 LLM]
    end
    
    subgraph "Tools Integration"
        TR[🔧 Tool Registry] --> TA[⚙️ Tool Assignment]
        TA --> TC[📞 Tool Calls]
        TC --> LLM
    end
    
    subgraph "Configuration"
        AT[📋 allowed-tools] -.-> |"hints"| TA
        SC[🔧 /skill commands] --> SM
        TC2[🎯 tool_choice] --> TC
    end
    
    classDef skill fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef config fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef llm fill:#8B0000,stroke:#7C90A0,color:#fff
    
    class SD,SM,SP skill
    class TR,TA,TC tool
    class AT,SC,TC2 config
    class LLM llm
```

### Discovery & Invocation

| Feature        | Skills                  | Tools                   |
| -------------- | ----------------------- | ----------------------- |
| **Discovery**  | File system scan        | Import registry         |
| **Activation** | `/skill` slash commands | Agent assignment        |
| **Execution**  | Prompt injection        | Function calls          |
| **Control**    | `allowed-tools` hints   | `tool_choice` parameter |

### CLI Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Question{What do you need?}
    
    Question --> |"Provide knowledge"| UseSkill[📋 Use Skills]
    Question --> |"Take actions"| UseTool[⚙️ Use Tools]
    
    UseSkill --> SkillEx["• Code review guidelines<br/>• Writing templates<br/>• Domain knowledge<br/>• Best practices"]
    
    UseTool --> ToolEx["• Search the web<br/>• Execute code<br/>• Read/write files<br/>• API calls"]
    
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef skill fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class Question decision
    class UseSkill,SkillEx skill
    class UseTool,ToolEx tool
```

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

<AccordionGroup>
  <Accordion title="Skills: Keep Context Focused">
    Write skills that provide specific, actionable knowledge. Use progressive disclosure - put essential info in SKILL.md, detailed references in `references/` folder.

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    ---
    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
    ```
  </Accordion>

  <Accordion title="Tools: Design for Reliability">
    Create tools with clear interfaces, proper error handling, and type hints. Each tool should have a single responsibility.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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)}
    ```
  </Accordion>

  <Accordion title="Security: Validate Inputs & Outputs">
    **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.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Skills" icon="puzzle-piece" href="/concepts/skills">
    Detailed skills documentation and API
  </Card>

  <Card title="Agent Tools" icon="wrench" href="/concepts/tools">
    Complete tools reference and built-ins
  </Card>
</CardGroup>