Skills#

A skill gives Analyst, Nominal’s AI assistant, instructions for a repeatable task such as a post-test review. Creating or changing a skill requires permission to edit the workspace’s configuration.

Connect the client#

This guide assumes you have installed the client and setup your API keys.

Import the experimental Analyst module. Its interfaces may change between releases:

from nominal.experimental import analyst

Find and read skills#

Use search_skills() to find skills by name or description:

skills = analyst.search_skills(client, "review")  # Omit the text to list all unarchived skills.
# Add enabled=True to search only skills that are turned on.
for skill in skills:
    # Load status is an enum such as AVAILABLE, INVALID, or MISSING.
    print(skill.name, skill.is_enabled, skill.get_load_status())

Read the instructions in SKILL.md and the files the skill refers to:

skill = analyst.get_skill(client, "<SKILL_RID>")  # Or use a skill returned by search_skills.
print(skill.get_content())  # The current SKILL.md.
for file in skill.list_files():
    print(file.path, file.size_bytes)
    if file.path != "SKILL.md":
        print(skill.read_file(file.path))

Create or import a skill#

Use create_skill() to save instructions and reference files. SKILL.md follows the Agent Skills format, with a name and description in its YAML frontmatter. Each workspace shares a skills library. Skills are enabled by default, so pass enabled=False while preparing instructions you are not ready for others to use:

skill_md = """---
name: post-test-review
description: Review a test run against its test plan and flag anomalies.
---

1. Read the test plan.
2. Compare each channel against its limits in methods/limits.md.
"""
skill = analyst.create_skill(
    client,
    skill_md,
    # Reference files are keyed by path within the skill's folder.
    files={"methods/limits.md": "Use the limits in the test plan's appendix.\n"},
    enabled=False,
)

Choose a unique name in the workspace using lowercase letters, digits and single hyphens. The client reads and writes UTF-8 text files. See create_skill() for validation rules.

If you already have a folder with SKILL.md at its top level, or a .zip containing one, use import_skill() instead:

skill = analyst.import_skill(client, "skills/post-test-review", enabled=False)

Import skips dot-prefixed files and folders, such as .git, and folder imports skip symbolic links. If creation or import fails, check the error’s notes before retrying. A timeout can leave a skill or its files saved. When the notes give a skill RID, fetch it with analyst.get_skill(client, rid) to check its state.

Edit a skill#

Use update() to replace SKILL.md or turn a skill on or off. Changing the name in its frontmatter renames the skill. Use write_files() to add or replace reference files, and remove_files() to remove them:

content = skill.get_content()  # Start from the saved instructions, including edits made outside this script.
skill.update(content=content.replace("flag anomalies", "flag and summarize anomalies"))
skill.write_files({"templates/summary.md": "## Summary\n"})
skill.remove_files(["templates/summary.md"])
skill.update(enabled=True)  # Make the prepared skill available to Analyst.

If the skill has changed since you fetched it, update raises NominalConflictError without saving your edit. Call skill.refresh(), read skill.get_content() again, and reapply your edit to that content before retrying. write_files and remove_files can also raise this error when a file changes during a save. Review the current files before retrying those operations.

If an error says SKILL.md was saved but the skill record could not be updated, fetch the skill and read its content before retrying. Some changes have already been saved.

Archive and restore a skill#

Use archive() to hide a skill from the library and stop making it available to agents. unarchive() brings it back turned off:

skill.archive()
skill.unarchive()
skill.update(enabled=True)

To find an archived skill, include archived results in your search:

Export a skill#

Use export() to save a local copy of SKILL.md and its reference files. Export creates a new folder named after the skill and refuses to overwrite an existing folder. Keep the folder in git, or import it into another workspace:

folder = skill.export("exported-skills")  # exported-skills/post-test-review
analyst.import_skill(client, folder, workspace="<WORKSPACE_RID>", enabled=False)