Customizing Your Agent

Your agent ships with a default personality and starter knowledge. The interesting part is making it yours: tuning its identity, adding domains that match your work, and setting up hooks that enforce your standards automatically.

Identity and persona

Your agent has a persona: a name, role, and communication style. This isn’t cosmetic. The persona shapes how the agent frames its responses, what it emphasizes, and how it communicates.

You: “What’s your identity?”

Agent: Name: sentinel. Role: security-focused code review assistant. Voice: direct, technical, no-nonsense.

You set the persona during scaffold, but you can change it anytime:

You: “Update your role to: full-stack development assistant focused on React and Node.js”

Agent: Identity updated. Role changed.

Behavioral guidelines

Guidelines are rules the agent follows in every interaction. They shape behavior beyond the persona:

You: “Add this guideline: always suggest TypeScript strict mode when reviewing tsconfig changes”

Agent: Guideline added.

Guidelines stack with vault knowledge. The vault has what to do; guidelines control how the agent approaches work.

Custom behavioral rules (instructions/user.md)

Your agent’s instructions/ folder contains two types of files:

File	Who writes it	Survives agent refresh?
_engine.md	Auto-generated by Soleri	No, overwritten every time
user.md	You	Yes, never touched by the engine

user.md is your safe zone for behavioral overrides. Anything you write there gets priority placement in CLAUDE.md. It appears before the engine rules, so it wins every conflict.

When you need it

You don’t need it for a generic second brain. The engine rules cover the standard behavior. Add user.md when you have rules specific to your project or domain that the engine doesn’t know:

## Project Rules

- This project uses React with Tailwind. Never suggest inline styles or CSS modules
- All API endpoints must follow the /v1/ prefix convention
- Never add npm dependencies without checking with me first

When you don’t need it

If your agent is a universal second brain with no domain specialization, skip this file. The engine rules already enforce vault-first search, plan before coding, and knowledge capture after every session.

Why it exists

_engine.md is regenerated every time you run npx @soleri/cli agent refresh. If the engine rules change in a new Soleri version, your _engine.md updates automatically. user.md was added so your own rules survive that regeneration. They’re source files, not generated output.

Adding domains

Domains are expertise areas. Each domain gets its own search partition and a domain facade with 5 operations (get_patterns, search, get_entry, capture, remove):

npx @soleri/cli add-domain infrastructure
npx @soleri/cli add-domain testing
npx @soleri/cli add-domain performance

After adding a domain, seed it with knowledge:

npx @soleri/cli install-knowledge ./bundles/infrastructure-patterns

Or capture knowledge interactively:

You: “Capture a critical pattern in the infrastructure domain: always set CPU and memory limits on Kubernetes pods.”

Agent: Captured in infrastructure domain.

Choosing domains

Good domains are knowledge areas where you accumulate reusable patterns:

Good domains	Why
security	Clear rules, critical patterns, compliance requirements
frontend	Component conventions, accessibility standards
api-design	Endpoint conventions, error formats, versioning rules
testing	Test patterns, coverage standards, mocking approaches
infrastructure	Deployment, scaling, monitoring patterns

Avoid domains that are too broad (“coding”) or too narrow (“button-styles”). You want enough specificity that searches return relevant results, but enough breadth that the domain accumulates useful knowledge.

Hooks

Hooks are quality gates that run automatically during development. They catch common mistakes in real time, before they reach your codebase.

Installing hooks

npx @soleri/cli hooks add-pack full

This installs all available hooks:

Hook	What it catches
no-console-log	Leftover debug statements
no-any-types	TypeScript any usage
no-important	CSS !important declarations
no-inline-styles	Inline style= attributes
semantic-html	Non-semantic HTML elements
focus-ring-required	Missing keyboard focus indicators
ux-touch-targets	Touch targets smaller than 44px
no-ai-attribution	AI attribution in commit messages

Token compression with RTK

Reduce LLM token usage by 60-90% by routing shell commands through RTK:

npx @soleri/cli hooks add-pack rtk

RTK intercepts Bash commands via a PreToolUse hook and compresses verbose output (git status, test runners, build logs, file listings) before it reaches the LLM context. Supports 70+ commands across git, JS/TS, Python, Go, Ruby, Rust, Docker, and more.

Prerequisites: RTK >= 0.23.0 (brew install rtk-ai/tap/rtk) and jq.

Inline linting with oxlint

Catch lint issues on every file edit without waiting for a full build:

npx @soleri/cli hooks add-pack oxlint

Runs oxlint on the affected file after every Edit or Write. Silent when clean, surfaces findings inline when there are issues.

Prerequisites: oxlint (npm install -g oxlint).

Terse mode

Reduce output tokens by ~66% via word budgets. Code blocks stay normal; only prose gets compressed:

npx @soleri/cli hooks add-pack terse-auto

Auto-activates terse mode on every session start. Enforces word budgets (60 words default) while keeping persona and technical accuracy intact. Toggle levels with /terse lite|full|ultra or disable with “stop terse”.

Worktree cleanup

Automatically clean up stale git worktrees and orphaned branches left behind by subagent work:

npx @soleri/cli hooks add-pack worktree-cleanup

Two hooks working together:

• SessionStart: removes worktree directories that are no longer valid
• PostToolUse:Agent: prunes orphaned worktree-agent-* branches after subagent completion

Included by default on new scaffolds (scaffoldDefault: true).

Editor integration

npx @soleri/cli hooks add claude-code    # Claude Code hooks
npx @soleri/cli hooks add cursor         # Cursor
npx @soleri/cli hooks add windsurf       # Windsurf
npx @soleri/cli hooks add copilot        # GitHub Copilot

Hooks run as pre-tool-use checks in your editor. When the agent is about to write code that violates a hook, the hook blocks it and explains why.

Knowledge packs

Knowledge packs are bundles of pre-built expertise:

npx @soleri/cli install-knowledge <path-or-package>

Packs can be a local directory with JSON knowledge entries or an npm package following the Soleri knowledge pack format.

What’s in a pack

A knowledge pack contains typed entries (patterns, anti-patterns, principles, workflows) organized by domain:

my-pack/
├── patterns/           # Proven approaches (JSON files)
│   ├── error-handling.json
│   └── retry-strategy.json
├── anti-patterns/      # What to avoid
│   └── silent-catches.json
├── principles/         # Guiding rules
├── workflows/          # Step-by-step procedures
└── manifest.json       # Pack metadata

Each entry file contains a single knowledge entry:

{
  "title": "Consistent API Error Format",
  "description": "All API errors must return { error, code, details }.",
  "type": "pattern",
  "severity": "critical",
  "domain": "backend",
  "tags": ["api", "error-handling"]
}

The manifest.json declares the pack:

{
  "name": "my-backend-patterns",
  "version": "1.0.0",
  "description": "Backend patterns for API development",
  "domains": ["backend", "security"],
  "entryCount": 15
}

Available tiers

Tier	Source	Cost
Starter	Ships with every agent	Free
Community	npm registry	Free

The starter pack gives your agent useful knowledge from day one. Community packs extend it with domain-specific expertise contributed by other developers.

Upgrading

Check for updates

npx @soleri/cli upgrade --check

Upgrade the CLI

npx @soleri/cli upgrade

Upgrade the Knowledge Engine

The engine updates alongside the CLI:

npx @soleri/cli agent update    # Updates agent engine
npx @soleri/cli dev              # Restart with new engine

Engine upgrades are backward-compatible within the same major version. Your agent folder, vault data, and all customizations are preserved.

Governance policies

Control how strictly knowledge enters your vault:

npx @soleri/cli governance --preset strict      # All captures require approval
npx @soleri/cli governance --preset moderate    # Auto-approve suggestions, review critical
npx @soleri/cli governance --preset permissive  # Auto-approve everything

Preset defaults

Preset	Review required	Max entries (total)	Max entries (per category)	Max entries (per type)
permissive	No	2000	500	1000
moderate	No	500	150	250
strict	Yes	200	50	100

What governance controls

• Quotas: maximum entries per domain or type, prevents unbounded vault growth
• Retention: how long unused entries survive before decay candidates are flagged
• Auto-capture: which severity levels auto-approve vs. require proposal review
• Duplicate detection: similar entries are rejected or proposed for merging

Start with moderate. It balances quality with convenience. Move to strict if your team has many contributors and you want to review every new pattern before it becomes active.

View current policy

npx @soleri/cli governance --show

Project linking

Link related projects to share knowledge across them:

You: “Link this project to ../api-server as related”

Link types:

Type	Meaning	Direction
related	Same domain or team, both projects can search each other	Bidirectional
parent	This project derives from another	Unidirectional
child	Another project derives from this one	Unidirectional
fork	Code fork	Unidirectional

Linked projects are included in cross-project searches with weighted relevance. See Cross-Project Knowledge for the full guide.

---

Next: Operator Learning covers how your agent learns about you over time. See also CLI Reference for all command details, Creating Packs for building extensions, and Skills Catalog for available skills.