Expand one skill into text

Reads one skill’s instructions and returns them framed the way the model’s own skill tool frames them — whose they are and which directory their relative paths resolve against — with whatever the person typed after the name appended. The file is read NOW, through the confinement its origin was discovered with, so a skill edited since it was listed is returned as edited and a project skill whose path has since become a symlink out of the checkout is refused. A body that cannot be read comes back as a sentence saying so rather than as an error: the caller asked for text to put in front of a person, and text is what it gets.

POST /v1/skills/{name}/expansion

Expand one skill into text

cURL

curl --request POST \
  --url https://api.example.com/v1/skills/{name}/expansion \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "repository": "/home/dev/repos/narya",
  "arguments": "internal/wire"
}
'

200

{
  "text": "Review the working tree.\n\nOn branch develop\n\ninternal/wire"
}

Authorizations

Authorization · string · header · required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Path Parameters

name · string · required

The skill's name, as listSkills reports it.

Maximum string length: 128

Pattern: ^[^\s/\\]+$

Body

application/json

What to expand a skill or a command file against: the repository the work is happening in, and whatever the person typed after the name.

repository · string

Absolute path of the repository, which decides which rungs are read and — for a command — where its shell blocks run and whether they may. A hosted home runs no shell block. On a hosted home it resolves under the home's workspace, and a path outside it is refused 422.

Maximum string length: 4096

sessionId · string<uuid>

The conversation to expand against, in place of repository (LadderSessionParam): for one whose code lives in an environment, the clone's skill or command is read there and a command's shell blocks run there, never on this host, starting its stopped container first. Naming both is refused 400. An expansion is a read of that conversation: a colleague's of a shared one is in its disclosure audit before any text comes back, and refused when that record cannot be written (listSessionDisclosures).

arguments · string

Everything typed after the name, verbatim. A command file's $ARGUMENTS and $1..$9 are filled from it, AFTER its shell blocks have already run, so text pasted here can never become a block.

Maximum string length: 65536

Response

200

application/json

The expanded text.

The text one expansion produced, ready to be put in front of a person. It is never sent anywhere on their behalf: the whole point of expanding into a composer is that somebody reads what a file wrote in their name before a model does.

text · string · required