Praison AI

Agent

Create, list, and inspect file-based custom agent definitions

Manage custom agents discovered from .praisonai/agents/ (and .claude/agents/ / .agents/agents/ when present) — author them with create, then list and inspect with list / show. Distinct from praisonai agents (the multi-agent UI command).

Commands

bash
praisonai agent create <name> [--describe TEXT] [--model TEXT] [--permission PRESET] [--global] [--force] [--yes]
praisonai agent list [--verbose]
praisonai agent show <name>
CommandDescription
create <name>Author a new custom agent definition (interactive or scriptable)
listShow Name, Source (user/project), Model
list --verboseAlso Path and Role
show <name>Agent details, system prompt, tools

create

Turn a one-line description into a permission-scoped .praisonai/agents/<name>.md — no editor round-trip.

Diagram

📝 –describe

🔒 validate name

🧠 draft system prompt

💾 write .md

🔁 re-parse

✅ next steps

  1. Interactive

    Run create with no flags and answer the four prompts (name, description, permission, model).

    bash
    praisonai agent create
    Agent name: reviewer
Describe what it does: Reviews diffs and suggests improvements
Permission [read-only/review/full] (full): read-only
Model (gpt-4o-mini):
✅ Created .praisonai/agents/reviewer.md
ℹ You can now run:
ℹ   praisonai run --agent reviewer "..."
  2. Non-interactive / CI

    Pass every value as a flag and add --yes to skip prompts — scriptable for CI.

    bash
    praisonai agent create code-reviewer -d "Reviews diffs and suggests improvements" -p read-only -m gpt-4o-mini --yes
    ✅ Created .praisonai/agents/code-reviewer.md
ℹ You can now run:
ℹ   praisonai run --agent code-reviewer "..."

    The resulting .praisonai/agents/code-reviewer.md:

    markdown
    ---
model: gpt-4o-mini
role: Code Reviewer
goal: Reviews diffs and suggests improvements
mode: read-only
---
You are a careful code reviewer. Review the diff for correctness, ...

    role is derived from the name (code-reviewer → Code Reviewer): _ and - become spaces, then title-cased. goal is your --describe text.

  3. Global (user-wide)

    Add --global to write to ~/.praisonai/agents/<name>.md instead of the project directory.

    bash
    praisonai agent create researcher --global -d "Researches topics and summarises findings" --yes

    If a same-named project agent already exists, a shadow warning fires — the project-local definition wins for run.

Flags

FlagShortTypeDefaultDescription
NAME (positional)—str—File stem for .praisonai/agents/<name>.md. Required — prompted for if missing in interactive mode. Path-unsafe names rejected.
--describe-dstr—One-line description of what the agent should do. Fed to the system-prompt drafter and becomes goal: in frontmatter. Prompted interactively; defaults to "A helpful <name> agent." under --yes if omitted.
--model-mstrautoModel to use. Defaults to the provider init/run/setup detect (silent, no persist). Interactive mode shows the detected default.
--permission-p`read-only \review \full`fullPermission preset mapped to a mode: frontmatter value. Rejected if not a known preset (exit 1).
--global—flagfalseWrite to ~/.praisonai/agents/<name>.md (user-global) instead of <repo>/.praisonai/agents/<name>.md.
--force-fflagfalseOverwrite an existing agent definition. Without it, exits 1 with “Agent already exists”.
--yes-yflagfalseNon-interactive: accept defaults, skip all prompts.

Permission presets

Presets reuse the same mode: grammar the runtime already understands — no parallel vocabulary.

Presetmode: frontmatterGrants
read-onlyread-onlyReads allowed; edits, writes, and shell denied
reviewreviewReads allowed; edits/writes denied; shell asks first
full(omitted)Full toolset — absence of mode: is the default

full deliberately omits mode: to keep files minimal. See Custom Agents & Commands → Scoping permissions for the full grammar.

Behaviour worth knowing

System prompt drafting is best-effort

The system prompt is drafted via the same Agent.run path as init --generate. On any failure, drafting degrades to an editable stub (“Describe how you should behave here”), prints a warning, and still writes the file with exit code 0. Edit the stub in place.

Path-safe names only

validate_agent_name rejects empty names, ., .., and any name containing / or \ — so every write stays inside the chosen agents directory. Invalid names exit 1 before any LLM call, so failure is cheap.

full omits mode:

--permission full writes no mode: key. Absence of mode: means the full toolset — the runtime’s default — so files stay minimal.

Shadow warning on –global

After writing, the CLI re-parses the exact file it wrote, then checks the precedence-resolved definition. If a higher-precedence (project-local) agent of the same name would win for run, it prints: “Another ‘{name}’ agent takes precedence for ‘run’: {other-path}.” Rename this agent or remove the other to use it directly.

–force overwrites in place

Without --force, create refuses to touch an existing file and exits 1. With --force, it overwrites in place.

After a successful create, run the exact line the CLI prints:

bash
praisonai run --agent code-reviewer "review the latest diff"

See praisonai run for the full runtime surface.

list

Show discovered agents with their source and model.

bash
praisonai agent list
praisonai agent list --verbose

show

Inspect a single agent’s details, system prompt, and tools.

bash
praisonai agent show researcher

Related

Custom Agents & Commands

Define agents from Markdown

 Run

Run with –agent

 Init

Scaffold a starter project in one command

 Agent Presets & Modes

The mode: shorthand behind permission presets