roboto.domain.skills.skill#

Module Contents#

class roboto.domain.skills.skill.Skill(record, roboto_client)#

An AI skill — a versioned, accessibility-scoped procedure the chat AI can apply.

Use create() to create a new skill, from_id() / from_name() to load existing ones, and list_for_org() to iterate. The constructor is internal.

Parameters:

record (roboto.domain.skills.record.SkillRecord)
roboto_client (roboto.http.RobotoClient)

property accessibility: roboto.domain.skills.record.SkillAccessibility#

Return type:: roboto.domain.skills.record.SkillAccessibility

classmethod create(name, description, body, accessibility=SkillAccessibility.Private, tags=None, caller_org_id=None, roboto_client=None)#

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.

Examples

>>> 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"],
... )
>>> skill.skill_id
'sk_...'

Parameters:

name (str)
description (str)
body (str)
accessibility (roboto.domain.skills.record.SkillAccessibility)
tags (Optional[collections.abc.Sequence[str]])
caller_org_id (Optional[str])
roboto_client (Optional[roboto.http.RobotoClient])

Return type:

Skill

create_version(request)#

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.

Examples

>>> v2 = skill.create_version(
...     CreateSkillVersionRequest(
...         description="Run when ...",
...         body="Updated procedure ...",
...     )
... )
>>> v2.version
2

Parameters:: request (roboto.domain.skills.operations.CreateSkillVersionRequest)
Return type:: roboto.domain.skills.record.SkillVersionRecord

property created_by: str#

Return type:: str

delete()#

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.

Examples

>>> skill.delete()

Return type:: None

delete_version(version)#

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.

Examples

>>> skill.delete_version(1)

Parameters:: version (int)
Return type:: None

classmethod from_id(skill_id, roboto_client=None)#

Load a skill by its skill_id.

Raises:

RobotoNotFoundException – No skill with this id exists, or the caller cannot see it (visibility-gated).

Parameters:

skill_id (str)
roboto_client (Optional[roboto.http.RobotoClient])

Return type:

Skill

Examples

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

classmethod from_name(name, caller_org_id=None, roboto_client=None)#

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()).

Parameters:

name (str) – Skill name. URL-encoded by the SDK.
caller_org_id (Optional[str]) – Look up in this org. Defaults to the caller’s current org.
roboto_client (Optional[roboto.http.RobotoClient])

Raises:

RobotoNotFoundException – No skill with this name is visible to the caller in the target org.

Return type:

Skill

Examples

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

get_version(version)#

Load a specific version of this skill.

Raises:: RobotoNotFoundException – No such version exists.
Parameters:: version (int)
Return type:: roboto.domain.skills.record.SkillVersionRecord

Examples

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

classmethod list_for_org(scope=None, caller_org_id=None, roboto_client=None)#

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.

Examples

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())

Parameters:

scope (Optional[roboto.domain.skills.operations.SkillListScope])
caller_org_id (Optional[str])
roboto_client (Optional[roboto.http.RobotoClient])

Return type:

collections.abc.Generator[roboto.domain.skills.record.SkillSummary, None, None]

classmethod list_known_tags(caller_org_id=None, roboto_client=None)#

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.

Examples

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

Parameters:

caller_org_id (Optional[str])
roboto_client (Optional[roboto.http.RobotoClient])

Return type:

list[str]

list_versions()#

List every version of this skill, newest first.

Examples

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

Return type:: list[roboto.domain.skills.record.SkillVersionRecord]

property name: str#

Return type:: str

property org_id: str#

Return type:: str

property record: roboto.domain.skills.record.SkillRecord#

Return type:: roboto.domain.skills.record.SkillRecord

refresh()#

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.

Examples

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

Return type:: Skill

set_ai_version(version)#

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.

Examples

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)

Parameters:: version (Optional[int])
Return type:: roboto.domain.skills.record.SkillSubscriptionRecord

property skill_id: str#

Return type:: str

subscribe()#

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.

Examples

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

Return type:: roboto.domain.skills.record.SkillSubscriptionRecord

property tags: list[str]#

Return type:: list[str]

unsubscribe()#

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.

Examples

>>> skill.unsubscribe()

Return type:: None

update_metadata(request)#

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.

Examples

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

Parameters:: request (roboto.domain.skills.operations.UpdateSkillMetadataRequest)
Return type:: Skill

update_version(version, request)#

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.

Examples

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

Parameters:

version (int)
request (roboto.domain.skills.operations.UpdateSkillVersionRequest)

Return type:

roboto.domain.skills.record.SkillVersionRecord