Project layout
The files and folders of a Plico project.
A Plico project is a folder. plico.config.ts is the anchor, and these entries are
required:
| Path | Purpose |
|---|---|
agent.md | The agent's instructions. |
skills/ | Skills, one folder each with a SKILL.md file. |
tools/ | TypeScript tools, one .tool.ts file per tool. |
evals/ | Scripted evals. |
artifacts/ | Files the agent produces. |
memory/ | Reserved for durable notes. The layout requires it; the agent does not read or write it yet. |
plico validate checks the layout, and projects generated by create-plico pass it.
Reserved names
Plico reserves agents/ and workflows/ as folder names, and entry as a plico.config.ts
key, for multi-agent projects planned for a later release. Plico does nothing with them today.
Avoid them in your own projects so a later upgrade does not change what they mean.
agent.md frontmatter
agent.md may start with a --- frontmatter block. Plico strips it before the instructions go
to the model, and plico validate warns on keys it does not know. No keys are defined yet.
Skills
A skill is a folder in skills/ with a SKILL.md file, the same layout as the Agent Skills
standard. SKILL.md starts with a frontmatter block holding a description: when the agent
should use the skill. The skill name is the folder name. Extra files can sit beside SKILL.md;
Plico does not read or run them yet.
---
description: Review incoming work items and choose the smallest safe next step.
---
# Triage
Review the item, then record the outcome.The instructions list each skill by name and description only. When a skill applies, the agent
calls the built-in load_skill tool with its name and gets the full text. That call is recorded
as tool.call and tool.result events, so it shows in the Studio timeline and replays the same
content after a restart. load_skill only returns files from skills/, and no project tool can
use that name. plico validate rejects a skill with no description, a skill folder with no SKILL.md, and a
flat skills/<name>.md file, with a message naming where to move it.
A run keeps the instructions and skills it started with. If you edit agent.md or a skill while a
run waits for an approval, the run continues with the old text and only new runs use the edit.
A waiting run also resumes if agent.md or a skill is now invalid. Plico records a hash of the
TypeScript files in tools/, and a change to any of them while a run waits ends it with
run.failed before the tool runs.
Configuration
Wrap the config in defineConfig from @plico-ai/sdk to get editor types. It returns its
argument unchanged, and Plico finds it without a node_modules in the project.
import { defineConfig } from "@plico-ai/sdk";
export default defineConfig({
schemaVersion: 1,
name: "My agent",
model: { provider: "anthropic", name: "claude-sonnet-5-5" },
});See Model providers for the model settings.
Set artifacts.access to read-write, read-only, or off to control which
artifact tools the model sees. See Artifacts.
Set threads.title to model to have the model write thread titles, or add an optional
threads/title.ts that default-exports a function from messages to a title. See
Threads.