Agent Spec Guide

How the specs an agent runs meet, where each is kept and how its values are written. Each field is in the Agent Spec reference.

Opinions, not decisions

A decision is in the code: what anyone with the facts would choose, such as Telegram's 4,096 characters a message, or how often its documentation says a bot may write. A model's own figures are facts too, so they are data. Its window, longest answer and price are in Link's file and yours (lnk model show).

An opinion

An opinion is a key here: a trade reasonable people make differently, such as how much of the window to pay for. Link's own opinions are a spec of their own, link_core's agent_spec/link.toml, printed whole by lnk agent spec show, so someone with the opposite ones changes only the file.

Specs meet as sets

An agent runs three specs as one: Link's, then each of its teams', then its own. Each is a set of keys, and any of them may be partial. The agent runs their union, with a key from a later set winning, key by key. A table of yours replaces only the keys it has.

What lnk agent spec show prints

The union, each key marked yours, a team's or Link's, and [storage] as this machine keeps each collection, a place it overrode marked this machine's, naming the one the agent prefers (in --json's from: {"from": "machine", "name": "<preferred>"}).

A general key beats the specific ones before it

Your [model] default replaces Link's [model.anthropic] default too, your [connections] working Link's [connection.slack] working, and [tools] answer a [tool.<name>] answer set before. A specific key in the same set as the general one still wins for its provider, connection or tool. An empty reaction (working = "") is none.

The union must be whole

Every key Link's spec has must be in it, but for those with a fallback ([window] max, the model names and the reactions) and each tool's own ([tool.<name>]). With extends = "none", Link's set is empty, so yours must have them all. A key no set holds refuses the start and names it. A feature's switch is never needed: left out, the feature is off.

A tool's keys

A tool's keys are its tool's to need: a tool the agent runs says which it lacks when it starts (its spec sets no [tool.scheduler] per_day), so a spec that extends none sets only the tables of the tools it runs.

Teams agree, or you settle it

Two teams setting one key differently refuse the start, unless the agent's own spec sets it.

What isn't an opinion isn't yours to claim

name is what Link knows of the agent here: a spec naming another agent is refused. Whose it is and its teams are no spec's keys at all: its saved setup keeps its owner and each team's file its members, so lnk agent spec show prints neither.

Where is the machine's to grant

[storage] is a preference: each collection is kept where the union says if the machine supports it, else at the machine's default, and lnk agent spec show marks each key the machine overrode (Specs).

Counts are yours

rounds, calls and the scheduler's caps take any number from 1 to 65,535. Within that range, counts above the warning thresholds of 64 rounds, 128 calls, or 64 subagents or hops are allowed, and lnk agent start says so. The scheduler’s daily-message cap still cannot exceed 65,535.

Storage

Everything an agent keeps is in six collections, each read and written through one storage bridge, whatever keeps it. On file, home is Home/ and each other Agent/<collection>/.

instructions and skills

Its instructions and its skills, which you edit. [instructions]'s files are in the agent's collections, their first part naming which: instructions/base.md is in instructions, and the agent's notes, memory/notes.md, in memory.

home, memory, conversations and schedule

home is the person's: documents, work, and the documents memory searches. The others are memory's notes and index, its conversations, and its scheduled jobs.

How a place keeps one

A place keeps a collection however its driver does, the same to the agent and its tools: the bridge reads, writes, lists and removes, adds to a file at its end, and leases a turn, so two copies of an agent never both write one. A harness from outside Link keeps its own conversations however it does; the rest are Link's.

file

Each collection a folder of the agent's on this machine (Configuration); a conversation is a file only added to. It keeps every collection.

sqlite

Each collection rows of one SQLite file in the agent's folder, lnk-sqlite-store. It keeps all but home.

bucket

Each collection objects in the agent's bucket, the one lnk storage connected for it, encrypted, with a cache of memory's index on this machine. It keeps every collection.

A place's driver

A place whose driver isn't installed installs as a module a feature needs does. A place's driver refuses what it doesn't serve, and the machine's [storage] never lists a place for a collection its driver refuses.

Values

How a spec writes a size, a duration and how hard a model thinks, and what it refuses.

Sizes and durations

A size is a number and B, KB, MB or GB, powers of 1024. A duration is a number and ms, s, m, h or d.

Thinking

On Anthropic's newer models, the effort the model thinks at, and off the least it can, as some always think. On a model that takes a budget, thinking_budget tokens, under the answer's. On OpenAI's reasoning models, the reasoning effort. A model Link doesn't know isn't asked to think.

A tool's own keys

tool.memory's keys are memory's only, tool.scheduler's the scheduler's, fetch web's, and output run's. Another tool's table with one is refused. Link Harness sends each tool its own table with every call, so one tool shared by many agents follows each one's.

What's refused

An unknown key or table, an empty table, or a value out of range is refused, naming the line.

Where it's kept

Yours is the agent's, a team's is the team's, and neither grants what the agent reaches.

Yours

lnk agent start --spec <file> reads a standalone behavior spec strictly, checks its resolved values, and keeps them under [behavior] in ~/Link/Safe/Agents/<agent>/agent.toml, beside its setup. Generated configuration contains concrete defaults without an extends pointer. Examples on this page are standalone specs. When editing saved configuration, prefix their sections with behavior, such as [behavior.tool.file]. Every start reads it again and a move carries it. A standalone spec setting [harness] selects that harness in setup.

Link rewrites only [access], through lnk agent share and unshare, the rest of the file and its comments kept: what a machine overrides is shown, not written back.

Never a grant of what it reaches

What the agent may reach is its sandbox file beside it, sandbox.toml (lnk agent start --sandbox, lnk agent permission add): a spec repeats nothing of it (Choose what your agent can reach). A spec's [access] says only who may ask it (Who may talk to it), and whoever may can make it do all its sandbox file allows.

A team's

~/Link/Safe/Teams/<team>.toml, the opinions its members share beneath their own (Team Spec).

More about it

Why it works this way: decisions.md. Every spec Link reads, side by side: Specs.