# Skill

## class nominal.experimental.analyst.Skill(rid, workspace_rid, name, description, is_enabled, is_archived, version, created_at, updated_at)

Bases: `HasRid`, `RefreshableGrpcMixin`[`Skill`]

A skill in a workspace’s skills library: a SKILL.md, and any reference files, that Analyst and connected
agents follow. Its files are in the folder `skills/<name>` of the workspace’s skills drive.

[`name`](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.Skill.md#nominal.experimental.analyst.Skill.name "nominal.experimental.analyst.Skill.name") and [`description`](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.Skill.md#nominal.experimental.analyst.Skill.description "nominal.experimental.analyst.Skill.description") are what the library last recorded from SKILL.md’s frontmatter, and are None when it had
no valid frontmatter. This client records them each time it saves SKILL.md.

Folder operations raise `NominalNotFoundError` if the registered SKILL.md is missing or another file has
taken its path.

### rid: str

### workspace_rid: str

### name: str | None

### description: str | None

### is_enabled: bool

### is_archived: bool

### version: int

### created_at: IntegralNanosecondsUTC

### updated_at: IntegralNanosecondsUTC

### archive()

Archive the skill, hiding it from the skills library, Analyst, and connected agents.

Raises:
:   - [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the user can’t edit the workspace’s configuration, which changing a
      skill needs.
    - [**NominalConflictError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConflictError.md#nominal.exceptions.NominalConflictError "nominal.exceptions.NominalConflictError") – If the skill changed since this object was fetched or last refreshed.

### export(path)

Write the skill’s current folder, named after the skill, under `path`, and return the folder.

Every file is read before any is written.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the skill’s name or a file’s path could lead outside `path` on this system, such as a path
      with a backslash or, on Windows, a drive or a colon. Nothing is written.
    - [**FileExistsError**](https://docs.python.org/3/builtins/exceptions.html#FileExistsError "(in Python v3.15)") – If `path` already has an entry with the skill’s name, or two of the skill’s files land on
      the same file on this system, such as names differing only in case where case is ignored. The files
      written before the second one stay.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If one of the skill’s files is not UTF-8 text.
    - **requests.RequestException** – If downloading a file fails.

Return type:
:   [*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)")

### get_content()

Read the skill’s SKILL.md, frontmatter included: the content that `update(content=...)` replaces.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If the registered SKILL.md was removed or moved from its recorded folder.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If SKILL.md is not UTF-8 text.
    - **requests.RequestException** – If downloading the file fails.

Return type:
:   [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")

### get_load_status()

Read SKILL.md now and report whether Analyst and connected agents can load the skill.

Return type:
:   [*SkillLoadStatus*](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.SkillLoadStatus.md#nominal.experimental.analyst.SkillLoadStatus "nominal.experimental.analyst._skill.SkillLoadStatus")

### list_files()

List every file in the skill’s folder, SKILL.md included, by path.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the skill’s SKILL.md is not at `skills/<name>/SKILL.md`, so it has no folder.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence "(in Python v3.15)")[[*SkillFileInfo*](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.SkillFileInfo.md#nominal.experimental.analyst.SkillFileInfo "nominal.experimental.analyst._skill.SkillFileInfo")]

### read_file(path)

Read one file in the skill’s folder, such as `SKILL.md` or `methods/limits.md`.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `path` leads outside the skill’s folder.
    - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If the skill has no file at this path.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the file is not UTF-8 text. The client reads and writes text files only.
    - **requests.RequestException** – If downloading the file fails.

Return type:
:   [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")

### refresh()

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### remove_files(paths)

Remove reference files from the skill’s folder.

The files are removed together or not at all.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If a path is SKILL.md or leads outside the skill’s folder, or there are more than 100 paths.
      Nothing is removed.
    - [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the user can’t edit the workspace’s configuration, which changing a
      skill needs. Nothing is removed.
    - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If the skill has no file at one of the paths. Nothing is removed.
    - [**NominalConflictError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConflictError.md#nominal.exceptions.NominalConflictError "nominal.exceptions.NominalConflictError") – If another save changed one of the files while it was being removed. Nothing is
      removed.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### unarchive()

Restore an archived skill. It comes back turned off; turn it on with `update(enabled=True)`.

Refreshes this object first, and does nothing when the skill is not archived.

Raises:
:   [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the user can’t edit the workspace’s configuration, which changing a
    skill needs.

### update(*, content=None, enabled=None)

Update the skill in place. Fields left as None are unchanged.

Each change is saved only if the skill’s record hasn’t changed since this object was fetched or last
refreshed. Edits made to the skill’s files in Drives don’t change its record, so `content` replaces SKILL.md as
it is now; read it with [`get_content()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.Skill.md#nominal.experimental.analyst.Skill.get_content "nominal.experimental.analyst.Skill.get_content") first to keep such edits.

Parameters:
:   - **content** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      The skill’s new SKILL.md, frontmatter included, replacing the current one. A new name in its
      frontmatter renames the skill: its folder moves to `skills/<new name>`, and it keeps its RID.
    - **enabled** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      Whether the skill is turned on. Turning it on needs a valid SKILL.md, and an archived skill must
      be restored with [`unarchive()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.Skill.md#nominal.experimental.analyst.Skill.unarchive "nominal.experimental.analyst.Skill.unarchive") first. Turning off an archived skill restores it turned off, as
      [`unarchive()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.Skill.md#nominal.experimental.analyst.Skill.unarchive "nominal.experimental.analyst.Skill.unarchive") does.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

SKILL.md and, for a rename, the move of its folder are saved together or not at all. Then the skill records
its new name and description.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the name is invalid, or enabled content exceeds 64 KiB or has invalid metadata.
      Nothing is saved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If `enabled` is True and the skill is archived. Nothing is saved.
    - [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the user can’t edit the workspace’s configuration, which changing a
      skill needs. Nothing is saved.
    - [**NominalConflictError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConflictError.md#nominal.exceptions.NominalConflictError "nominal.exceptions.NominalConflictError") – If the skill changed since this object was fetched or last refreshed, or SKILL.md
      changed while it was being saved. Nothing is saved.
    - [**NominalAlreadyExistsError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalAlreadyExistsError.md#nominal.exceptions.NominalAlreadyExistsError "nominal.exceptions.NominalAlreadyExistsError") – If a skill already has the new name. Nothing is saved.
    - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If `content` is given and the SKILL.md the skill points at is no longer in its
      folder, for example because it was deleted, or deleted and re-created, in Drives. Nothing is saved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the file is saved and the record update returns an error. Read the skill again before
      retrying, since a lost response can follow a successful update.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### write_files(files)

Add or replace reference files in the skill’s folder, replacing each file as it is now.

The files are saved together or not at all.

Parameters:
:   **files** ([*Mapping*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

    UTF-8 text keyed by path relative to the skill’s folder, such as `methods/limits.md`. SKILL.md
    is not a reference file; change it with [`update()`](https://dev.nominal.io/python/ref/generated/nominal.experimental.analyst.Skill.md#nominal.experimental.analyst.Skill.update "nominal.experimental.analyst.Skill.update").

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If a path is SKILL.md or leads outside the skill’s folder, or there are more than 100 files.
      Nothing is saved.
    - [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the user can’t edit the workspace’s configuration, which changing a
      skill needs. Nothing is saved.
    - [**NominalConflictError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConflictError.md#nominal.exceptions.NominalConflictError "nominal.exceptions.NominalConflictError") – If another save changed or created one of the files while it was being saved.
      Nothing is saved.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")
