Customizable Agents (Personas)

ChatCLI allows you to create Customizable Agents (also called Personas) that define specific behaviors for the AI. This system transforms ChatCLI from a tool with a static “System Prompt” into a polymorphic platform.

Core Concept

The central idea is prompt composition:

Agents define “who” the AI is (personality, specialization, tone)
Skills define “what” it should know/follow (rules, knowledge, compliance)

An Agent can import multiple Skills, creating a “Super System Prompt” that is automatically composed.

Benefits

Reusability

Skills can be shared across multiple agents

Versioning

.md files can be versioned in Git

Collaboration

Teams can share agents and skills

Consistency

Coding style rules applied automatically

Specialization

Create agents for Go, Python, DevOps, etc.

Dispatch as Worker

Custom agents are automatically registered in the multi-agent system and can be dispatched via agent_call by the LLM

Remote Server

When connecting to a server, remote agents and skills are automatically discovered and merged with local ones

Directory Structure

Files are stored in the ~/.chatcli/ directory:

~/.chatcli/
|-- agents/            # Agent files
|   |-- go-expert.md
|   |-- devops-senior.md
|   |-- security-auditor.md
|   +-- python-data-scientist.md
+-- skills/            # Skill files (.md or V2 directories)
    |-- clean-code/    # V2 Skill (package with subskills + scripts)
    |   |-- SKILL.md
    |   |-- naming-rules.md
    |   +-- scripts/
    |       +-- lint_check.py
    |-- error-handling.md  # V1 Skill (single file)
    |-- docker-master.md
    +-- clean-scripts.md

Agent File Format

Agents are Markdown files with YAML frontmatter:

---
name: "devops-senior"
description: "Senior DevOps with focus on CI/CD and infrastructure"
tools: Read, Grep, Glob, Bash, Write, Edit   # Defines which tools the agent can use as a worker
skills:                    # List of skills to import
  - clean-code
  - bash-linux
  - architecture
plugins:                   # Enabled plugins (optional)
  - "@coder"
---
# Base Personality

You are a Senior DevOps Engineer, specialist in CI/CD,
containers, infrastructure as code, and observability.

`tools` Field — Multi-Agent Integration

The tools field in the YAML frontmatter is the key to integration with the multi-agent orchestration system. It defines which commands the agent can use when dispatched as a worker by the orchestrator LLM.

Tool in YAML	@coder Command(s)	Description
`Read`	`read`	Read file contents
`Grep`	`search`	Search for patterns in files
`Glob`	`tree`	List directories
`Bash`	`exec`, `test`, `git-status`, `git-diff`, `git-log`, `git-changed`, `git-branch`	Command execution and git operations
`Write`	`write`	Create/overwrite files
`Edit`	`patch`	Precise editing (search/replace)

Agents without a tools field automatically receive read, search, tree and are marked as read-only. Agents with Write, Edit, or Bash have write/execute access. Embedded agent names (file, coder, shell, git, search, planner) are protected and cannot be overwritten.

Example without the `tools` field

---
name: "go-expert"
description: "Go/Golang specialist focused on clean code"
skills:
  - clean-code
  - error-handling
plugins:
  - "@coder"
---
# Base Personality

You are a Senior Software Engineer, specialist in Go/Golang.

## Core Principles

1. **Simplicity**: Prefer simple and readable code.
2. **Composition**: Use small interfaces and composition over inheritance.
3. **Errors**: Handle errors explicitly, never ignore them.
4. **Tests**: Write tests with table-driven tests.

This agent will be registered as read-only in the multi-agent system (only read, search, tree).

Skill File Format

Skills contain pure knowledge or compliance rules:

---
name: "clean-code"
description: "Clean Code principles and best practices"
---
# Clean Code Rules

## Naming

1. **Meaningful names**: Variables and functions should reveal their purpose.
2. **Avoid disinformation**: Don't use names that could confuse.
3. **Pronounceable names**: Use names that can be discussed verbally.

## Functions

1. **Small**: Functions should do one thing only.
2. **Few arguments**: Ideally 0-2 arguments, maximum 3.
3. **No side effects**: Functions should do only what they promise.

Skills V2 — Packages with Subskills and Scripts

In addition to V1 skills (single .md file), ChatCLI supports Skills V2: directories containing multiple documents and executable scripts.

V2 Skill Structure

skills/
+-- clean-code/
    |-- SKILL.md            # Main content (frontmatter + body)
    |-- naming-rules.md     # Subskill: naming rules
    |-- formatting.md       # Subskill: formatting rules
    +-- scripts/
        +-- lint_check.py   # Executable script

Subskills

.md files inside the skill directory (except SKILL.md) are registered as subskills. When the agent is dispatched as a worker, the subskill paths appear in the worker’s system prompt, which can read them with the read command as needed.

Scripts

Files in scripts/ are registered as executable skills in the worker. The system automatically infers the execution command based on the extension:

Extension	Inferred Command
`.sh`	`bash script.sh`
`.py`	`python3 script.py`
`.js`	`node script.js`
`.ts`	`npx ts-node script.ts`
`.rb`	`ruby script.rb`
Others	`./script` (direct execution)

Scripts are executed via the @coder exec command and their results return to the worker for processing.

Skills from Remote Registries

In addition to creating skills manually, you can search and install skills from remote registries with the /skill command:

# Search for kubernetes skills
/skill search kubernetes

# Install a skill
/skill install k8s-ops

# Verify it appears in available skills
/agent skills

Skills installed via registry are saved in ~/.chatcli/skills/<name>/SKILL.md as V2 packages and are immediately available for use with agents. ChatCLI supports multiple simultaneous registries (ChatCLI.dev, ClawHub, corporate registries) with parallel fan-out search. See Skill Registry for full details.

Dispatch as Worker (Multi-Agent)

When starting /coder or /agent, all custom agents are automatically registered in the multi-agent orchestration system. The orchestrator LLM can then dispatch them via <agent_call>:

<agent_call agent="devops-senior" task="Configure CI/CD pipeline with GitHub Actions" />
<agent_call agent="security-auditor" task="Audit the authentication module for OWASP" />

What the Worker Receives

When dispatched, the CustomAgent executes with:

Personalized system prompt

Includes the agent content (markdown body), loaded skills, subskill paths, script commands, and tool_call instructions

Mini ReAct loop

The same ReAct loop as embedded agents, with reasoning, action, and observation

Allowed commands

Based on the tools field in the frontmatter

Parallel reading

Read-only tool calls execute in parallel goroutines

File locks

Writing with per-filepath mutex for anti-race safety

Error recovery

The orchestrator can use direct tool_call to diagnose and fix failures

End-to-End Example

# 1. Create the agent in ~/.chatcli/agents/devops-senior.md
# 2. Start coder mode
/coder configure the deployment pipeline and monitoring

# The orchestrator LLM can dispatch:
# <agent_call agent="devops-senior" task="Set up CI/CD with GitHub Actions" />
# <agent_call agent="file" task="Read current Dockerfile and docker-compose.yml" />
#
# Both run in parallel with their own ReAct loops

Management Commands

All management commands are integrated into /agent:

Command	Description
`/agent`	Shows active agent status and help
`/agent list`	Lists all available agents
`/agent status`	Lists only attached agents (summary) - alias: attached/list-attached
`/agent load <name>`	Loads a specific agent
`/agent attach <name>`	Attaches an additional agent to the session
`/agent detach <name>`	Removes an attached agent
`/agent skills`	Lists all available skills
`/agent show [--full]`	Shows the active agent with example prompts (use —full to display everything)
`/agent off`	Deactivates all currently activated agents
`/agent <task>`	Executes a task in agent mode

Prompt Assembly Order

When an agent is loaded, the system prompt is assembled in the following order:

[ROLE]

Agent identity (name, description)

[PERSONALITY]

Base agent content (markdown body)

[SKILLS]

Knowledge from imported skills (numbered)

[PLUGINS]

Hints for enabled plugins

[REMINDER]

Anchor with application instructions

This order ensures that the AI receives context in a structured manner.

Complete Practical Example

1. Create an agent

Create the file ~/.chatcli/agents/python-data.md:

---
name: "python-data"
description: "Data Scientist specializing in Python"
skills:
  - clean-code
plugins:
  - "@coder"
---
# Base Personality

You are a Senior Data Scientist, specializing in Python.

## Preferred Tools

- Pandas for data manipulation
- NumPy for numerical computation
- Matplotlib/Seaborn for visualization
- Scikit-learn for classical ML
- PyTorch for deep learning

2. Use the agent

# List agents
/agent list

# Available Agents:
#   go-expert - Go/Golang Specialist [2 skills]
#   python-data - Data Scientist [1 skills]

# Load the agent
/agent load python-data

# Agent 'python-data' loaded successfully!
#    Data Scientist specializing in Python
#    Attached skills:
#     - clean-code

# Use in agent mode
/agent analyze this dataset and create visualizations

# Or in coder mode
/coder create an ML pipeline for classification

Agent and Skill Precedence (Project > Global)

Both agents and skills support per-project directories with precedence over global ones. ChatCLI automatically detects the project root by searching for a .agent/ or .git/ directory starting from the current directory.

Search Order

Resource	1. Project (priority)	2. Global (fallback)
Agents	`./.agent/agents/*.md`	`~/.chatcli/agents/*.md`
Skills	`./.agent/skills/`	`~/.chatcli/skills/`

If an agent or skill with the same name exists in both directories, the project version takes precedence.

Project Structure

my-project/
|-- .agent/                  # Marks the project root for ChatCLI
|   |-- agents/              # Project-specific agents
|   |   +-- backend.md       # Overrides ~/.chatcli/agents/backend.md
|   +-- skills/              # Project-specific skills
|       +-- team-rules.md    # Team-specific rules
|-- src/
+-- ...

If your project already has .git/, ChatCLI uses that directory as the project root automatically. The .agent/ is optional — use it when you want per-project agents/skills without depending on Git.

Integration with /coder

When an agent is loaded:

/agent <task> — Uses the agent’s persona
/coder <task> — Combines the agent’s persona with the coder prompt

This allows you to have a Go specialist agent using @coder tools to edit files, run tests, etc.

Tips

Start Simple

Create agents with few skills and add more as needed.

Version in Git

Keep your agents and skills in a repository.

Share with the Team

Coding style skills ensure consistency.

Use Clear Descriptions

Helps understand the purpose of each agent/skill.

Test the Prompt

Use /agent show to see how the assembled prompt looks.

Useful Skill Examples

clean-code - Clean code principles
error-handling - Error handling patterns
testing-patterns - Automated testing patterns
docker-master - Best practices for Dockerfiles
clean-scripts - Patterns for secure Bash scripts
aws-security - AWS security rules
team-conventions - Team-specific conventions

Remote Agents and Skills

When connected to a ChatCLI server via chatcli connect, the client automatically discovers agents and skills available on the server. They are transferred to the client and composed locally, allowing merging with local resources.

# Upon connecting, the client shows available resources
Connected to ChatCLI server (version: 1.3.0, provider: CLAUDEAI, model: claude-sonnet-4-5)
 Server has 3 plugins, 2 agents, 4 skills available

# Remote agents appear in the listing
/agent list

# Available Agents:
#   go-expert       - Go/Golang Specialist                  [local]
#   devops-senior   - Senior DevOps with K8s focus          [remote]

# Loading a remote agent works the same way
/agent load devops-senior

Provisioning via Kubernetes

Helm
Operator

# Helm: inline agents and skills
helm install chatcli deploy/helm/chatcli \
  --set agents.enabled=true \
  --set-file agents.definitions.devops-senior\\.md=agents/devops-senior.md \
  --set skills.enabled=true \
  --set-file skills.definitions.k8s-best-practices\\.md=skills/k8s-best-practices.md

# Operator: references existing ConfigMaps
apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: chatcli-prod
spec:
  provider: CLAUDEAI
  agents:
    configMapRef: chatcli-agents
    skillsConfigMapRef: chatcli-skills

ConfigMaps are mounted at /home/chatcli/.chatcli/agents/ and /home/chatcli/.chatcli/skills/, and are available for automatic remote discovery.

Home

Getting Started

Core Concepts

Features

Support

​Core Concept

​Benefits

Reusability

Versioning

Collaboration

Consistency

Specialization

Dispatch as Worker

Remote Server

​Directory Structure

​Agent File Format

​tools Field — Multi-Agent Integration

​Example without the tools field

​Skill File Format

​Skills V2 — Packages with Subskills and Scripts

​V2 Skill Structure

​Subskills

​Scripts

​Skills from Remote Registries

​Dispatch as Worker (Multi-Agent)

​What the Worker Receives

​End-to-End Example

​Management Commands

​Prompt Assembly Order

​Complete Practical Example

​1. Create an agent

​2. Use the agent

​Agent and Skill Precedence (Project > Global)

​Search Order

​Project Structure

​Integration with /coder

​Tips

Start Simple

Version in Git

Share with the Team

Use Clear Descriptions

Test the Prompt

​Useful Skill Examples

​Remote Agents and Skills

​Provisioning via Kubernetes

Core Concept

Benefits

Directory Structure

Agent File Format

`tools` Field — Multi-Agent Integration

Example without the `tools` field

Skill File Format

Skills V2 — Packages with Subskills and Scripts

V2 Skill Structure

Subskills

Scripts

Skills from Remote Registries

Dispatch as Worker (Multi-Agent)

What the Worker Receives

End-to-End Example

Management Commands

Prompt Assembly Order

Complete Practical Example

1. Create an agent

2. Use the agent

Agent and Skill Precedence (Project > Global)

Search Order

Project Structure

Integration with /coder

Tips

Useful Skill Examples

Remote Agents and Skills

Provisioning via Kubernetes