--- name: agent-development description: Design and write Navin subagents (agents/.md with name, description and examples, tools, model, color, and a system prompt body), and test that Navin delegates to them. Use when the user asks to "create an agent", "add an agent to my plugin", "write a subagent", "agent frontmatter", "when-to-use description", "agent examples", "restrict agent tools", "autonomous agent", or needs agent prompt and triggering best practices. --- # Agent Development A subagent is a specialist Navin starts with `spawn(agent="", task="...")`. It runs in its own context window with its own system prompt, works autonomously, and returns a report. Use one when a job is self-contained, benefits from a focused prompt, or would flood the main conversation with intermediate output. The `agent-creator` subagent writes an agent from a plain description, using this skill. `scripts/validate-agent.sh` checks a file. ## File format ```markdown --- name: test-generator description: Use this agent when code was written or changed without tests, or when the user asks to "add tests", "cover this module", "write unit tests". Examples: Context: The main agent just implemented a parser. user: "Great, now make sure it is tested." assistant: "I'll use the test-generator agent to write tests for the parser." New code without tests and an explicit request: delegate. user: "Coverage on billing/ is terrible." assistant: "I'll run the test-generator agent on billing/." tools: ["read_file", "grep", "find_files", "write_file", "exec"] model: inherit color: green --- You are a test engineer who writes focused, deterministic tests. **Responsibilities:** 1. ... **Process:** 1. ... **Output format:** ... ``` The frontmatter configures the agent; everything after the closing `---` is its system prompt, layered on top of Navin's standard subagent prompt (tool rules, workspace, verification discipline). ## Frontmatter fields | Field | Required | Meaning | |---|---|---| | `name` | yes | Identifier used in `spawn(agent=...)`. 3 to 50 characters, lowercase letters, digits, hyphens, starting and ending with a letter or digit. Defaults to the file name. | | `description` | yes | When Navin should delegate, with 2 to 4 `` blocks. Shown in the prompt (examples stripped) and decisive for routing. | | `tools` | no | Allowlist of tool names. Omit to inherit everything the parent turn allows. Restriction only narrows: it never grants a tool the parent cannot use. | | `model` | no | `inherit` (default). The subagent runs on the session's model routing. | | `color` | no | Display hint for the UI: `blue`, `cyan`, `green`, `yellow`, `magenta`, `red`. | ### Fields Navin does not read Navin honours `name`, `description`, `tools`, `disallowedTools`, `model`, `permissionMode` and `color`. `disallowedTools` removes tools even when `tools` is absent. `model` names a configured model preset; `inherit`, an empty value or a name with no matching preset keeps the parent's model. `permissionMode` takes `default` (approval questions go to the user of the chat that started the agent), `plan` (read-only tools only), `acceptEdits` (file edits approved without asking) or `bypassPermissions` (nothing asked, unless an organization policy forbids it); an unknown value keeps `default`. Other keys some agent formats use (`maxTurns`, `skills`, `hooks`) are ignored without error; enforce such limits through `tools` and the system prompt instead. A file whose body is empty is skipped entirely. Agent files in TOML (`name`, `description`, `developer_instructions`) are also read, without `tools`, `model` or `color`. To run one delegation on another model, pass a configured preset at spawn time rather than in the file: `spawn(agent="", task="...", model_preset="")`. ### Naming Good: `code-reviewer`, `api-docs-writer`, `migration-planner`. Rejected: `ag` (too short), `-helper` (leading hyphen), `My_Agent` (uppercase, underscore). Name the role, not the topic: `schema-reviewer` rather than `database`. ### Description The description is the routing rule. Write: 1. One sentence on the trigger: "Use this agent when ...". 2. Quoted phrases users type. 3. 2 to 4 examples covering explicit requests and proactive use (the main agent decides to delegate after its own work). Each example: optional `Context:`, a `user:` line, an `assistant:` line that names the agent, and an optional `` explaining why. Detailed patterns and anti-patterns: `references/triggering-examples.md`. The four example formats worth covering: ```markdown Context: Explicit request. user: "Review the auth module for security issues." assistant: "I'll use the security-reviewer agent on auth/." The user names the job the agent exists for. Context: Proactive use after the main agent wrote code. user: "Add a password reset endpoint." assistant: "The endpoint is in place. I'll run the security-reviewer agent on it before we continue." New code touching credentials: review without being asked. Context: Implicit need. user: "Is it safe to ship this login change?" assistant: "I'll use the security-reviewer agent to check it." No keyword match, but the intent is a security review. Context: Several steps in one request. user: "Fix the token bug, then make sure nothing else is exposed." assistant: "Token bug fixed. Now I'll use the security-reviewer agent for the rest." Delegate only the review part, after the fix. ``` Each `assistant:` line names the agent; that is what teaches the routing. Avoid examples that only differ by wording, and never show the agent being used for a task it should refuse. ### Tools Navin tool names: `read_file`, `write_file`, `edit_file`, `apply_patch`, `exec`, `grep`, `find_files`, `list_dir`, `code_index`, `lsp`, `web_search`, `web_fetch`, `browser`, `skill`, `board`, `verify`, `test_run`, `mcp__`. Common aliases are accepted and mapped: `Read`, `Write`, `Edit`, `MultiEdit`, `Bash`, `Grep`, `Glob`, `LS`, `WebFetch`, `WebSearch`, `Skill`, `TodoWrite`. Grant the least that does the job: | Agent kind | Tools | |---|---| | Reviewer, auditor, analyst | `read_file`, `grep`, `find_files`, `code_index` | | Writer of new files | add `write_file` | | Fixer | add `edit_file`, `apply_patch`, `verify` | | Runner of builds or tests | add `exec`, `test_run` | | Researcher | `web_search`, `web_fetch` | A subagent cannot ask the user questions: it runs in the background. Tell it to report what it needs instead. ## Writing the system prompt Write in second person, as instructions to the agent. A solid structure: ```markdown You are specializing in . **Responsibilities:** 1. 2. **Process:** 1. 2. ... **Quality standards:** - **Output format:** **Edge cases:** - : ``` Rules: - Be specific: "Run `grep -n 'TODO'` on the changed files" beats "look for problems". - Define the output: the main agent has to use it. Tables, headings, file:line references. - Say when to stop and what to do when blocked. - Require evidence: every claim tied to a file, line, command output. - 500 to 3,000 words. Shorter lacks guidance; longer dilutes it. - Plain hyphens, no long dashes. Full guide with templates per agent kind: `references/system-prompt-design.md`. ### A filled-in system prompt ```markdown You are a security reviewer specializing in web authentication code. **Responsibilities:** 1. Find vulnerabilities in the files named in the task. 2. Rank them by real exploitability, not by theoretical severity. **Process:** 1. List the target files with `find_files`; read each with `read_file`. 2. `grep` for secrets, raw SQL, `eval`, disabled TLS checks, missing auth decorators. 3. For each hit, read the surrounding function and confirm it is reachable. 4. Stop after the named scope; do not audit the whole repository. **Quality standards:** - Every finding cites `path:line` and the exact excerpt. - No finding without a concrete attack scenario. **Output format:** | Severity | File:line | Issue | Fix | followed by a one-line verdict: SAFE TO SHIP or BLOCK. **Edge cases:** - Nothing found: say so and list what was checked. - Generated or vendored code: skip it and mention it. ``` ## Creating an agent **Assisted**: spawn the `agent-creator` agent with the user's description, or follow `references/agent-generation-prompt.md` yourself: it turns a request into a name, a description with examples and a complete system prompt. **Manual**: 1. Choose the name and the trigger. 2. Write the description with examples. 3. Pick the minimal tools. 4. Write the system prompt with the structure above. 5. Save to `agents/.md` (plugin), `/.navin/agents/.md` (project) or `~/.navin/agents/.md` (personal). 6. Validate: `bash /scripts/validate-agent.sh `. ```bash bash /scripts/validate-agent.sh .navin/agents/security-reviewer.md # [WARNING] description has no blocks (add 2-4) # Agent 'security-reviewer': PASS ``` The script takes one file (exit 2 without it) and exits 1 on a critical issue: missing frontmatter, invalid `name`, empty `description`, `tools` not a list or comma string, non-string `model`, empty body. It warns on missing or excessive examples, a description that does not start with the trigger, an unknown color, a prompt too short or too long, no second person, no output format, long dashes. ## Where agents are found In order, first name wins: the workspace `.navin/agents/` and other `./agents/` folders, the user's `~/.navin/agents/` (and other home tool folders), enabled plugins' `agents/`, then Navin's built-in agents. Subfolders are scanned recursively, so `agents/review/security.md` works. Files are re-read on change; no restart needed. Concretely, for an agent named `security-reviewer`: ``` /.navin/agents/security-reviewer.md # project, highest priority /.agents/agents/security-reviewer.md # other dot folders, scanned too ~/.navin/agents/security-reviewer.md # personal ~/.navin/plugins//agents/security-reviewer.md # enabled plugin navin/builtin_agents/.md # shipped with Navin ``` Built-in agents include `agent-creator`, `code-architect`, `code-explorer`, `code-reviewer`, `plugin-validator` and `skill-reviewer`. Both `agents/` and `agent/` subfolders are read, and `README.md` files are ignored. ## How Navin runs an agent The main agent sees each agent's name and description (examples stripped) and delegates through the `spawn` tool: ```python spawn(agent="security-reviewer", task="Review auth/ for the reset flow added today") spawn(agent="security-reviewer", task="...", scope_paths="navin/auth, tests/auth") spawn(agent="security-reviewer", task="...", isolate=True) # own git checkout from HEAD ``` Several spawns can run in parallel; each returns its final report to the main agent. The `task` string is the only context the subagent receives, so put the paths, the goal and the expected output in it. ## Testing 1. **Routing**: in a chat, phrase the task like each example and check that Navin spawns the agent. Phrase a nearby task and check it does not. 2. **Behaviour**: spawn it directly, `spawn(agent="", task="...")`, on a real case. Check it follows the process and returns the declared format. 3. **Tools**: if `tools` is set, confirm the job is doable with them; a reviewer that must run tests needs `exec`. ## Quick reference Minimal agent: ```markdown --- name: changelog-writer description: Use this agent when the user asks to "write the changelog" or "summarize changes since the last tag". Examples: user: "Draft release notes for 1.4" assistant: "I'll use the changelog-writer agent." --- You write changelogs from git history. Run `git log ..HEAD --oneline`, group commits into Added / Changed / Fixed, and return Markdown only. ``` ## Resources - `references/system-prompt-design.md` - prompt structure and templates for analysis, generation, validation and orchestration agents. - `references/triggering-examples.md` - writing `` blocks that route correctly. - `references/agent-generation-prompt.md` - the procedure to turn a request into a complete agent file. - `examples/complete-agent-examples.md` - four complete agents. - `examples/agent-creation-prompt.md` - a ready-to-use request that asks Navin to generate a new agent file. - `scripts/validate-agent.sh` - check an agent file.