Skip to content
aarness.
DocsHaarness CLI
On this page

Create agents, commands and skills

Three ways to stop repeating yourself:

  • A slash command is a prompt you reuse: /audit src/billing.
  • An agent is a role with its own instructions, model, tools and permissions, such as a reviewer that may not edit files.
  • A skill is a set of instructions the model can pick up by itself when a task calls for it.

Each one is a Markdown file. Create them with the commands below or write the files by hand.

Make a slash command

haarness command create audit \
  --description 'Audit a folder for security problems' \
  --template 'Audit $ARGUMENTS for security problems' \
  --argument-hint '<path>'

Then type /audit src/billing in the terminal UI or Desktop, or run it from a script:

haarness run --command audit "src/billing"

$ARGUMENTS is replaced by everything after the command name. $1, $2 and so on take single words, and the highest one you use takes the rest of the line. A template with neither gets the arguments added at the end. --agent and --model make the command always run with that agent or model. Use --file prompt.md instead of --template for a longer prompt.

The command is saved as ~/.config/haarness/commands/audit.md:

---
description: Audit a folder for security problems
argument-hint: <path>
---
Audit $ARGUMENTS for security problems

Write @path/to/file in a template to send that file's contents with the command, or @folder/ to send a listing of the folder.

Make a custom agent

haarness agent create reviewer \
  --description 'Reviews changes without editing' \
  --model anthropic/claude-sonnet-5-5 \
  --tool bash=false \
  --permission 'edit:*=deny' \
  --prompt 'Review the change for correctness and missing tests.'

Switch to it in the terminal UI with /agents (or Alt+A, or Tab to cycle), in Desktop with the agent menu in the message box, or use it in a script with haarness run --agent reviewer "…".

Flag Does
--description What the agent is for (required)
--prompt or --file Its instructions, inline or from a file (one is required)
--model Always use this provider/model
--tool NAME=BOOL Allow or remove a tool (repeatable)
--permission 'PATTERN=allow|ask|deny' A permission rule for this agent (repeatable)
--mode primary, subagent or all: where the agent can be used

Your instructions are added to Haarness's own; they do not replace its safety rules. See Permissions for the patterns --permission accepts.

Haarness ships five agents: build (the default), plan, review, explore and general. haarness agents lists them with yours. A chat that is running keeps the agent definition it started with; your edits apply from its next message.

Add a skill

haarness skill create release-check \
  --description 'Check a release is ready: build, tests and artefacts' \
  --instructions 'Run the build and tests, then check the changelog and version.'

This creates ~/.config/haarness/skills/release-check/SKILL.md. The model sees each skill's name and description and loads the instructions when a task matches, so write the description as "when to use this". Use --file for longer instructions. /skills in the terminal UI lists them.

Share them with your project

Add --project to any create or remove command. The file then goes under .haarness/ in the project, so you can commit it and your team gets it too.

Kind Yours Project
Commands ~/.config/haarness/commands/ .haarness/commands/
Agents ~/.config/haarness/agents/ .haarness/agents/
Skills ~/.config/haarness/skills/ .haarness/skills/

If a project file and one of yours have the same name, the project's wins. Haarness picks up new and changed files without a restart.

See, change or remove them

haarness command list           # also: agent list, skill list
haarness command get audit
haarness command remove audit

To change one, edit its file, or run create again with --force to replace it.

You can also ask the agent: "create a command called audit that…". It writes the same files.

Change Haarness's built-in instructions

The built-in agents and a few helpers (chat titles, summaries of long chats, Auto's reviewer) use prompts that ship with Haarness. A prompt file replaces one of them, or adds text before or after it:

haarness prompt customize plan  # writes ~/.config/haarness/prompts/plan.md to edit
haarness prompt show plan       # the prompt as Haarness now sends it

A file without front matter is added after the built-in prompt, so it keeps working when Haarness improves that prompt:

<!-- ~/.config/haarness/prompts/plan.md -->
Write the plan as a numbered list, and name the tests that prove each step.

A file that haarness prompt customize writes starts with mode: replace; prepend and append are the other modes. The names are system, plan, review, explore, compaction, title, preview, ultracode, max-steps, goal and auto-review; haarness prompt list shows them with the files that change them. The next message uses your change.

Prompt files are read only from your configuration folder (or a team system folder), never from a project, so a repository you clone cannot rewrite them. A replaced prompt keeps Haarness's safety lines, and no prompt changes what the agent is allowed to do. When an update changes a built-in prompt you replaced, haarness prompt list marks your file stale and haarness prompt diff shows what changed.

For one project's rules, use AGENTS.md instead.