> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agent create [--describe TEXT] [--model TEXT] [--permission PRESET] [--global] [--force] [--yes] praisonai agent list [--verbose] praisonai agent show ``` | Command | Description | | ---------------- | ---------------------------------------------------------------- | | `create ` | Author a new custom agent definition (interactive or scriptable) | | `list` | Show Name, Source (user/project), Model | | `list --verbose` | Also Path and Role | | `show ` | Agent details, system prompt, tools | ## create Turn a one-line description into a permission-scoped `.praisonai/agents/.md` — no editor round-trip. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR D[📝 --describe] --> V[🔒 validate name] V --> P[🧠 draft system prompt] P --> W[💾 write .md] W --> R[🔁 re-parse] R --> N[✅ next steps] classDef input fill:#6366F1,stroke:#7C90A0,color:#fff classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff classDef result fill:#10B981,stroke:#7C90A0,color:#fff class D input class V,P,W,R process class N result ``` Run `create` with no flags and answer the four prompts (name, description, permission, model). ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 "..." ``` Pass every value as a flag and add `--yes` to skip prompts — scriptable for CI. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} --- 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. Add `--global` to write to `~/.praisonai/agents/.md` instead of the project directory. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 | Flag | Short | Type | Default | Description | | ------------------- | ----- | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NAME` (positional) | — | `str` | — | File stem for `.praisonai/agents/.md`. Required — prompted for if missing in interactive mode. Path-unsafe names rejected. | | `--describe` | `-d` | `str` | — | 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 agent."` under `--yes` if omitted. | | `--model` | `-m` | `str` | *auto* | Model 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` | `full` | Permission preset mapped to a `mode:` frontmatter value. Rejected if not a known preset (exit `1`). | | `--global` | — | flag | `false` | Write to `~/.praisonai/agents/.md` (user-global) instead of `/.praisonai/agents/.md`. | | `--force` | `-f` | flag | `false` | Overwrite an existing agent definition. Without it, exits `1` with *"Agent already exists"*. | | `--yes` | `-y` | flag | `false` | Non-interactive: accept defaults, skip all prompts. | ### Permission presets Presets reuse the same `mode:` grammar the runtime already understands — no parallel vocabulary. | Preset | `mode:` frontmatter | Grants | | ----------- | ------------------- | ---------------------------------------------------- | | `read-only` | `read-only` | Reads allowed; edits, writes, and shell denied | | `review` | `review` | Reads 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](/docs/docs/features/custom-agents-commands#scoping-permissions) for the full grammar. ### Behaviour worth knowing 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. `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. `--permission full` writes no `mode:` key. Absence of `mode:` means the full toolset — the runtime's default — so files stay minimal. 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. Without `--force`, `create` refuses to touch an existing file and exits `1`. With `--force`, it overwrites in place. Names must be path-safe. `../foo`, `a/b`, `a\b`, `/abs`, `.`, and `..` are all rejected before any model call. Prefer `praisonai agent create` for a single, focused agent; use [`praisonai init`](/docs/cli/init) when you also want starter commands and tools next to it. See [Custom Agents & Commands](/docs/features/custom-agents-commands) for the full definition format. After a successful create, run the exact line the CLI prints: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai run --agent code-reviewer "review the latest diff" ``` See [`praisonai run`](/docs/cli/run) for the full runtime surface. ## list Show discovered agents with their source and model. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agent list praisonai agent list --verbose ``` ## show Inspect a single agent's details, system prompt, and tools. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai agent show researcher ``` No agents yet? Run [`praisonai agent create`](#create) for the shortest path to a single custom agent, or [`praisonai init`](/docs/cli/init) to scaffold a full starter project in `.praisonai/`. ## Related Define agents from Markdown Run with --agent Scaffold a starter project in one command The mode: shorthand behind permission presets