> ## 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.
# Create Custom Agents
> Author a permission-scoped custom agent from one line of description — interactive or scriptable.
`praisonai agent create` writes a ready-to-run custom agent from a single line of description.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Create a Custom Agent"
Desc[📝 One-line description] --> Draft[🧠 LLM drafts prompt]
Draft --> Write[💾 Write .praisonai/agents/name.md]
Write --> Ready[✅ praisonai run --agent name]
end
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 Desc input
class Draft,Write process
class Ready result
```
## Quick Start
Run the command with no arguments and answer the prompts:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create
```
You'll see:
```
$ praisonai agent create
Agent name: code-reviewer
Describe what this agent does: Review PRs and suggest improvements
Permission preset [full/read-only/review] (full): read-only
Model (gpt-4o-mini):
Created .praisonai/agents/code-reviewer.md
You can now run:
praisonai run --agent code-reviewer "..."
```
Pass every answer as a flag and skip the prompts with `--yes`:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create code-reviewer \
--describe "Review pull requests and suggest improvements" \
--model gpt-4o-mini \
--permission read-only \
--yes
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run --agent code-reviewer "Review the diff on this branch"
```
***
## Which preset should I pick?
Presets map to the `mode` frontmatter that scopes what the agent may do.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{What should this agent do?}
Q -->|Only read/analyse| RO[read-only]
Q -->|Read + suggest, no writes| RV[review]
Q -->|Full authoring, edits, tools| FU[full]
classDef question fill:#6366F1,stroke:#7C90A0,color:#fff
classDef preset fill:#10B981,stroke:#7C90A0,color:#fff
class Q question
class RO,RV,FU preset
```
| Preset | Written `mode` | Effect |
| ----------- | ----------------- | --------------------------------------------------------------------------------- |
| `read-only` | `mode: read-only` | Denies edits and writes — safe for reviewers and analysts. |
| `review` | `mode: review` | Read plus inspection with a limited action surface. |
| `full` | *omitted* | Full toolset — `mode` is left out so the file stays minimal (absence means full). |
Interactive default is `full`. For anything that reviews code, choose `read-only` explicitly.
***
## How It Works
The command drafts a system prompt, writes the file, then re-parses it to confirm discovery can read it back.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI as praisonai agent create
participant LLM
participant FS as .praisonai/agents/
participant Disc as Discovery
User->>CLI: name + describe + permission
CLI->>LLM: draft system prompt (from describe)
LLM-->>CLI: prompt body (or fallback stub on failure)
CLI->>FS: write .md (frontmatter + body)
CLI->>Disc: re-parse file to validate
Disc-->>CLI: OK (or precedence warning)
CLI-->>User: praisonai run --agent "..."
```
The written file re-parses losslessly through discovery:
```md theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
model: gpt-4o-mini
role: Code Reviewer
goal: Review code and suggest improvements
mode: read-only
---
You are a careful code reviewer.
Describe your responsibilities and ask for clarification instead of guessing.
```
If the LLM draft fails, an editable stub is written instead — file creation is never blocked.
***
## Configuration Options
| Flag | Type | Description |
| -------------------- | -------- | -------------------------------------------------------------------------- |
| `NAME` | argument | File stem for `.praisonai/agents/.md`. Prompted if omitted. |
| `-d`, `--describe` | str | One-line description of what the agent should do. Drives the prompt draft. |
| `-m`, `--model` | str | Model to use. Defaults to your detected provider. |
| `-p`, `--permission` | str | Permission preset: `read-only`, `review`, or `full`. |
| `--global` | flag | Write to `~/.praisonai/agents/` instead of the project. |
| `-f`, `--force` | flag | Overwrite an existing agent definition. |
| `-y`, `--yes` | flag | Non-interactive: accept defaults and skip prompts. |
**Destination directories**
* Project (default): `/.praisonai/agents/.md`
* Global (`--global`): `~/.praisonai/agents/.md`
***
## Common Patterns
**Team of reviewers** — create three read-only reviewers, then run them together via subagents:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create security-reviewer --describe "Flag security issues in diffs" --permission read-only --yes
praisonai agent create perf-reviewer --describe "Flag performance regressions" --permission read-only --yes
praisonai agent create style-reviewer --describe "Flag style and readability nits" --permission read-only --yes
praisonai run --subagents security-reviewer,perf-reviewer,style-reviewer "Review this PR"
```
**Global helper across every project** — write to your home directory:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create commit-writer --describe "Write concise commit messages" --global --yes
```
**Overwrite an old definition** — pass `--force`; without it the command refuses and prints the exact path:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create code-reviewer --describe "Stricter review checklist" --force --yes
```
**Shadow warning** — a `--global` agent is shadowed when a project agent shares its name. The command warns and names the shadowing path so you don't `run` the wrong one. Resolve it by renaming or deleting one of the two files.
***
## Best Practices
The file omits `mode` for `full`, so an explicit `read-only` is the safest default for reviewers.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create code-reviewer --describe "Review PRs" --permission read-only --yes
```
A one-line description makes the drafted system prompt dramatically better than a bare name.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create --describe "Summarise long design docs into 5 bullets"
```
Same-named project agents take precedence for `run`, so a global one silently loses to a project override.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create note-taker --describe "Capture meeting notes" --global --yes
```
A name is a file stem, not a path. Avoid `/`, `\`, `.`, and `..` — the command rejects them before drafting, so you get fast, clear failures.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agent create code-reviewer --describe "Review PRs" --yes
```
***
## Related
Full command tree, including the `agent` subcommands.
Custom agents in the coding CLI.