---
name: authoring-agent-specs
description: Authoring agent spec files (frontmatter + system prompt) for pi-subagent. Use when defining new agents, updating agent behavior, or scaffolding specialist prompts.
---

# Authoring Agent Specs

Create well-formed agent spec files that pi-subagent can discover and invoke.

## Agent Spec Format

An agent is defined in a `.md` file with YAML frontmatter followed by a system prompt body.

```markdown
---
name: my-agent
description: One-line summary shown in agent listings
model: anthropic/claude-sonnet-4.6
tools: read,bash,edit,write
---

You are a specialist in X. Keep responses concise.
Always confirm before making destructive changes.
```

### Required Fields

| Field | Description |
|-------|-------------|
| `name` | Identifier used when invoking the agent. Lowercase, hyphens, numbers only. |
| `description` | One-line summary shown in agent listings and the subagent tool description. |

### Optional Fields

| Field | Description |
|-------|-------------|
| `model` | `<provider>/<id>` format (e.g. `anthropic/claude-sonnet-4.6`). Resolution failure (malformed, not found, no auth) halts the run with an error. Falls back to the SDK default if absent. |
| `thinkingLevel` | `off \| minimal \| low \| medium \| high \| xhigh`. Clamped to the model's supported levels by the SDK. Falls back to the SDK default if absent. |
| `tools` | Comma-separated allowed tools (e.g. `read,bash,edit`). All tools if absent. |
| `extensions` | Omit or empty → none; list of paths → exactly those extensions loaded. Supports `${ENV_VAR}` substitution. |
| `skills` | Omit or empty → none; list of names → exactly those skills loaded. |

### `extensions` and `skills`

Subagents start with **no extensions and no skills** by default. List them explicitly if the agent needs them.

| Frontmatter | Behaviour |
|-------------|-----------|
| Field absent or empty | No extensions/skills loaded. |
| `extensions` with paths (`extensions: /path/a, /path/b`) | Exactly those extensions loaded. |
| `skills` with names (`skills: my-skill, other-skill`) | Exactly those skills loaded. |

## Where to Place Agents

### User-level (available in all projects)

```
~/.pi/agent/agents/<name>.md
```

### Project-level (available in one project)

```
<project-root>/.pi/agents/<name>.md
```

### Bundled with an extension

```
<extension-dir>/agents/<name>.md
```

Choose based on scope:
- **User-level** for personal agents you reuse across projects.
- **Project-level** for agents specific to a codebase (e.g. a framework-specific reviewer).
- **Extension-bundled** when distributing agents as part of a package.

## Naming Rules

- Lowercase letters, numbers, and hyphens only.
- No leading, trailing, or consecutive hyphens.
- The file name (minus `.md`) should match the `name` field for clarity, though pi-subagent reads the frontmatter `name`, not the filename.

**Good:** `security-reviewer`, `docs-writer`, `perf-analyzer`
**Bad:** `SecurityReviewer`, `-reviewer`, `code--reviewer`

## System Prompt Guidelines

The body after the frontmatter becomes the agent's system prompt. Effective prompts are:

- **Role-specific.** Define what the agent is expert at.
- **Constrained.** Specify output format (e.g. "Respond with a bullet list").
- **Scoped.** State what the agent should NOT do.
- **Concise.** Subagents have isolated context — tight prompts produce better results.

## Examples

### Code Reviewer

```markdown
---
name: code-reviewer
description: Reviews code for correctness, clarity, and security issues
tools: read,find,grep,ls
---

You are a thorough code reviewer. For each file or diff you review:

1. Identify correctness bugs and logic errors.
2. Flag security vulnerabilities.
3. Assess code clarity and naming.
4. Suggest specific improvements.

Respond with a brief summary followed by a bullet list of issues, grouped by severity (critical, warning, minor).
```

### Documentation Writer

```markdown
---
name: docs-writer
description: Writes clear, concise documentation and JSDoc comments
tools: read,bash,edit,write
---

You write documentation. Follow these rules:

- Use active voice and present tense.
- Keep paragraphs under 4 sentences.
- Include code examples for non-trivial APIs.
- For JSDoc: include @param, @returns, and @throws when applicable.
- Match the existing documentation style in the codebase.
```

### Agent with Explicit Extensions and Skills

```markdown
---
name: code-reviewer-with-skill
description: Reviews code using a custom review skill
tools: read,bash,edit
extensions: ./my-extension
skills: code-review
---

You review code using the review skill for structured feedback.
```