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

# Self-Improving Skills

> Let agents create, edit, and patch their own skills at runtime

Self-improving skills enable agents to create, edit, and manage their own capabilities dynamically, learning from user interactions and building persistent knowledge.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Self-Improving Loop"
        U[👤 User Request] --> A[🤖 Agent]
        A --> M{🔍 Skill Exists?}
        M -->|Yes| USE[⚡ Use Skill]
        M -->|No| NEW[✨ create/edit/patch]
        NEW --> SAVE[💾 SKILL.md]
        SAVE --> A
    end
    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef decide fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef action fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef done fill:#10B981,stroke:#7C90A0,color:#fff
    class U,A user
    class M decide
    class NEW,SAVE action
    class USE done
```

## Quick Start

<Steps>
  <Step title="Enable Skill Management">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Skill Builder",
        instructions="When users teach you something, save it as a skill for next time.",
        tools=["skill_manage", "skills_list", "skill_view"]  # auto-injected in bots
    )

    agent.start("Create a skill called 'weekly-summary' that summarises the week's work.")
    ```
  </Step>

  <Step title="Agent Learns and Improves">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Agent creates skills automatically from user interactions
    # User: "Create a weekly summary skill"
    # Agent calls: skill_manage(action="create", name="weekly-summary", content="...")

    # Later interaction
    # User: "Update the summary to include metrics"
    # Agent calls: skill_manage(action="patch", name="weekly-summary", old_string="...", new_string="...")
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant U as 👤 User
    participant A as 🤖 Agent
    participant S as 📋 Skills
    U->>A: "Create weekly report skill"
    A->>S: skill_manage(action="create", name="weekly-report", content="...")
    S-->>A: ✅ Skill created
    A->>S: skill_manage(action="write_file", name="weekly-report", file_path="scripts/report.py", content="...")
    S-->>A: ✅ Script added
    A-->>U: "Weekly report skill created! It can generate reports from data files."
```

The skill management system provides six core actions for runtime skill manipulation:

| Action           | Purpose                  | Security Constraints                  |
| ---------------- | ------------------------ | ------------------------------------- |
| **create**       | Create new skills        | 100KB SKILL.md limit, name validation |
| **edit**         | Replace skill content    | Preserves frontmatter, atomic writes  |
| **patch**        | Targeted find/replace    | String matching, traversal protection |
| **delete**       | Remove skills completely | Path validation, atomic removal       |
| **write\_file**  | Add skill resources      | 1MB limit, allowed subdirs only       |
| **remove\_file** | Delete skill files       | Containment checks, safe removal      |

***

## Configuration Options

### Skill Management Actions

| Action        | Required Args                       | Optional Args              | What it does                               |
| ------------- | ----------------------------------- | -------------------------- | ------------------------------------------ |
| `create`      | `name`, `content`                   | `category`                 | Create a new skill with SKILL.md body      |
| `edit`        | `name`, `content`                   | -                          | Replace an existing skill's SKILL.md body  |
| `patch`       | `name`, `old_string`, `new_string`  | `file_path`, `replace_all` | Fuzzy find-and-replace within a skill file |
| `delete`      | `name`                              | -                          | Remove a skill entirely                    |
| `write_file`  | `name`, `file_path`, `file_content` | -                          | Add/overwrite a file inside the skill      |
| `remove_file` | `name`, `file_path`                 | -                          | Delete a file from within the skill        |

### Python API Reference

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.skills import SkillManager

mgr = SkillManager()
mgr.discover()

# Create new skills
result = mgr.create_skill("weekly-summary", "# Weekly Summary\nSteps...", category="reporting")

# Edit existing skills
result = mgr.edit_skill("weekly-summary", "# Weekly Summary v2\n...")

# Apply targeted patches
result = mgr.patch_skill("weekly-summary", old_string="v2", new_string="v3")

# Manage skill files
result = mgr.write_skill_file("weekly-summary", "scripts/report.py", "print('Weekly report')")
result = mgr.remove_skill_file("weekly-summary", "scripts/report.py")

# Delete skills
result = mgr.delete_skill("weekly-summary")
```

### Security Guards

| Guard               | Purpose                     | Implementation                                          |
| ------------------- | --------------------------- | ------------------------------------------------------- |
| **Size Limits**     | Prevent resource exhaustion | 100KB SKILL.md, 1MB files                               |
| **Name Validation** | Secure identifiers          | `[a-z0-9][a-z0-9._-]*` pattern, 64 char limit           |
| **Path Validation** | Prevent traversal           | Block `..`, absolute paths, encoded attacks             |
| **Atomic Writes**   | Prevent corruption          | Temp file + rename operations                           |
| **Allowed Subdirs** | Restrict file placement     | `references/`, `templates/`, `scripts/`, `assets/` only |

***

## Common Patterns

### User Teaching Flow

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Typical interaction where agent learns from user
agent = Agent(
    name="Learning Assistant", 
    instructions="""
    When users teach you something new, save it as a skill.
    Use skill_manage to create persistent knowledge.
    """,
    tools=["skill_manage", "skills_list", "skill_view"]
)

# User: "Here's how to analyze CSV data: load with pandas, clean nulls, then summarize"
# Agent automatically calls:
# skill_manage(action="create", name="csv-analysis", 
#              content="# CSV Analysis\n1. Load with pandas\n2. Clean nulls\n3. Summarize data")
```

### Skill Evolution

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Agent improves existing skills based on feedback
# User: "The CSV skill should also handle missing headers"
# Agent calls:
# skill_manage(action="patch", name="csv-analysis", 
#              old_string="2. Clean nulls", 
#              new_string="2. Handle missing headers\n3. Clean nulls")
```

### Adding Executable Resources

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Agent creates supporting scripts for skills
# skill_manage(action="write_file", name="csv-analysis",
#              file_path="scripts/analyze.py", 
#              file_content="import pandas as pd\n# Analysis script...")
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Security-First Design">
    All skill operations are workspace-contained and use atomic writes via temp files. Never bypass name validation or path checks. Skills inherit workspace security automatically.
  </Accordion>

  <Accordion title="Progressive Learning">
    Start with simple skills and let agents enhance them through patch operations. This creates more natural learning patterns than full rewrites.
  </Accordion>

  <Accordion title="Skill Organization">
    Use meaningful categories and names. Skills are stored in `~/.praisonai/skills/` by default, with clean directory structure per skill.
  </Accordion>

  <Accordion title="Error Handling">
    All skill operations return detailed JSON results with success flags and error messages. Always check `result["success"]` before proceeding.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Skills (Concepts)" icon="puzzle-piece" href="/docs/concepts/skills">
    Understanding what skills are and how they work
  </Card>

  <Card title="Workspace" icon="folder-lock" href="/docs/features/workspace">
    How workspace containment secures skill operations
  </Card>
</CardGroup>