Configure the workspace

Environment Skills

Install, update and remove reusable Skill packages.

On this page

Package reusable instructions

An Environment Skill is a named package containing a SKILL.md and optional UTF-8 supporting files. The native harness discovers Skills in its prepared directory before each Run. Platform and interactive Sandpi share package validation and RootFS storage.

Use agents.md for instructions applying to every task; use a Skill for a reusable workflow that a harness can discover and select.

Install a Skill

Use the console’s Environment Configuration tab or upload a package through the API. Set the Skill path variable to your package’s name and ensure its frontmatter matches the intended package identity.

Create or replace an Environment Skill

PUT /v1/environments/{environmentId}/skills/{skillName}

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string	Yes	Environment identifier. It must belong to the caller’s account or Project.
`path: skillName`	string · min length 1; max length 64 Validation pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`	Yes	Skill package name. Use the same name in SKILL.md frontmatter.

Request example

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/skills/review-code" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "files": [
    {
      "path": "SKILL.md",
      "content": "---\nname: review-code\ndescription: Review code changes.\n---\n\nCheck correctness and summarize findings.\n"
    }
  ]
}'

Request body · required `application/json`

Maximum bytes: 2,097,152

Replace the complete package. Requires a unique SKILL.md with matching name and description frontmatter. At most 1 MiB of decoded UTF-8 content.

Field	Type and constraints	Required	Description
`files`	array · min 1 items; max 64 items	Yes	Files associated with this resource; each item is described below.
`files[]`	object · extra fields rejected	Yeseach array item	UTF-8 file inside a Skill package.
`files[].path`	string · min length 1; max length 240	Yeseach array item	Relative UTF-8 support file path. Hidden, empty and parent components are rejected.
`files[].content`	string	Yeseach array item	UTF-8 text for this package file; binary content is not supported.

Example

{
  "files": [
    {
      "path": "SKILL.md",
      "content": "---\nname: review-code\ndescription: Review code changes.\n---\n\nCheck correctness and summarize findings.\n"
    }
  ]
}

Responses

200 Success

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Complete user-managed or built-in Skill package.
`data.name`	string	Yeswithin data	Human-readable name for this resource.
`data.description`	string	Yeswithin data	Skill description from SKILL.md frontmatter, used by native discovery.
`data.files`	array	Yeswithin data	Files associated with this resource; each item is described below.
`data.files[]`	object · extra fields rejected	Yeseach array item	UTF-8 file inside a Skill package.
`data.files[].path`	string · min length 1; max length 240	Yeseach array item	Relative UTF-8 support file path. Hidden, empty and parent components are rejected.
`data.files[].content`	string	Yeseach array item	UTF-8 text for this package file; binary content is not supported.

Example

{
  "data": {
    "name": "",
    "description": "",
    "files": [
      {
        "path": "example",
        "content": ""
      }
    ]
  }
}

Error responses

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

All package paths are relative to the Skill. The API details owns the exact file and byte constraints. Built-in Skills are read-only.

Inspect and update

List Environment Skills

GET /v1/environments/{environmentId}/skills

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string	Yes	Environment identifier. It must belong to the caller’s account or Project.

Request example

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/skills" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

200 Success

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	array	Yes	Successful result wrapped by the API. The child fields describe its content.
`data[]`	object · extra fields rejected	Yeseach array item	Discovered Skill identity, source and package size.
`data[].name`	string	Yeseach array item	Human-readable name for this resource.
`data[].description`	string	Yeseach array item	Skill description from SKILL.md frontmatter, used by native discovery.
`data[].source`	string · values: "sandpi" \| "environment"	Yeseach array item	Origin of this resource, as identified by the allowed values.
`data[].fileCount`	integer · ≥ 1	Yeseach array item	Number of files in the Skill package.

Example

{
  "data": [
    {
      "name": "",
      "description": "",
      "source": "sandpi",
      "fileCount": 1
    }
  ]
}

Error responses

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Read an Environment Skill

GET /v1/environments/{environmentId}/skills/{skillName}

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string	Yes	Environment identifier. It must belong to the caller’s account or Project.
`path: skillName`	string · min length 1; max length 64 Validation pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`	Yes	Skill package name. Use the same name in SKILL.md frontmatter.

Request example

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/skills/review-code" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

200 Success

Response body `application/json`

Field	Type and constraints	Required	Description
`data`	object · extra fields rejected	Yes	Complete user-managed or built-in Skill package.
`data.name`	string	Yeswithin data	Human-readable name for this resource.
`data.description`	string	Yeswithin data	Skill description from SKILL.md frontmatter, used by native discovery.
`data.files`	array	Yeswithin data	Files associated with this resource; each item is described below.
`data.files[]`	object · extra fields rejected	Yeseach array item	UTF-8 file inside a Skill package.
`data.files[].path`	string · min length 1; max length 240	Yeseach array item	Relative UTF-8 support file path. Hidden, empty and parent components are rejected.
`data.files[].content`	string	Yeseach array item	UTF-8 text for this package file; binary content is not supported.

Example

{
  "data": {
    "name": "",
    "description": "",
    "files": [
      {
        "path": "example",
        "content": ""
      }
    ]
  }
}

Error responses

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Replace the package to update it. Skill operations need the same lifecycle and checkpoint fence as workspace files, so wait for active work to finish. Edits affect later Runs; a running harness may require a reload to discover changed content.

Remove a package

Delete an Environment Skill

DELETE /v1/environments/{environmentId}/skills/{skillName}

Authentication: Platform API bearer token

Parameters and headers

Field	Type and constraints	Required	Description
`path: environmentId`	string	Yes	Environment identifier. It must belong to the caller’s account or Project.
`path: skillName`	string · min length 1; max length 64 Validation pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`	Yes	Skill package name. Use the same name in SKILL.md frontmatter.

Request example

curl -X DELETE \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/skills/review-code" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

No request body.

Responses

204 Success

Empty response body.

Error responses

default Sandpi error.

Error body `application/json`

Standard error envelope containing a stable code, diagnostic message and request identity.

Field	Type and constraints	Required	Description
`error`	object · extra fields rejected	Yes	Structured failure information. Inspect the stable code and retain the request ID for investigation.
`error.code`	string	Yeswithin error	Stable error code used to distinguish failures programmatically.
`error.message`	string	Yeswithin error	Human-readable diagnostic text.
`error.requestId`	string	Yeswithin error	Request identifier for correlating diagnostics and support investigations.
`error.details`	any	Nowithin error	Optional structured error context. Its shape is specific to the service failure.
`error.loginUrl`	string	Nowithin error	Authentication URL supplied when a browser login is required.
`error.registrationOpen`	boolean	Nowithin error	Whether new account registration is enabled for this deployment.

Example

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Removal stops later discovery of that user Skill. Skills are workspace content, so selected RootFS forks and rollback follow the selected checkpoint’s files. See forks and workspace files.

Environment Skills

Package reusable instructions

Install a Skill

Create or replace an Environment Skill

Parameters and headers

Request example

Request body · required application/json

Responses

Response body application/json

Error body application/json

Inspect and update

List Environment Skills

Parameters and headers

Request example

Responses

Response body application/json

Error body application/json

Read an Environment Skill

Parameters and headers

Request example

Responses

Response body application/json

Error body application/json

Remove a package

Delete an Environment Skill

Parameters and headers

Request example

Responses

Error body application/json

Request body · required `application/json`

Response body `application/json`

Error body `application/json`

Response body `application/json`

Error body `application/json`

Response body `application/json`

Error body `application/json`

Error body `application/json`