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

# Agent Skills

> Manage modular skills for agents using the open Agent Skills standard

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:

1. **Level 1 - Metadata** (\~100 tokens): Name and description loaded at startup
2. **Level 2 - Instructions** (\<5000 tokens): Full SKILL.md body loaded when activated
3. **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.

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

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

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

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

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

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

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

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

### Check Skills

Check all discovered skills for issues and validate their configurations:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check all skills
praisonai skills check

# Check with verbose output
praisonai skills check --verbose

# Check specific directories
praisonai skills check --dirs ./skills ./other-skills
```

**Output:**

```
Skill Health Check

✅ pdf-processing
   ✓ SKILL.md valid
   ✓ Frontmatter complete
   ✓ Instructions present

✅ data-analysis
   ✓ SKILL.md valid
   ✓ scripts/script.py exists
   ✓ Dependencies installed

⚠️ web-scraping
   ✓ SKILL.md valid
   ⚠ Missing examples/ directory
   ⚠ No scripts found

❌ broken-skill
   ✗ Invalid SKILL.md frontmatter
   ✗ Name contains invalid characters

Summary: 2 healthy, 1 warning, 1 error
```

### Eligible Skills

List skills eligible for a specific task or capability:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List skills eligible for data tasks
praisonai skills eligible --task "analyze CSV data"

# List skills with specific tools
praisonai skills eligible --tools read_file write_file

# Output as JSON
praisonai skills eligible --task "process PDFs" --json
```

**Output:**

```
Eligible Skills for: "analyze CSV data"

1. csv-analyzer (score: 0.95)
   Match: CSV, data analysis, statistics

2. data-analysis (score: 0.82)
   Match: data analysis, visualization

3. file-processor (score: 0.45)
   Match: file operations
```

## Skill Discovery Locations

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

1. **Project**: `./.praison/skills/` or `./.claude/skills/`
2. **User**: `~/.praisonai/skills/`
3. **System**: `/etc/praison/skills/` (admin-managed)

## Using Skills with Agents

### Direct Skill Paths

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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", "~/.praisonai/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**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai
export OPENAI_API_KEY=xxxxxx
praisonai skills create --name csv-analyzer --description "Analyze CSV files" --script
```

**Step 2: Create test data**

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

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
python app.py
```

**How it works behind the scenes:**

1. **Skill Discovery**: When `skills=["./csv-analyzer"]` is set, the agent loads skill metadata
2. **Lazy Tool Injection**: `read_file` and `run_skill_script` tools are added only when skills are accessed (zero performance impact when not used)
3. **System Prompt**: Skills are injected into the system prompt with their descriptions, locations, and current working directory
4. **Path Resolution**: The `run_skill_script` tool automatically resolves relative file paths (like `data.csv`) to absolute paths based on the working directory
5. **Progressive Disclosure**: Agent reads SKILL.md only when the skill is relevant to the task
6. **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:**

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

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

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

1. **Clear Descriptions**: Be specific about when to use the skill
2. **Structured Instructions**: Use numbered steps for clarity
3. **Tool Requirements**: List all required tools in `allowed-tools`
4. **Version Management**: Use semantic versioning in metadata
5. **Documentation**: Include examples in references/
6. **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

1. **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

2. **Validation errors**
   * Ensure name uses only lowercase and hyphens
   * Check description length (1-1024 chars)
   * Verify YAML frontmatter is valid

3. **Skills not loading**
   * Check file permissions on skill directories
   * Verify skill directory structure
   * Use `praisonai skills validate` to check compliance

### Debug Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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/](https://github.com/MervinPraison/PraisonAI/tree/main/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