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.nameanddescriptionare 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
NominalNotFoundErrorif the registered SKILL.md is missing or another file has taken its path.- created_at: IntegralNanosecondsUTC#
- updated_at: IntegralNanosecondsUTC#
- archive()#
Archive the skill, hiding it from the skills library, Analyst, and connected agents.
- Raises:
NominalPermissionDeniedError – If the user can’t edit the workspace’s configuration, which changing a skill needs.
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 – If the skill’s name or a file’s path could lead outside
pathon this system, such as a path with a backslash or, on Windows, a drive or a colon. Nothing is written.FileExistsError – If
pathalready 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 – If one of the skill’s files is not UTF-8 text.
requests.RequestException – If downloading a file fails.
- Return type:
- get_content()#
Read the skill’s SKILL.md, frontmatter included: the content that
update(content=...)replaces.- Raises:
NominalNotFoundError – If the registered SKILL.md was removed or moved from its recorded folder.
NominalError – If SKILL.md is not UTF-8 text.
requests.RequestException – If downloading the file fails.
- Return type:
- get_load_status()#
Read SKILL.md now and report whether Analyst and connected agents can load the skill.
- Return type:
- list_files()#
List every file in the skill’s folder, SKILL.md included, by path.
- Raises:
NominalError – If the skill’s SKILL.md is not at
skills/<name>/SKILL.md, so it has no folder.- Return type:
- read_file(path)#
Read one file in the skill’s folder, such as
SKILL.mdormethods/limits.md.- Raises:
ValueError – If
pathleads outside the skill’s folder.NominalNotFoundError – If the skill has no file at this path.
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:
- remove_files(paths)#
Remove reference files from the skill’s folder.
The files are removed together or not at all.
- Raises:
ValueError – If a path is SKILL.md or leads outside the skill’s folder, or there are more than 100 paths. Nothing is removed.
NominalPermissionDeniedError – If the user can’t edit the workspace’s configuration, which changing a skill needs. Nothing is removed.
NominalNotFoundError – If the skill has no file at one of the paths. Nothing is removed.
NominalConflictError – If another save changed one of the files while it was being removed. Nothing is removed.
- Return type:
- 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 – 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
contentreplaces SKILL.md as it is now; read it withget_content()first to keep such edits.- Parameters:
content (str | 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 | None)
Whether the skill is turned on. Turning it on needs a valid SKILL.md, and an archived skill must be restored with
unarchive()first. Turning off an archived skill restores it turned off, asunarchive()does.
- Return type:
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 – If the name is invalid, or enabled content exceeds 64 KiB or has invalid metadata. Nothing is saved.
NominalError – If
enabledis True and the skill is archived. Nothing is saved.NominalPermissionDeniedError – If the user can’t edit the workspace’s configuration, which changing a skill needs. Nothing is saved.
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 – If a skill already has the new name. Nothing is saved.
NominalNotFoundError – If
contentis 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 – 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:
- 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:
-
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 withupdate(). - Raises:
ValueError – If a path is SKILL.md or leads outside the skill’s folder, or there are more than 100 files. Nothing is saved.
NominalPermissionDeniedError – If the user can’t edit the workspace’s configuration, which changing a skill needs. Nothing is saved.
NominalConflictError – If another save changed or created one of the files while it was being saved. Nothing is saved.
- Return type: