Agent skill#

plone-client ships an Agent Skill: a SKILL.md file that teaches a coding agent its commands, its output, the Volto content model, and the safety rules. Use plone-client with coding agents installs it.

Where skill install writes#

Command

File

plone-client skill install

.claude/skills/plone-client/

plone-client skill install --user

~/.claude/skills/plone-client/

plone-client skill install --dir DIR

DIR/plone-client/

Changed in version 1.0.0a4: The skill has a second file, references/blocks.md, and skill show takes the name of a file.

The folder holds SKILL.md, which an agent reads first, and references/blocks.md, which it reads when it works with blocks. The command replaces an older copy, and prints installed, with the path of SKILL.md, and replaced. plone-client skill show prints SKILL.md, and plone-client skill show references/blocks.md prints the reference.

Directories each agent reads#

Agent

In a project

For a user

Claude Code

.claude/skills

~/.claude/skills

Codex

.agents/skills, from the working directory up to the repository root

~/.agents/skills

Cursor

.agents/skills, .cursor/skills, and, for compatibility, .claude/skills, .codex/skills

~/.agents/skills, ~/.cursor/skills, and, for compatibility, ~/.claude/skills, ~/.codex/skills

Gemini CLI

.agents/skills, .gemini/skills

~/.agents/skills, ~/.gemini/skills

VS Code

.agents/skills, .claude/skills, .github/skills

~/.agents/skills, ~/.claude/skills, ~/.copilot/skills

The skill#

---
name: plone-client
description: Read and change content on a Plone site with the plone-client command line — list, search, create, update, publish, upload, and delete items, write Volto pages and blocks, manage users and groups, and call any plone.restapi service. Use when the user asks to work with a Plone site's content or configuration, or mentions plone-client, plone.restapi, Volto content, or a Plone profile.
---

# plone-client

`plone-client` talks to a Plone site through `plone.restapi`.
Results are JSON on standard output; errors are JSON on standard error with a meaningful exit code.

## Rules

- Never ask for passwords and never call the REST API with `curl`.
  The profiles already hold the credentials, in the system keyring.
- Never create, change, or remove profiles unless the user asks; run `plone-client profile list` to see which exist.
- Before changing a site other than a local one, run the command with `-n` (dry run) and show the user the requests it would send.
- Never pass `--yes` to `delete`, `users delete`, or `groups delete` unless the user confirmed the exact items.
- Exit code 7 means the profile refused the change: it is read-only, or it does not allow that workflow transition. Do not work around it; tell the user.
- A dry run shows the request, not the site's answer: apart from a `warning` on a refused type, a request that passes `-n` can still fail.
- Use `-f` to keep only the keys you need, so the output stays small.
- Read the `@id` of what a command creates: the site may change the id you asked for (`/blocks` became `/blocks-1`).
- After a change that matters, read the item back: a success does not prove that every field was stored.

## Choosing the site

The profile comes from, in order: `-p <name>`, `$PLONE_CLIENT_PROFILE`, a `.plone-client.toml` file (`profile = "<name>"`) in the working directory or a parent, and the current profile.

```shell
plone-client profile list          # profiles and which one is current
plone-client info                  # site, user, and Plone version
plone-client -p production get /   # one command against another profile
```

## Items

`<ref>` is a path (`/news/item`), a URL inside the site, `uid:<UID>`, or a `resolveuid` link.

```shell
plone-client get /news/item -f @id,title,review_state
plone-client ls /news -f @id,title,review_state
plone-client search /news -q "keyword" -t "News Item" --state published --limit 10 -f @id,title
plone-client search -i Subject=plone --count
plone-client resolve uid:0123456789abcdef
plone-client history /news/item
plone-client sharing /news/item
```

## Changes

`create` and `update` take field values from `-d` (JSON object, `@file.json`, or `-` for stdin), then `-s` (repeatable: `key=text` for a string, `key:=json` for any JSON value), then `--title` and `--description`; later ones win.

```shell
plone-client create /news "News Item" --title "Title" --description "Summary" --publish publish
plone-client update /news/item -s subjects:='["plone", "release"]'
plone-client update /news/item -d @fields.json
plone-client workflow /news/item                  # state and available transitions
plone-client workflow /news/item publish
plone-client workflow /news publish --recursive
plone-client copy /news/item --to /archive
plone-client move /news/old --to /archive
plone-client order /news item top
plone-client delete /news/old --yes               # only after the user confirmed
plone-client upload /news/item photo.jpg report.pdf
plone-client download /news/item/photo.jpg
```

Commands that change an item print `@id`, `@type`, `UID`, `id`, `title`, and `review_state`; add `--full` for the whole item.

## Tasks of several steps

These commands send several requests in the right order and print every one of them, with what they created.
If one stops part way, its error has a `result` with what was already created; report it to the user.

```shell
plone-client create-page /docs page.md --publish publish        # Markdown (or --html) to blocks; # heading = title
plone-client create-page /docs - --title "Notes" < notes.md
plone-client create-with-files /news "News Item" lead.jpg more.jpg --title "Title" --publish publish
plone-client create-page /news story.md --type "News Item" --file lead.jpg --publish publish   # page with files and lead image
plone-client upload-tree ./handbook /docs --pages               # folders as pages, .md files as pages
```

`create-page` and `upload-tree --pages` need the `markdown` extra; exit code 3 means it is missing.
`--blocks '{"codeBlock": true}'` chooses the block types the Markdown becomes (code blocks, here), merged over the profile's `blocks` setting; an unknown block type is exit code 2.

## Content model

- Run `plone-client types <type>` before setting fields: the site silently ignores fields a type does not have.
- On Volto sites `Folder` usually cannot be added; `-n` adds a `warning` to an item the site would refuse.
  For a section such as `/news`, create a `Document`, which is folderish; `plone-client types --addable-in <path>` lists what a folder can hold.
- A News Item's lead image on a Volto site is `preview_image_link`, a relation to an Image inside the item; other sites have an `image` field.
  `create-with-files` picks the right one from the type's schema.
- New items are private until a workflow transition such as `publish` runs; `create` and `create-page` take `--publish`.

## Blocks

The text of a Volto page lives in blocks, not in a text field, and a page without them shows nothing.
To write prose, use `create-page`.
`create` adds a title block and a description block, unless given `--no-blocks` or `blocks` in the data.

`update` with `blocks` replaces all of them.
Before you write or change blocks, read [references/blocks.md](references/blocks.md), or run `plone-client skill show references/blocks.md`.

## Site administration

```shell
plone-client users list -f id,email
plone-client groups add-member Editors jdoe
plone-client registry get plone.site_title
plone-client registry set plone.site_title '"New title"'
plone-client vocabulary plone.app.vocabularies.Keywords
plone-client aliases list /news/item
```

## Anything else

`request` sends any request, for services without a command.

```shell
plone-client request GET /@navroot
plone-client request GET /@search -P portal_type=Image -P b_size=5
plone-client request POST /news/item/@lock -d '{}'
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected error, or a refused confirmation |
| 2 | Invalid usage, invalid JSON, or a destructive command without `--yes` |
| 3 | Configuration: unknown profile, missing secret, no site configured |
| 4 | Not authenticated, not allowed, the item is locked, or the type cannot be added here |
| 5 | Not found |
| 6 | Invalid request or conflict, such as an id in use or an invalid field |
| 7 | Refused by a read-only profile, `--read-only`, or a transition the profile does not allow |
| 8 | The site could not be reached |
| 9 | Server error |

Run `plone-client <command> --help` for every option of a command.

The reference on blocks#

# Blocks

Read this before you write or change the blocks of a page on a Volto site.

## Pick the simplest way

| Goal | Use |
|---|---|
| Write a page from prose | `plone-client create-page`, which converts Markdown or HTML to blocks. |
| Change a title or another field | `plone-client update`; the blocks stay as they are. |
| Add, change, or reorder blocks | Read the blocks, edit them, and write them back, as shown below. |
| Show a block Markdown cannot express, such as a grid | Write its JSON by hand, after you read its documentation. |

## How a page stores blocks

Two fields hold the content, and a page needs both.

- `blocks` maps ids to block data, and each block has an `@type`.
- `blocks_layout.items` lists the ids in display order.

Ids are any unique strings.
Every id in `blocks` must also be in `blocks_layout.items`.
A block that is missing from the layout stays stored, and Volto does not show it, although `plone-client blocks` still lists it.

## Learn what the site offers

Each site has its own blocks, and each block has its own data, so ask before you write one.

```shell
plone-client block-types --markdown                  # the blocks of the site
plone-client block-types gridBlock --markdown        # the data one block takes
plone-client block-types --for /news/item --markdown # what editors can add to this item
```

If the answer has `"source": "builtin"`, or a warning about `@blocks-schema`, it describes only Volto's core blocks, and the site did not say which blocks it has.
This happens on Volto before 19.6, or when the profile has no frontend URL.
Tell the user before you rely on a block from an add-on.

## Read the blocks

```shell
plone-client blocks /news/item                 # ids, types, and text, nested blocks included
plone-client blocks /news/item --links         # the links in each block
plone-client get /news/item -f blocks,blocks_layout > page.json   # the full data
```

## Create a page from JSON

Give `blocks` as a mapping, with `blocks_layout`.
The command line refuses a list of blocks with exit code 6 and `Wrong contained type`.

```json
{
  "blocks": {
    "title-1": {"@type": "title"},
    "text-1": {
      "@type": "slate",
      "value": [{"type": "p", "children": [{"text": "First paragraph."}]}],
      "plaintext": "First paragraph."
    }
  },
  "blocks_layout": {"items": ["title-1", "text-1"]}
}
```

```shell
plone-client create /docs Document --title "Page" -d @page.json
```

With `blocks` in the data, `create` adds no title or description block, so include the ones you want.
A page normally has exactly one `title` block.

## Change the blocks

`update` replaces all the blocks, so a file with one block leaves a page with one block.
Always start from what the site has.

1. Read the page: `plone-client get /docs/page -f blocks,blocks_layout > page.json`.
2. Edit `page.json`: change a block, or add one to `blocks` and its id to `blocks_layout.items`.
3. Preview it, if the site is not a local one: `plone-client -n update /docs/page -d @page.json`.
4. Write it: `plone-client update /docs/page -d @page.json`.
5. Check the result: `plone-client blocks /docs/page`.

To reorder blocks, send only the layout.

```shell
plone-client update /docs/page -s 'blocks_layout:={"items": ["text-1", "title-1"]}'
```

## Common blocks

Text is a `slate` block, with one paragraph, heading, list, or quote in each block.
Keep `plaintext` in sync with `value`, because the site indexes it for search.

```json
{
  "@type": "slate",
  "value": [{"type": "h2", "children": [{"text": "Our services"}]}],
  "plaintext": "Our services"
}
```

A teaser links to one item, and shows its title, description, and image.

```json
{"@type": "teaser", "href": [{"@id": "/news/item", "title": "Item"}]}
```

A grid holds up to four blocks in its own `blocks` and `blocks_layout`, and those need their ids too.
For the others, and for inline formatting and links in text, read `plone-client block-types <block> --markdown`.

## From Python or MCP

These helpers exist only outside the command line.

- The `plone_client.blocks` module builds blocks with new ids and a layout: `build`, `title`, `description`, `text`, `block`, `grid`, `teaser`, and `container`.
- The MCP tools take blocks as a list, make the ids and the layout, and change one block at a time with `add_blocks`, `update_block`, and `remove_blocks`.