Skill Invocation - PraisonAI

Skills can be invoked three ways: auto-triggered by the LLM from the system-prompt listing, manually via /skill-name slash commands, or programmatically through SkillManager.invoke().

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    skills=["./skills/deploy"],
)
agent.start("/deploy staging prod")

The user sends a slash command or normal prompt; the agent routes to skill invoke or LLM handling.

Quick Start

Slash command

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    skills=["./skills/deploy"],
)
agent.start("/deploy staging prod")
# Renders the skill body with $ARGUMENTS substituted, then continues the turn

Auto-trigger

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    skills=["./skills/csv-summary"],
)
agent.start("Summarise this CSV for me")
# LLM sees skill descriptions in the system prompt and activates the matching skill

How It Works

Mode	When to use
Auto-trigger	Skill `description` is in the system prompt; the LLM decides when to follow it
Slash command	User types `/deploy staging`; body is rendered with `$ARGUMENTS` substituted

Skill files are read as UTF-8. Run praisonai skills validate --path ./my-skill to catch encoding issues before deploy.

Argument Substitution

Inside SKILL.md bodies you can reference arguments passed after the skill name:

$ARGUMENTS
Indexed
Shorthand
Context vars

Deploy $ARGUMENTS now.

/deploy staging prod becomes Deploy staging prod now.

Migrate $ARGUMENTS[0] from $ARGUMENTS[1] to $ARGUMENTS[2].

/migrate SearchBar React Vue expands each positional argument.

Hello $0, meet $1.

$N is shorthand for $ARGUMENTS[N]. Quotes group tokens: /greet "hello world" friend sets $0 = "hello world".

Working inside ${PRAISON_SKILL_DIR}. Session ${PRAISON_SESSION_ID}.

${CLAUDE_SKILL_DIR} / ${CLAUDE_SESSION_ID} are supported as aliases so existing Claude Code skills work unchanged.

Inline Shell Substitution

Disabled by default. Skills that embed !`cmd` blocks render as [shell execution disabled] until you explicitly opt in.

from praisonaiagents import SkillManager

mgr = SkillManager()
mgr.add_skill("./skills/pr-summary")
rendered = mgr.invoke("pr-summary", raw_args="42", shell_exec=True)

Inline backtick form

Current branch: !`git rev-parse --abbrev-ref HEAD`

Fenced block form

```!
node --version
npm --version
```

Invocation Policy

disable-model-invocation

boolean

default:"false"

When true the skill is hidden from the system-prompt listing, so the LLM cannot auto-trigger it. Users can still invoke it via /skill-name. Use for side-effecting commands like /deploy.

user-invocable

boolean

default:"true"

When false the slash-router ignores the skill. Use for background knowledge you want auto-triggered by the LLM but not exposed as a user command.

Allowed Tools Pre-approval

allowed-tools

string | list[str]

Space-separated string (Read Grep) or YAML list. When a user invokes the skill, those tool names are pre-approved via the approval registry for the current agent so the LLM can run them without the interactive confirmation prompt.

Common Patterns

Programmatic invoke

from praisonaiagents import Agent

agent = Agent(name="assistant", skills=["./skills/deploy"])
rendered = agent.skill_manager.invoke("deploy", raw_args="staging prod")

YAML

# agents.yaml
agents:
  assistant:
    role: Helper
    goal: Help the user
    backstory: You are helpful.
    skills:
      - ./skills/deploy
      - ~/.praisonai/skills/csv-summary

CLI

praisonai skills list

praisonai "/deploy staging" --skills ./skills/deploy

praisonai skills install https://github.com/acme/my-skill
praisonai skills install ./local-skill --dest ~/.praisonai/skills

Set PRAISONAI_DISABLE_SKILL_TOOLS=1 to stop the agent from auto-injecting run_skill_script and read_file when skills are configured. Useful for hermetic tests and hosts that want full control over the tool surface.

Precedence

Skills are discovered in this order (first wins on name collision):

Project

./.praisonai/skills/ or ./.claude/skills/

Ancestors

Every .praisonai/skills or .claude/skills in a parent directory (monorepo support)

User

~/.praisonai/skills/

System

/etc/praison/skills/

Collisions are logged at INFO level so you can see which skill won.

Best Practices

Use slash commands for side effects

Set disable-model-invocation: true on deploy, restart, or delete skills so the LLM cannot trigger them accidentally — users invoke them explicitly with /skill-name.

Keep user-invocable false for background knowledge

Set user-invocable: false when a skill should only auto-activate from the system prompt, not appear as a slash command.

Opt in to shell blocks deliberately

Leave shell_exec=False (default) in production. Pass shell_exec=True only in trusted environments where inline !`cmd` blocks are required.

Validate encoding before deploy

Save SKILL.md as UTF-8. Run praisonai skills validate --path ./my-skill to catch Windows encoding issues early.

Agent Skills

Author SKILL.md files and configure skills on agents

Skill Bundles

Select a named, reusable set of skills with a single @bundle marker

Skill Manage

Create, edit, and approve agent-proposed skills

Approval Protocol

How allowed-tools pre-approval plugs into the approval registry

Skills Config

SkillsConfig options for discovery and paths

​Quick Start

​How It Works

​Argument Substitution

​Inline Shell Substitution

​Invocation Policy

​Allowed Tools Pre-approval

​Common Patterns

​Programmatic invoke

​YAML

​CLI

​Precedence

​Best Practices

​Related

Agent Skills

Skill Bundles

Skill Manage

Approval Protocol

Skills Config

Quick Start

How It Works

Argument Substitution

Inline Shell Substitution

Invocation Policy

Allowed Tools Pre-approval

Common Patterns

Programmatic invoke

YAML

CLI

Precedence

Best Practices

Related