docs: Document workspace sandboxing, self-improving skills, and expanded bot default tools (PraisonAI PR #1503)

[MervinPraison]

Context

PraisonAI PR #1503 was merged into main (commit 9386823). It brings bots/gateways up to parity with modern agent frameworks by adding:

• Workspace sandboxing (new module praisonaiagents.workspace)
• Self-improving skill management (write API on SkillManager + skill_manage tool)
• 20+ expanded bot default tools (files, planning, skills, delegation, session)

These are user-facing features that agents use automatically when deployed as a bot. No end-user documentation exists yet for them. This issue defines exactly what needs to be created/updated and provides SDK source references so a follow-up agent can implement the docs per AGENTS.md.

Important

Per AGENTS.md folder-placement rules, all new pages below MUST be created under docs/features/, never docs/concepts/ (concepts is human-approved only). docs.json entries go under the Features group.

---

Summary of SDK Changes

Area	SDK File	Change
Workspace	praisonaiagents/workspace/__init__.py	NEW — Workspace dataclass, path containment, access modes
Bot config	praisonaiagents/bots/config.py	UPDATED — workspace_dir, workspace_access, workspace_scope, expanded default_tools
Skill manager	praisonaiagents/skills/manager.py	UPDATED — create_skill, edit_skill, patch_skill, delete_skill, write_skill_file, remove_skill_file
Skill tool	praisonaiagents/tools/skill_tools.py	UPDATED — new skill_manage, skills_list, skill_view functions
Todo tools	praisonaiagents/tools/todo_tools.py	NEW — todo_add, todo_list, todo_update
Edit tools	praisonaiagents/tools/edit_tools.py	NEW — edit_file, search_files (fuzzy find/replace)
File tools	praisonaiagents/tools/file_tools.py	UPDATED — workspace-aware factory create_file_tools(workspace=...)
Session tools	praisonaiagents/tools/session_tools.py	NEW (stub) — session_search (placeholder, honest empty result)
Delegation tools	praisonaiagents/tools/delegation_tools.py	NEW (stub) — delegate_task (placeholder)
Bot smart defaults	praisonai/bots/_defaults.py	UPDATED — auto-injects workspace + 20+ tools when agent has none

---

Documentation Plan

Each page below uses the standard template from AGENTS.md: frontmatter, hero Mermaid diagram (standard color scheme), Quick Start with <Steps>, How It Works, Configuration Options table, Common Patterns, Best Practices with <AccordionGroup>, Related <CardGroup>.

All examples must be agent-centric (open with an Agent(...) snippet), beginner-friendly, and use simple imports like from praisonaiagents import Agent.

---

1. NEW — docs/features/workspace.mdx

Why: Workspace sandboxing is brand-new and has zero documentation.

Frontmatter:

---
title: "Workspace"
sidebarTitle: "Workspace"
description: "Sandbox agent file operations inside a safe, per-session directory"
icon: "folder-lock"
---

Agent-centric opening example (Quick Start Step 1):

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(
    name="Assistant",
    instructions="You help users with files and tasks"
)

# Workspace is applied automatically when agent runs as a bot
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

Quick Start Step 2 — Custom workspace:

from praisonaiagents import Agent
from praisonai.bots import TelegramBot
from praisonaiagents.bots import BotConfig

config = BotConfig(
    token="YOUR_TOKEN",
    workspace_dir="./my-bot-workspace",  # custom path
    workspace_access="rw",                # "rw" | "ro" | "none"
    workspace_scope="session",            # "shared" | "session" | "user" | "agent"
)

bot = TelegramBot(config=config, agent=agent)

Hero Mermaid diagram:

graph LR
    subgraph "Workspace Sandbox"
        A[🤖 Agent] --> T[🛠️ File Tools]
        T --> W[📁 Workspace Root]
        W --> OK[✅ Inside = Allowed]
        W --> NO[🚫 Outside = Rejected]
    end
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef safe fill:#10B981,stroke:#7C90A0,color:#fff
    classDef danger fill:#F59E0B,stroke:#7C90A0,color:#fff
    class A agent
    class T,W tool
    class OK safe
    class NO danger

Loading

Access-mode decision diagram (to help users pick):

graph TD
    Q1["What should the agent do with files?"]
    Q1 -->|"Read AND write"| RW["rw (default)"]
    Q1 -->|"Only read"| RO["ro"]
    Q1 -->|"Isolated scratch only"| NONE["none (sandbox)"]
    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef a fill:#10B981,stroke:#7C90A0,color:#fff
    class Q1 q
    class RW,RO,NONE a

Loading

Configuration options table (extract exactly from praisonaiagents/workspace/__init__.py):

Option	Type	Default	Description
root	Path	required	Absolute workspace directory (auto-created; refuses /)
access	"rw", "ro", "none"	"rw"	Read-write, read-only, or copy-on-write sandbox
scope	"shared", "session", "user", "agent"	"session"	Workspace scope level
session_key	Optional[str]	None	Session identifier for scope resolution

BotConfig fields (from praisonaiagents/bots/config.py):

Option	Type	Default	Description
workspace_dir	Optional[str]	None → ~/.praisonai/workspaces/<scope>/<session_key>	Override workspace path
workspace_access	str	"rw"	Access mode
workspace_scope	str	"session"	Scope level

Must cover:

• Why workspaces exist (security by construction, path-traversal protection, macOS symlink safety)
• The four scope modes (shared / session / user / agent) and when to use each
• That file tools fall back to os.getcwd() when no workspace is configured (backward compatibility)
• Workspace.contains(path) and Workspace.resolve(path) usage for advanced users
• Default path layout: ~/.praisonai/workspaces/<scope>/<session_key>/

Related cards: BotOS, Skills (Manage), Bot Default Tools

---

2. NEW — docs/features/skill-manage.mdx (self-improving skills)

Why: The skill_manage write API + SkillManager write methods are entirely new. Existing docs/concepts/skills.mdx and docs/features/skills.mdx only cover reading/loading skills, not creating/editing them at runtime.

Frontmatter:

---
title: "Self-Improving Skills"
sidebarTitle: "Skill Manage"
description: "Let agents create, edit, and patch their own skills at runtime"
icon: "wand-magic-sparkles"
---

Agent-centric opening:

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

Hero diagram — the self-improving loop:

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

Loading

Actions table — document every action in skill_manage (from praisonaiagents/tools/skill_tools.py::skill_manage):

Action	Required args	What it does
create	name, content, optional 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, optional 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 (e.g. scripts/run.py)
remove_file	name, file_path	Delete a file from within the skill

Python-level API (from praisonaiagents/skills/manager.py):

from praisonaiagents.skills import SkillManager

mgr = SkillManager()
mgr.discover()

mgr.create_skill("weekly-summary", "# Weekly Summary\nSteps...", category="reporting")
mgr.edit_skill("weekly-summary", "# Weekly Summary v2\n...")
mgr.patch_skill("weekly-summary", old_string="v2", new_string="v3")
mgr.delete_skill("weekly-summary")

mgr.write_skill_file("weekly-summary", "scripts/report.py", "print('hi')")
mgr.remove_skill_file("weekly-summary", "scripts/report.py")

Must cover:

• Security guards: 100KB SKILL.md limit, 1MB file limit, atomic writes via temp files, name validation, path validation
• Why this matters: agents can teach themselves and persist knowledge across sessions
• Typical user interaction flow (example): user teaches agent a new workflow in chat → agent calls skill_manage(action="create", ...) → agent uses that skill on the next matching request
• How workspace containment applies (skill files are written under the workspace root)
• Link to docs/concepts/skills.mdx for what skills are

Related cards: Workspace, Skills (concepts), Bot Default Tools

---

3. NEW — docs/features/bot-default-tools.mdx

Why: BotConfig.default_tools now ships with 20+ tools auto-injected. Existing docs/concepts/bot-os.mdx mentions --memory --web flags only. Users need a single place that shows what a bot can do out of the box.

Frontmatter:

---
title: "Bot Default Tools"
sidebarTitle: "Bot Default Tools"
description: "The 20+ tools every bot gets automatically"
icon: "toolbox"
---

Agent-centric opening — "zero-config bot" with every superpower:

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(
    name="Assistant",
    instructions="You help users. Use any tool you need."
)

# No tools= passed — bot auto-injects safe defaults
TelegramBot(token="YOUR_TOKEN", agent=agent).start()

Hero diagram — tool categories:

graph TB
    subgraph "Auto-Injected Bot Tools"
        BOT[🤖 Bot]
        BOT --> FILE[📁 Files<br/>read/write/edit/list/search]
        BOT --> PLAN[📋 Planning<br/>todo_add/list/update]
        BOT --> SKILL[🧠 Skills<br/>skill_manage/list/view]
        BOT --> WEB[🌐 Web<br/>search_web/web_crawl]
        BOT --> MEM[💾 Memory<br/>store/search memory & learning]
        BOT --> SCHED[⏰ Schedule<br/>schedule_add/list/remove]
    end
    classDef bot fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef cat fill:#189AB4,stroke:#7C90A0,color:#fff
    class BOT bot
    class FILE,PLAN,SKILL,WEB,MEM,SCHED cat

Loading

Full default tool table (extract verbatim from BotConfig.default_tools in praisonaiagents/bots/config.py):

Tool	Category	Safe without workspace?	Notes
search_web	Web	✅	Existing
web_crawl	Web	✅	Existing
store_memory	Memory	✅	Existing
search_memory	Memory	✅	Existing
store_learning	Learning	✅	Existing
search_learning	Learning	✅	Existing
schedule_add	Scheduling	✅	Existing
schedule_list	Scheduling	✅	Existing
schedule_remove	Scheduling	✅	Existing
clarify	Clarification	✅	Existing
read_file	Files	✅ (read-only)	NEW — workspace-scoped
write_file	Files	⚠️ requires workspace	NEW
edit_file	Files	⚠️ requires workspace	NEW
list_files	Files	✅	NEW
search_files	Files	✅	NEW
todo_add	Planning	✅	NEW
todo_list	Planning	✅	NEW
todo_update	Planning	✅	NEW
skills_list	Skills	✅	NEW
skill_view	Skills	✅	NEW
skill_manage	Skills	⚠️ requires workspace	NEW

Opt-in (not auto-injected): delegate_task, session_search — both are stub implementations right now and return honest "not configured" errors. Document this clearly so users aren't surprised.

Customising defaults:

from praisonaiagents.bots import BotConfig

config = BotConfig(
    token="YOUR_TOKEN",
    default_tools=["search_web", "read_file", "todo_add"],  # override list
    auto_approve_tools=True,  # default True for bots
)

Must cover:

• How smart defaults work (agent has no tools → bot auto-injects safe defaults from apply_bot_smart_defaults)
• How to disable: explicitly pass tools=[] (bot respects _explicit_empty_tools)
• Relationship with workspace: destructive file tools (write_file, edit_file, skill_manage) are filtered out unless a workspace is configured
• auto_approve_tools flag (default True for bots because chat UIs can't show approval prompts)

Related cards: BotOS, Workspace, Tools

---

4. NEW — docs/features/todo-planning.mdx

Why: todo_tools.py is a brand-new module. Great for "agent-centric planning" per AGENTS.md principle (show how an agent uses todos in a real flow).

Frontmatter:

---
title: "Todo Planning"
sidebarTitle: "Todos"
description: "Let agents plan multi-step tasks with a persistent todo list"
icon: "list-check"
---

Agent-centric Quick Start:

from praisonaiagents import Agent

agent = Agent(
    name="Planner",
    instructions="Break tasks into todos, then execute them one by one.",
    tools=["todo_add", "todo_list", "todo_update"]
)

agent.start("Plan a blog launch — research, draft, publish.")

User interaction flow diagram:

sequenceDiagram
    participant U as 👤 User
    participant A as 🤖 Agent
    participant T as 📋 Todos
    U->>A: "Plan a blog launch"
    A->>T: todo_add("research topic")
    A->>T: todo_add("draft post")
    A->>T: todo_add("publish")
    A->>T: todo_list()
    T-->>A: 3 pending todos
    A->>T: todo_update(1, status="completed")
    A-->>U: "Done ✅ — moving to drafting"

Loading

Parameters table (from praisonaiagents/tools/todo_tools.py):

Function	Args	Notes
todo_add	task, priority="medium", category="general"	Priority: low/medium/high
todo_list	status="all", category=None	Status filter: all/pending/completed/cancelled
todo_update	todo_id, status, task, priority	Update any combination

Must cover:

• Persistence: todos are stored at <workspace.root>/todos.json (or ~/.praisonai/todos.json without workspace)
• Use as a planning primitive for longer-horizon tasks
• How it combines with skill_manage and file tools

---

5. NEW — docs/features/file-editing.mdx

Why: edit_tools.py (edit_file, search_files) is new and workspace-aware. file_tools.py gained a create_file_tools(workspace=...) factory.

Frontmatter:

---
title: "File Editing"
sidebarTitle: "File Editing"
description: "Fuzzy find-and-replace across files, scoped to a workspace"
icon: "file-pen"
---

Must cover:

• edit_file(filepath, old_string, new_string, replace_all=False) — approval-gated at risk level high
• search_files(directory, pattern, file_pattern="*") — returns JSON with match locations
• read_file / write_file / list_files from file_tools.py
• Workspace scoping: destructive ops require a configured Workspace
• Error message for escaping the workspace: "Path escapes workspace: ..."

Agent-centric opening:

from praisonaiagents import Agent

agent = Agent(
    name="Code Editor",
    instructions="Edit code files carefully using fuzzy search and replace.",
    tools=["edit_file", "search_files", "read_file"]
)

---

6. UPDATE — docs/features/skills.mdx

Why: Current file covers reading/loading skills. Needs a new section pointing to the new "Self-Improving Skills" page.

Add to the existing file:

• A "Managing skills at runtime" sub-section with a short blurb + CardGroup link to the new docs/features/skill-manage.mdx
• Note that skills_list and skill_view are now tools agents can call directly

Do NOT touch docs/concepts/skills.mdx — it is in the human-only folder.

---

7. UPDATE — docs.json

Add the new features pages under the Features group (never under Concepts). Expected entries:

"features/workspace",
"features/skill-manage",
"features/bot-default-tools",
"features/todo-planning",
"features/file-editing"

Verify docs.json stays valid JSON after editing.

---

Writing Rules Recap (from AGENTS.md)

For every page the follow-up agent writes:

• Open with a short (one-line) description; no filler intros
• Agent-centric code example at the very top
• Hero Mermaid diagram using the standard palette: #8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text, #7C90A0 stroke
• Simple imports only (from praisonaiagents import Agent), not deep subpaths
• <Steps> in Quick Start, <AccordionGroup> in Best Practices, <CardGroup> in Related
• Configuration tables extracted verbatim from the SDK files listed above
• Show a user-interaction flow diagram where there are choices (e.g. access modes, skill actions)
• No forbidden phrases ("As you can see…", "It's important to note…", etc.)
• Pages live under docs/features/ — never docs/concepts/
• Register pages in docs.json under the Features group

---

References

• PR: feat: workspace sandboxing + self-improving skill management + expanded bot toolset PraisonAI#1503
• Head SHA: 93868235518512d872cd72cbb6dc30d6a51a8928
• Issue it fixes: Feature: Bot/Gateway parity with hermes-agent + openclaw — expanded defaults, self-improving skill_manage, per-session workspace sandbox PraisonAI#1499

Exact SDK source files to read (in MervinPraison/PraisonAI at PR head)

• src/praisonai-agents/praisonaiagents/workspace/__init__.py
• src/praisonai-agents/praisonaiagents/bots/config.py
• src/praisonai-agents/praisonaiagents/skills/manager.py
• src/praisonai-agents/praisonaiagents/tools/skill_tools.py
• src/praisonai-agents/praisonaiagents/tools/todo_tools.py
• src/praisonai-agents/praisonaiagents/tools/edit_tools.py
• src/praisonai-agents/praisonaiagents/tools/file_tools.py
• src/praisonai-agents/praisonaiagents/tools/session_tools.py
• src/praisonai-agents/praisonaiagents/tools/delegation_tools.py
• src/praisonai/praisonai/bots/_defaults.py
• src/praisonai/praisonai/bots/bot.py

Remember: session_search and delegate_task are stubs — don't invent behaviour they don't have. Document them as planned/opt-in placeholders.

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude finished @MervinPraison's task —— View job • claude/issue-232-20260422-1654 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-232-20260422-1654?quick_pull=1&title=Issue%20%23232%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23232%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Documentation Implementation for PraisonAI Features ✅

Successfully implemented comprehensive documentation for workspace sandboxing, self-improving skills, and expanded bot default tools from PraisonAI PR #1503.

Completed Tasks:

• Setup git identity and authentication
• Read AGENTS.md for documentation guidelines
• Clone and read PraisonAI SDK source files for API details
• Create docs/features/workspace.mdx
• Create docs/features/skill-manage.mdx
• Create docs/features/bot-default-tools.mdx
• Create docs/features/todo-planning.mdx
• Create docs/features/file-editing.mdx
• Update docs/features/skills.mdx
• Update docs.json navigation
• Verify all files and commit changes
• Push and create pull request

📋 Summary

Created 5 new comprehensive documentation pages covering:

📁 Workspace Sandboxing - Secure file operation containment with access modes and scope management
🧠 Self-Improving Skills - Runtime skill creation, editing, and management for agent learning
🛠️ Bot Default Tools - 20+ auto-injected tools with smart workspace-aware filtering
📋 Todo Planning - Multi-step task management with persistent todo lists
✏️ File Editing - Fuzzy find-and-replace operations with workspace security

All documentation follows AGENTS.md standards with agent-centric examples, standardized Mermaid diagrams, and proper Mintlify components.

🔗 Pull Request

PR #234: Document workspace sandboxing, self-improving skills, and expanded bot default tools

Ready for review and merge!

--- |