roboto.domain.skills

Create a new skill plus its first version (version=1).

The skill is created in the caller’s organization. With the default SkillAccessibility.Private accessibility only the caller can see, edit, or delete it. SkillAccessibility.Org makes it readable by all org members (author-only to edit); SkillAccessibility.OrgEditable additionally lets any member who subscribes edit its versions, name, and tags. The author is auto-subscribed at creation time and the new version is pinned as Available to AI. Other org members must subscribe() to see the skill in their AI auto-invoke registry. Pass tags to seed the skill’s tag list at creation time; later edits flow through UpdateSkillMetadataRequest. Pass relevant_topics to record the topic names v1’s procedure investigates; the chat AI resolves them to schemas when it loads the skill (see SkillVersionRecord.relevant_topics).

Usage

skill = Skill.create(
    name="qa-review",
    description="Run when the user asks for a QA review of a dataset.",
    body="Step 1: load the dataset summary...",
    accessibility=SkillAccessibility.Org,
    tags=["qa-review", "triage"],
    relevant_topics=["/imu/data", "/gps/fix"],
)
skill.skill_id
# 'sk_...'

Add a new version to this skill. The server assigns MAX(version) + 1.

Permitted for the author and — on an SkillAccessibility.OrgEditable skill — for any subscribed org member. Subscribers who pinned the previous version stay on that pin until they explicitly re-pin — the new row does not auto-promote.

Pass relevant_topics to record the topic names this version’s procedure investigates; the chat AI resolves them to schemas when it loads the skill (see SkillVersionRecord.relevant_topics).

Usage

v2 = skill.create_version(
    CreateSkillVersionRequest(
        description="Run when ...",
        body="Updated procedure ...",
        relevant_topics=["/imu/data", "/gps/fix"],
    )
)
v2.version
# 2

Hard-delete this skill. Author-only, including on OrgEditable skills.

Cascades to all versions and subscriptions. Existing chats keep any fabricated load_skill tool_use / tool_result blocks they’ve already produced — the body is captured at invocation time and written into the transcript.

Usage

skill.delete()

Delete a single version. If it’s the last remaining version, the parent skill is removed too.

Permitted for the author and — on an SkillAccessibility.OrgEditable skill — for any subscribed org member. A subscribed non-author may not delete the last remaining version: that cascades into a full skill delete, which is author-only. The author has no such restriction.

Subscriptions pinned to the deleted version have their ai_version nulled out via a server-side trigger; the subscription row survives.

Usage

skill.delete_version(1)

Load a skill by its skill_id.

Usage

skill = Skill.from_id("sk_abc123")
skill.name
# 'qa-review'

Load a skill by name in the caller’s organization.

Skill names are unique within (org_id, accessibility). When both a private and an org-shared skill share a name in the same org, this method returns the caller’s private one (the manual-invocation tie-break — see SkillsRepo.get_skill_by_name()).

Usage

skill = Skill.from_name("qa-review")
skill.accessibility
# <SkillAccessibility.Org: 'org'>

Load one skill’s summary: the skill, its latest version, and your subscription.

The single-skill counterpart of list_for_org(). Prefer it over filtering that listing when you already know the skill_id — it costs one row instead of the whole org’s skills.

Usage

summary = Skill.get_summary("sk_abc123")
summary.latest_version.version
# 3
summary.subscription is None  # not subscribed
# True

Load a specific version of this skill.

Usage

v2 = skill.get_version(2)
print(v2.body)

Yield SkillSummary items for every skill the caller can see in their org.

The summary includes the latest version (MAX(version)) and the caller’s own subscription row when one exists. When scope is provided the result is restricted to either Personal (authored or subscribed) or Org (org-shared skills the caller did not author, regardless of subscription state). Omit scope to receive every visible skill in one stream.

Usage

List the caller’s Personal-tab skills:

for summary in Skill.list_for_org(scope=SkillListScope.Personal):
    print(summary.skill.name, summary.subscription.ai_version if summary.subscription else None)

Iterate every visible skill (Personal + Org), in one pass:

all_visible = list(Skill.list_for_org())

Return the distinct tags found on skills the caller can see in this org.

Visibility-filtered the same way list_for_org() is — private skills owned by other users contribute no tags. Suitable for powering a tag-autocomplete UI.

Usage

Skill.list_known_tags()
# ['qa-review', 'triage', 'experiments']

List every version of this skill, newest first.

Usage

for version in skill.list_versions():
    print(version.version, version.description)

Re-fetch this skill’s record from the server and return self.

Useful after another caller may have updated the skill — bumps the local view past stale data.

Usage

skill.refresh()
skill.name  # now reflects any server-side rename
# 'qa-review'

Pin (or clear) which version of this skill the AI auto-invokes for the caller.

Pass an integer to expose that exact version to AI auto-invocation; pass None to disable AI auto-invocation while keeping the subscription. Implicitly subscribes the caller if no row exists yet. Visibility-gated; the caller does not have to be the author.

Usage

Pin version 2 for AI auto-invoke:

skill.set_ai_version(2)

Stop the AI from auto-invoking this skill, but stay subscribed so manual chip-invocation still works:

skill.set_ai_version(None)

Subscribe to this skill — adds it to the caller’s Personal tab.

Idempotent: if the caller is already subscribed (or is the author), the existing row is returned unchanged. New subscriptions default to ai_version=None (not yet exposed to AI). Use set_ai_version() to enable AI auto-invocation.

Usage

sub = skill.subscribe()
sub.ai_version is None
# True

Remove the caller’s subscription row — removes the skill from their Personal tab.

No-op if there is no subscription. Authors who unsubscribe from their own skill can re-subscribe later; authorship is unchanged.

Usage

skill.unsubscribe()

Update skill-level metadata (name, accessibility, tags).

Editing the name and tags is permitted for the author and — on an SkillAccessibility.OrgEditable skill — for any subscribed org member. Changing accessibility is always author-only.

Updates apply in place; the local record is replaced with the server’s authoritative copy.

Usage

skill.update_metadata(
    UpdateSkillMetadataRequest(
        accessibility=SkillAccessibility.Org,
        put_tags=["qa-review"],
    )
)

Edit fields on an existing version in place.

Permitted for the author and — on an SkillAccessibility.OrgEditable skill — for any subscribed org member.

Subscribers pinned to this version see the new body on their next AI invocation; there is no per-edit revision. Use create_version() when callers should not be auto-migrated.

Usage

skill.update_version(2, UpdateSkillVersionRequest(body="..."))