---
title: Session templates and learned templates
description: Start a session from a saved setup (prompt, gear, mode, tools, checks) and save jobs you repeat as templates.
section: plugins
order: 90
audience: [user, operator]
sources: [docs/templates.md, packages/harness/src/templates, cli/src/branding.ts]
features: [plugins.template]
---

A template is a saved starting setup for a job you do again and again: a bug fix, a release, a migration, a dependency bump. It is a prompt with placeholders plus the session it should start: a gear, a permission mode, allow rules, plan-then-execute and checks to run at the end. The repository's reference is `docs/templates.md`.

## Quick start

```bash
venom new                                   # list the templates
venom new bug-fix issue="checkout 500s when the cart is empty"
venom new dependency-bump package=vitest --model venom-smart
```

In a session: `/template` opens a picker, `/template dependency-bump package=vitest` runs one. `venom new <template> [args]` starts a normal session whose first message is `/template <template> <args>`, so every other flag works. A required placeholder you leave out is asked for on screen.

## Where templates come from

A nearer source replaces a farther one of the same name:

| Source | Where | Notes |
|---|---|---|
| project | `.venom/templates/<name>.md` | read only once you trust the project |
| yours | `~/.venom/templates/<name>.md` | |
| your org | the team library: a prompt tagged `template` | hide one with `library.hidden` ([Team library](/docs/plugins/library.md)) |
| built in | `bug-fix`, `release`, `migration`, `dependency-bump`, `flaky-test-fix` | |

## The file

```markdown
---
description: "Bump a dependency and fix what it breaks"
argument-hint: "package=<name> [to=<version>]"
params:
  - name: package
    description: "The package to bump"
    required: true
  - name: to
    default: latest
gear: eco
mode: accept-edits
tools: ["bash(npm install:*)"]
plan-exec: true
checks: ["npm test", "npm run lint"]
---
Bump {{package}} to {{to}} and fix what breaks.
```

| Field | What |
|---|---|
| `description`, `argument-hint` | shown in lists and the picker |
| `params` | `name`, `description`, `required`, `default`; used as `{{name}}`. `$ARGUMENTS`, `$1` also work |
| `gear` | switch to this gear (skipped with a notice if not available) |
| `mode` | `plan`, `default` or `accept-edits`; never `auto` or `yolo`, and capped by your policy |
| `tools` | allow rules for this session, in the permission engine's syntax |
| `plan-exec` | plan first, approve, then run each step on a worker |
| `checks` | commands the agent must run and fix before finishing; they go through the normal permission flow |

Nothing in a template runs as a shell command, and a template gets no more power than your own allow rules would. Templates cost nothing until you run one: they never change the system prompt or tool list.

## Learned templates

After you finish the same kind of job three times in 60 days (similar goals, same kinds of changed files, judged locally from your session summaries), venom makes one request to your gear's `summary` role (at most one a day, at most five drafts waiting) and writes a draft to `~/.venom/templates/proposed/`. At your next start one line tells you. `/template learn` (or `venom template learn`) lets you save it for yourself or the project, edit it first, export it as a team-library draft, or dismiss that kind of job. Nothing is saved or shared without you. `learn: false` in venom.yaml turns detection off.

## Commands

| Command | What |
|---|---|
| `venom new [<template> [args…]]` | start a session from a template; no name lists them |
| `venom template list [--json]` | templates and their source |
| `venom template show <name>` | one template with its setup |
| `venom template export <name>` | a team-library draft for any template |
| `venom template learn` | drafts waiting for review |
| `venom template learn show\|accept\|dismiss <name> [--project]` | review one draft |
| `venom template learn export <name>` | a draft as a team-library proposal |
| `/template [name] [args…]`, `/template list`, `/template learn` | the same in a session |

## Related

- [Team library](/docs/plugins/library.md)
- [Skills and slash commands](/docs/plugins/skills.md)
