# Project layout (/docs/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.

```md title="skills/triage/SKILL.md"
---
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.

```ts title="plico.config.ts"
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](/docs/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](/docs/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](/docs/threads#model-written-and-custom-titles).