---
title: Templates
description: Agents, teams, departments and skills someone already made, ready to add. 4 tools.
group: templates
tools: [templates.search, templates.read, templates.propose_add, templates.propose_share]
source: [packages/agents/src/templates/tool.ts, packages/agents/src/templates/service.ts, packages/agents/src/templates/roadstar.ts]
generated: true
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

A template is a setup someone already made: one agent, a team, a department, or one skill. Roadstar's own are there for every workspace, and the owner's workspace has the ones its people shared. Search them before making an agent.

Agents never add or share a template themselves. They ask, and the owner says yes on Home:

- **Add**: `propose_add` with the template's `id`, any answers to its questions you could find (say where, in `found`), and why it fits. The owner places it on their chart and adds it.
- **Share**: `propose_share` with agents by name, or one agent's skill, when the owner asks to share them. The owner reviews what goes out first.

What they return:

- `search`: up to 8, best first, each with `id`, `name`, `kind`, `says`, `from` and what `matched`: `{ "id": "roadstar/chase-a-late-invoice", "name": "Chase a late invoice", "kind": "skill", "from": "Roadstar", "matched": "Name: Chase a late invoice" }`.
- `read`: the whole template: its agents with their jobs, skills and routines, its `questions`, and `youHave`, the agents in it the owner already has by name.
- `propose_add` and `propose_share`: `{ "asked": "…" }`. The ask waits on Home.

See [Home and asks](/how-it-works/home-and-asks/) and [agents and the chart](/how-it-works/agents/).

## How to use it

What `find_tools` sends with these tools, word for word:

> Setups someone already made: an agent, a team, a department or a skill. Search before making an agent. To suggest one, find what answers you can, say where, and propose_add; the owner adds it. propose_share when the owner asks to share. Never add or share yourself.

## Tools

| Tool | What it does | Owner's yes |
| --- | --- | --- |
| [templates.search](#search) | Templates matching words, best first, each with what matched | No |
| [templates.read](#read) | One template in full: its agents, skills, routines and questions | No |
| [templates.propose_add](#propose_add) | Ask the owner to add one, with the answers you found and where | No |
| [templates.propose_share](#propose_share) | Ask the owner to share some of their agents, or one skill, as a template | No |

## search

`templates.search` · Templates matching words, best first, each with what matched.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `query` | text | yes | 1–120 characters |

Returns:

```ts
{
  id: string;
  name: string;
  kind: TemplateKind;
  says: string;
  from: string;
  matched: string;
}[]
```

## read

`templates.read` · One template in full: its agents, skills, routines and questions.

**Owner's yes:** No. Nothing of the owner's changes.

| Input | Type | Required | Limits |
| --- | --- | --- | --- |
| `id` | text | yes | 1–120 characters |

Returns:

```ts
{
  youHave: string[];
  questions: {
    blank: string;
    asks: string;
    kind: FillKind;
  }[];
  skill?: {
    name: string;
    when: string;
    steps: string;
  };
  agents: {
    skills: string[];
    routines: string[];
    under?: string;
    name: string;
    job: string;
  }[];
  department?: string;
  id: string;
  name: string;
  kind: TemplateKind;
  says: string;
  version: number;
}
```

## propose_add

`templates.propose_add` · Ask the owner to add one, with the answers you found and where.

**Owner's yes:** No. It makes something new.\
**Your work:** listed on Home.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `id` | text | yes |  | 1–120 characters |
| `answers` | named values of object | no |  |  |
| `under` | text | no | One of the owner's agents its top agents report to | up to 60 characters |
| `to` | text | no | For a skill: the agent that gets it | up to 60 characters |
| `why` | text | yes | Why it fits, in a line or two the owner reads | 1–400 characters |

Returns:

```ts
{
  asked: string;
}
```

## propose_share

`templates.propose_share` · Ask the owner to share some of their agents, or one skill, as a template.

**Owner's yes:** No. It makes something new.\
**Your work:** listed on Home.

| Input | Type | Required | What it is | Limits |
| --- | --- | --- | --- | --- |
| `agents` | list of text | no | The agents by name | up to 16 items, each 1–60 characters |
| `skill` | object | no |  |  |
| `skill.agent` | text | yes |  | up to 60 characters |
| `skill.name` | text | yes |  | up to 60 characters |
| `why` | text | yes |  | 1–400 characters |

Returns:

```ts
{
  asked: string;
}
```

## Types

Named types in the results above.

```ts
type TemplateKind = "agent" | "skill" | "team" | "department"

type FillKind = "file" | "agent" | "folder" | "text" | "company" | "choice" | "web" | "contact"
```