> ## 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.

# Custom Agents & Commands

> Define reusable agents and commands from Markdown files — no Python required

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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/`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[~/.praisonai/] --> D[Discovery]
    P[./.praisonai/] --> D
    D --> A[Custom agents]
    D --> C[Custom commands]
    A --> R[praisonai run --agent]
    C --> RC[praisonai run --command]

    classDef dir fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef discover fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef run fill:#10B981,stroke:#7C90A0,color:#fff

    class U,P dir
    class D discover
    class A,C,R,RC run

```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Custom Agents & Commands

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Note>
  Skip the boilerplate — [`praisonai init`](/docs/cli/init) scaffolds a working `.praisonai/` with a starter agent and command, then read on to customise.
</Note>

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai init
```

<Steps>
  <Step title="Create an agent file">
    ```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    <!-- .praisonai/agents/researcher.md -->
    ---
    model: gpt-4o
    role: Research Specialist
    tools:
      - web_search
    ---

    You are an expert researcher. Provide concise, cited answers.
    ```
  </Step>

  <Step title="Run the agent">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run --agent researcher "What's new in WebAssembly 3.0?"
    ```
  </Step>

  <Step title="Create a command file">
    ```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    <!-- .praisonai/commands/summarise.md -->
    ---
    description: Summarise text
    ---

    Summarise the following in three bullet points:

    $ARGUMENTS
    ```
  </Step>

  <Step title="Run the command">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run --command summarise "Long article text here..."
    ```
  </Step>
</Steps>

## How discovery works

| Location                             | Scope                          |
| ------------------------------------ | ------------------------------ |
| `~/.praisonai/agents/` / `commands/` | User-global                    |
| `./.praisonai/agents/` / `commands/` | Project (walks up to git root) |

Project definitions **override** user definitions on name collision.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    U[User-global] --> M[Merge by name]
    P[Project-level] --> M
    M --> F[Final registry]

    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef project fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef final fill:#10B981,stroke:#7C90A0,color:#fff

    class U user
    class P project
    class M,F final
```

## Agent definitions

Files: `.praisonai/agents/*.md` or `*.yaml`

| Field          | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `model`        | LLM model                                                           |
| `tools`        | Tool list                                                           |
| `role`         | Agent role                                                          |
| `goal`         | Agent goal                                                          |
| `instructions` | System instructions                                                 |
| `mode`         | Coarse permission shorthand: `build`, `read-only`, `plan`, `review` |
| `permission`   | Per-capability allow / deny / ask rules                             |
| Markdown body  | Becomes `system_prompt` when no `instructions` field                |

## Scoping permissions

<Info>
  Three built-in agents (`build`, `plan`, `review`) are available **without any file** — see [Agent Presets & Modes](/docs/features/agent-presets-and-modes).
</Info>

Add `mode:` to a definition for instant read-only or review scoping:

```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
name: reviewer
mode: read-only
---
You are a meticulous code reviewer…
```

For finer control, use the `permission:` block:

```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
name: git-assistant
permission:
  bash:
    "git *": ask
    "*": deny
  read: allow
---
You are a git-aware assistant.
```

See [Agent Presets & Modes](/docs/features/agent-presets-and-modes) for the full modes reference, permission syntax, and precedence rules.

## Command templates

Files: `.praisonai/commands/*.md`

| Pattern         | Behaviour                                                          |
| --------------- | ------------------------------------------------------------------ |
| `$ARGUMENTS`    | Replaced with user input                                           |
| `@path/to/file` | Inlines 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`

```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
---
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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{What do you need?}
    Q -->|Named persona + tools| A[Custom agent]
    Q -->|Reusable prompt template| C[Custom command]
    Q -->|Project instructions file| R[Rules / AGENTS.md]
    Q -->|Packaged capability bundle| S[Skill]

    classDef pick fill:#F59E0B,stroke:#7C90A0,color:#fff
    class Q pick
```

## 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](/docs/features/bot-commands).

### 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:

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /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](/docs/cli/slash-commands#unified-command-registry).

## Python API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="Use project files for team sharing">
    Commit `.praisonai/agents/` and `.praisonai/commands/` to git.
  </Accordion>

  <Accordion title="Keep user-global files personal">
    Use `~/.praisonai/` for personal shortcuts that should not override team agents.
  </Accordion>

  <Accordion title="Never rely on unguarded shell substitution">
    `` !`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`.
  </Accordion>

  <Accordion title="Start with praisonai init">
    Run [`praisonai init`](/docs/cli/init) to scaffold `.praisonai/agents/` and `.praisonai/commands/` before hand-writing files.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Run CLI" icon="play" href="/docs/cli/run">
    \--agent and --command flags
  </Card>

  <Card title="Agent CLI" icon="robot" href="/docs/cli/agent">
    List and inspect custom agents
  </Card>

  <Card title="Command CLI" icon="terminal" href="/docs/cli/command">
    List and preview commands
  </Card>

  <Card title="Slash Commands" icon="slash" href="/docs/cli/slash-commands">
    Interactive custom commands
  </Card>

  <Card title="Init CLI" icon="wand-magic-sparkles" href="/docs/cli/init">
    Scaffold .praisonai/ in one command
  </Card>

  <Card title="Agent Presets & Modes" icon="shield-check" href="/docs/features/agent-presets-and-modes">
    Built-in presets and per-agent permission scoping
  </Card>
</CardGroup>