Skip to main content
from praisonaiagents import Agent

agent = Agent(name="custom-cmd-agent", instructions="Handle custom /commands in chat.")
agent.start("Register /summarise as a custom command that summarises the chat.")
Drop Markdown or YAML files into .praisonai/agents/ and .praisonai/commands/ to extend the CLI without writing Python. The user runs praisonai run --agent researcher; discovery loads custom agents and slash commands from .praisonai/.

​
How It Works

​
Quick Start

Skip the boilerplate — praisonai init scaffolds a working .praisonai/ with a starter agent and command, then read on to customise.
praisonai init
1

Create an agent file

<!-- .praisonai/agents/researcher.md -->
---
model: gpt-4o
role: Research Specialist
tools:
  - web_search
---

You are an expert researcher. Provide concise, cited answers.
2

Run the agent

praisonai run --agent researcher "What's new in WebAssembly 3.0?"
3

Create a command file

<!-- .praisonai/commands/summarise.md -->
---
description: Summarise text
---

Summarise the following in three bullet points:

$ARGUMENTS
4

Run the command

praisonai run --command summarise "Long article text here..."

​
How discovery works

LocationScope
~/.praisonai/agents/ / commands/User-global
./.praisonai/agents/ / commands/Project (walks up to git root)
Project definitions override user definitions on name collision.

​
Agent definitions

Files: .praisonai/agents/*.md or *.yaml
FieldDescription
modelLLM model
toolsTool list
roleAgent role
goalAgent goal
instructionsSystem instructions
modeCoarse permission shorthand: build, read-only, plan, review
permissionPer-capability allow / deny / ask rules
Markdown bodyBecomes system_prompt when no instructions field

​
Scoping permissions

Three built-in agents (build, plan, review) are available without any file — see Agent Presets & Modes.
Add mode: to a definition for instant read-only or review scoping: 
---
name: reviewer
mode: read-only
---
You are a meticulous code reviewer…
For finer control, use the permission: block: 
---
name: git-assistant
permission:
  bash:
    "git *": ask
    "*": deny
  read: allow
---
You are a git-aware assistant.
See Agent Presets & Modes for the full modes reference, permission syntax, and precedence rules.

​
Command templates

Files: .praisonai/commands/*.md
PatternBehaviour
$ARGUMENTSReplaced with user input
@path/to/fileInlines file contents
!`cmd`Opt-in live shell substitution — runs cmd and inlines stdout
$(shell cmd)Escaped — not executed (safety)

​
Opt-in live shell substitution

!`cmd` is disabled by default. Enable with any one of:
  1. PRAISONAI_ALLOW_SHELL=true environment variable
  2. commands.allow_shell: true in .praisonai/config.yaml
  3. Per-command frontmatter allow_shell: true
---
name: review
allow_shell: true
---
Review this diff:

!`git diff --stat`
Safety bounds: 30s timeout, 100KB max stdout, runs in the template’s working directory. Non-zero exit raises ShellSubstitutionError. !`cmd` inside $ARGUMENTS or @file contents is never executed — only markers in the original template run.

​
Agent vs command vs skill vs rule

​
Slash commands

Custom commands auto-register in interactive mode as CommandKind.CUSTOM. Disable with SlashCommandHandler(discover_custom=False). Custom commands appear automatically in Telegram / Discord / autocomplete when your bot restarts, filtered by the same CommandAccessPolicy that gates execution. See Native / Autocomplete.

​
Inside praisonai code too

The same .praisonai/commands/*.md files work as /name inside praisonai code, the REPL, and the async TUI. A unified CommandRegistry aggregates built-ins, your custom commands, skills, MCP prompts, and pip-installed praisonai.commands packs into one namespace: 
> /mydeploy staging
This runs the exact interpolated template that praisonai run --command mydeploy staging would — byte-for-byte parity between interactive and CLI. See Slash Commands → Unified Command Registry.

​
Python API

from praisonai.cli.features.custom_definitions import (
    load_agent_from_name,
    interpolate_command_template,
)

config = load_agent_from_name("researcher")
prompt = interpolate_command_template("summarise", "Long text...")

​
Best Practices

Commit .praisonai/agents/ and .praisonai/commands/ to git.
Use ~/.praisonai/ for personal shortcuts that should not override team agents.
!`cmd` requires an explicit opt-in gate (allow_shell: true, config, or PRAISONAI_ALLOW_SHELL). $(...) is always escaped — use !`cmd` only when you need live output like git diff.
Run praisonai init to scaffold .praisonai/agents/ and .praisonai/commands/ before hand-writing files.

Run CLI

—agent and —command flags

Agent CLI

List and inspect custom agents

Command CLI

List and preview commands

Slash Commands

Interactive custom commands

Init CLI

Scaffold .praisonai/ in one command

Agent Presets & Modes

Built-in presets and per-agent permission scoping