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

​
Quick Start

1

Enable Skill Management

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.")
2

Agent Learns and Improves

# 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="...")

​
How It Works

The skill management system provides six core actions for runtime skill manipulation:
ActionPurposeSecurity Constraints
createCreate new skills100KB SKILL.md limit, name validation
editReplace skill contentPreserves frontmatter, atomic writes
patchTargeted find/replaceString matching, traversal protection
deleteRemove skills completelyPath validation, atomic removal
write_fileAdd skill resources1MB limit, allowed subdirs only
remove_fileDelete skill filesContainment checks, safe removal

​
Configuration Options

​
Skill Management Actions

ActionRequired ArgsOptional ArgsWhat it does
createname, contentcategoryCreate a new skill with SKILL.md body
editname, content-Replace an existing skill’s SKILL.md body
patchname, old_string, new_stringfile_path, replace_allFuzzy find-and-replace within a skill file
deletename-Remove a skill entirely
write_filename, file_path, file_content-Add/overwrite a file inside the skill
remove_filename, file_path-Delete a file from within the skill

​
Python API Reference

All skill management methods return a consistent response format: Success Response: 
{"success": True, "skill": "skill-name", ...}  # Additional fields vary by method
Failure Response: 
{"success": False, "error": "Error message"}
Method Examples: 
from praisonaiagents.skills import SkillManager

mgr = SkillManager()
mgr.discover()

# Create new skills
result = mgr.create_skill("weekly-summary", "# Weekly Summary\nSteps...", category="reporting")
# Returns: {"success": True, "skill": "weekly-summary", "path": "/path/to/skill"}
# Or: {"success": False, "error": "Invalid skill name"}

# Edit existing skills
result = mgr.edit_skill("weekly-summary", "# Weekly Summary v2\n...")
# Returns: {"success": True, "skill": "weekly-summary"}
# Or: {"success": False, "error": "Skill not found"}

# Apply targeted patches
result = mgr.patch_skill("weekly-summary", old_string="v2", new_string="v3")
# Returns: {"success": True, "skill": "weekly-summary", "replacements": 1}
# Or: {"success": False, "error": "String not found"}

# Manage skill files
result = mgr.write_skill_file("weekly-summary", "scripts/report.py", "print('Weekly report')")
# Returns: {"success": True, "skill": "weekly-summary", "file": "scripts/report.py"}
# Or: {"success": False, "error": "File path must be under: ['references', 'templates', 'scripts', 'assets']"}

result = mgr.remove_skill_file("weekly-summary", "scripts/report.py")
# Returns: {"success": True, "skill": "weekly-summary", "file": "scripts/report.py"}
# Or: {"success": False, "error": "File not found"}

# Delete skills
result = mgr.delete_skill("weekly-summary")
# Returns: {"success": True, "skill": "weekly-summary", "path": "/path/to/skill"}
# Or: {"success": False, "error": "Skill not found"}

​
Security Guards

GuardPurposeImplementation
Size LimitsPrevent resource exhaustion100KB SKILL.md, 1MB files
Name ValidationSecure identifiers[a-z0-9][a-z0-9._-]* pattern, 64 char limit
Path ValidationPrevent traversalBlock .., absolute paths, encoded attacks
Atomic WritesPrevent corruptionTemp file + rename operations
Allowed SubdirsRestrict file placementreferences/, templates/, scripts/, assets/ only

​
Storage Location & Precedence

Skills are stored in directories according to this precedence order (highest to lowest):
  1. Project: ./.praisonai/skills/ (centralized) — and ./.claude/skills/ for compatibility
  2. Ancestor walk: any .praisonai/skills or .claude/skills in parent directories (monorepo support)
  3. User: ~/.praisonai/skills/
  4. System (Unix): /etc/praison/skills/
When creating new skills, they are written to the first existing directory in this list. If none exist, the system falls back to creating ~/.praisonai/skills/.
The current documentation incorrectly states that skills are stored “in ~/.praisonai/skills/ by default”. This is only the fallback location, not the actual default behavior.

​
Validation Rules

Each skill management operation enforces security constraints:
OperationValidation Rules
create_skill/edit_skillName: ^[a-z0-9][a-z0-9._-]*$, ≤64 chars
Content: ≤100KB
patch_skillPath traversal protection (.., absolute paths)
String must exist in target file
write_skill_fileFile size: ≤1MB
Allowed subdirs: references/, templates/, scripts/, assets/ only
Path traversal protection
remove_skill_filePath must be within skill directory
File must exist
delete_skillSkill must exist and have valid path

​
Common Patterns

​
Complete Agent Learning Example

# Real agent-centric example you can copy and run
from praisonaiagents import Agent

agent = Agent(
    name="Learning Assistant",
    instructions="When users teach you something, save it as a persistent skill using skill_manage.",
    tools=["skill_manage", "skills_list", "skill_view"]
)

# User teaches the agent
response = agent.start("Here's how to analyze CSV files: load with pandas, check for nulls, then create summary stats")

# Agent automatically calls:
# skill_manage(action="create", name="csv-analysis", content="# CSV Analysis\n1. Load with pandas...")
# Response: {"success": True, "skill": "csv-analysis", "path": "/path/to/skill"}

print("Agent learned and persisted the skill!")

​
User Teaching Flow

# 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

# 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

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

​
Troubleshooting

ImportError Fix: If you see ImportError: cannot import name 'get_default_skill_directories', upgrade praisonaiagents — this was fixed in MervinPraison/PraisonAI#1687. The function was renamed from get_default_skill_directories to get_default_skill_dirs.

​
Best Practices

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.
Start with simple skills and let agents enhance them through patch operations. This creates more natural learning patterns than full rewrites.
Use meaningful categories and names. Skills are stored according to directory precedence (see Storage Location above), with clean directory structure per skill.
All skill operations return detailed JSON results with success flags and error messages. Always check result["success"] before proceeding.

Skills (Concepts)

Understanding what skills are and how they work

Workspace

How workspace containment secures skill operations