# Create Custom Agents with Specific Authority Boundaries in AIOX > Learn how to create custom agents with specific authority boundaries in AIOX. Define agent identity and enforce runtime security with allowed operations. - Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core) - Tags: how-to-guide - Published: 2026-03-15 --- **You create custom agents in AIOX by copying a base template to `.aiox-core/development/agents/`, editing the YAML front-matter to define identity and permitted operations, and configuring the `security` block with `allowed_operations` to enforce runtime boundaries.** AIOX treats every agent as a declarative YAML document, making it simple to create custom agents with specific authority boundaries without modifying core framework code. By storing agent definitions as static markdown files under `.aiox-core/development/agents/`, you can version-control both agent capabilities and security constraints alongside your codebase. This guide walks through the exact file paths and YAML structures used in the SynkraAI/aiox-core repository to define authority limits that the runtime enforces at execution time. ## Understanding AIOX Authority Layers AIOX enforces two complementary layers of authority to prevent unauthorized operations. The **delegation matrix** defines high-level exclusive operations (like `git push` or `gh pr create`) reserved for specific built-in agents, residing in [`.claude/rules/agent-authority.md`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/rules/agent-authority.md). The **security block** provides per-agent authorization through `allowed_operations` that you declare in the agent's YAML front-matter, using the schema defined in [`.claude/templates/agent-template.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/templates/agent-template.yaml). When an agent executes a command, the dispatcher in [`src/agents/dispatcher.ts`](https://github.com/SynkraAI/aiox-core/blob/main/src/agents/dispatcher.ts) verifies the command exists in the agent's `commands` list, checks against `security.allowed_operations`, and validates it doesn't violate the delegation matrix. Commands reserved exclusively for another agent are rejected unless `@aiox-master` grants a temporary override. ## Step-by-Step Guide to Creating Custom Agents ### Copy the Base Agent Template Start by duplicating the generic development agent to create your custom agent file: ```bash cp .aiox-core/development/agents/dev.md .aiox-core/development/agents/my-agent.md ``` This base template contains the YAML skeleton used by the runtime parser when loading agents at startup. ### Define Identity and Persona Edit the YAML front-matter in your new file to establish the agent's identity. According to the template structure in [`.claude/templates/agent-template.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/templates/agent-template.yaml), modify fields like `name`, `id`, `title`, `icon`, and `persona`: ```yaml agent: name: Analyst id: analyst title: Business Analyst icon: 📊 persona: role: Business Analyst & Requirements Specialist style: Concise, data-driven ``` The `id` field must be unique across your agent directory, as it determines the slash command name (e.g., `/analyst`). ### Configure Security Boundaries Add a `security` block to constrain what operations the agent can perform. Following the schema in lines 74–81 of [`.claude/templates/agent-template.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/templates/agent-template.yaml), specify `authorization` (for documentation) and `allowed_operations` (enforced by the runtime): ```yaml security: authorization: "read-only" allowed_operations: - git status - git fetch - db query - code search audit_logging: true ``` Setting `audit_logging: true` enables automatic recording of every command execution to `.ai/decision-log-{story}.md`. The framework only enforces the `allowed_operations` list; the `authorization` label serves documentation purposes. ### Register with Your IDE After saving your agent file, register it with your development environment using the AIOX CLI from [`bin/aiox.js`](https://github.com/SynkraAI/aiox-core/blob/main/bin/aiox.js): ```bash npx aiox-core install --ide claude-code ``` The installer scans `.aiox-core/development/agents/` and creates slash-command entries under `.claude/commands/AIOX/agents/`, making your custom agent available as `/my-agent` in the IDE chat interface. ## Code Examples ### Minimal Read-Only Analyst Agent Create [`.aiox-core/development/agents/analyst.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/agents/analyst.md) with this complete YAML front-matter: ```yaml agent: name: Analyst id: analyst title: Business Analyst icon: 📊 persona: role: Business Analyst & Requirements Specialist style: Concise, data-driven security: authorization: "analysis" allowed_operations: - code search - db query - git status - git fetch audit_logging: true commands: - name: help visibility: [full, quick, key] description: "Show available commands" - name: search-requirements visibility: [full] description: "Search codebase for requirement patterns" ``` This configuration restricts the analyst to read-only operations while allowing codebase queries. ### Extending the Delegation Matrix for Exclusive Operations If your agent requires exclusive rights to sensitive operations, edit [`.claude/rules/agent-authority.md`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/rules/agent-authority.md) to add a new delegation section. Only `@aiox-master` can grant these exclusive permissions: ```markdown ### @deployment (Nova) — EXCLUSIVE Authority | Operation | Exclusive? | Other Agents | |--------------------------|------------|--------------| | `deploy production` | YES | BLOCKED | | `rollback production` | YES | BLOCKED | ``` Once committed, only an agent with `id: deployment` can execute these commands. Other agents attempting `deploy production` receive a "blocked by authority matrix" error. ### Testing Authority Enforcement After registration, test your agent's boundaries in the IDE: ```text /analyst 📊 Analyst (Business Analyst & Requirements Specialist) ready. Available Commands: *help – Show all commands *search-requirements – Search codebase for requirement patterns > *search-requirements "authentication flow" [✅] Ran allowed operation: code search > *git push [❌] Blocked: git push is exclusive to @devops (see Agent Authority rules) ``` The runtime validates every command against both the `allowed_operations` list and the delegation matrix before execution. ## Summary - **AIOX agents are declarative YAML files** stored in `.aiox-core/development/agents/` that require no code changes to create. - **Authority uses two layers**: the delegation matrix in [`.claude/rules/agent-authority.md`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/rules/agent-authority.md) for exclusive operations, and per-agent `security.allowed_operations` for runtime enforcement. - **Security blocks** use the schema from [`.claude/templates/agent-template.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.claude/templates/agent-template.yaml) to define permitted operations and enable audit logging. - **Registration** happens via `npx aiox-core install --ide claude-code`, which creates IDE-specific slash commands. - **Runtime enforcement** occurs in the dispatcher, which rejects unauthorized commands before execution. ## Frequently Asked Questions ### What file format does AIOX use for agent definitions? AIOX stores agent definitions as markdown files with YAML front-matter located in `.aiox-core/development/agents/`. The runtime parses the YAML block between triple backticks at load time, extracting the `agent`, `persona`, `security`, and `commands` sections. This static file approach maintains the framework's "No Invention" principle by keeping agent definitions as configuration rather than code. ### Can I override an exclusive operation assigned to another agent? Only the `@aiox-master` agent can override exclusive authority restrictions defined in the delegation matrix. The core dispatcher in [`src/agents/dispatcher.ts`](https://github.com/SynkraAI/aiox-core/blob/main/src/agents/dispatcher.ts) checks the matrix before execution, and if a command is marked as exclusive to another agent ID, it rejects the request unless the requesting agent has master override privileges. Regular custom agents cannot bypass these boundaries through their individual `security` blocks. ### Where does AIOX log agent command executions? When you set `audit_logging: true` in the `security` block, AIOX writes every command execution to `.ai/decision-log-{story}.md` using the built-in audit hook. This creates a permanent record of what operations each agent performed, satisfying compliance requirements while debugging authority boundary violations. The log path includes the story ID to organize audits by workflow context. ### Why are my agent changes not showing up in the IDE? You must run the installer command `npx aiox-core install --ide claude-code` (or your specific IDE flag) after creating or modifying agent files. The installer scans `.aiox-core/development/agents/` and regenerates the slash-command mappings in `.claude/commands/AIOX/agents/`. Without this registration step, the IDE doesn't know to expose your new agent as a chat command, even though the YAML file exists in the agents directory.