Struct SkillsApi 

pub struct SkillsApi { /* private fields */ }

The public skill surface for embedders.

Obtain one from crate::embedded::EmbeddedRuntime::skills. Cloning is cheap — it is an Arc internally — so a host may hand copies to whatever subsystem needs skill access.

Implementations

impl SkillsApi

pub fn for_test(inner: Arc<SkillService>) -> Self

Build a facade directly from a service.

Production hosts go through crate::embedded::EmbeddedRuntime::skills, which guarantees the service was built and initialised correctly. This exists so an integration test — which is a separate crate and cannot reach pub(crate) — can exercise the facade without standing up a whole runtime (and, notably, without supplying an LLM driver it has no use for).

pub async fn list(&self) -> Vec<Skill>

Every skill known to the runtime, enabled or not.

Includes pack builtins and anything installed at runtime. Use Self::list_enabled when presenting choices to a user.

pub async fn list_enabled(&self) -> Vec<Skill>

Only skills currently enabled.

A builtin that has been switched off is absent here but still present in Self::list — pack skills are never deleted, only disabled, so the two lists diverge rather than one shrinking permanently.

pub async fn get(&self, skill_id: &str) -> Option<Skill>

One skill by id, or None.

pub async fn install(&self, skill: Skill) -> Result<Skill>

Install a skill, registering it in the database when persistence is configured.

This is the explicit path: the caller asked for an install, so it happens. For skills a tool generates on the fly, see Self::install_generated, which is gated.

Errors

Propagates validation and storage failures from the underlying service.

pub async fn install_generated(&self, skill: Skill) -> Result<Option<Skill>>

Register a skill that was generated at runtime — only when the host has opted in.

Why this is separate from Self::install, and off by default

R4 says dynamic skill creation should register in the database optionally. “Optionally” has to live in the default, not just in the documentation: a generator that writes to the database by default silently grows a user’s skill catalogue with artifacts they never asked to keep, and a skills table that fills up on its own is far harder to diagnose than one that stays empty.

So the default is off. Opt in with either:

• UAR_REGISTER_GENERATED_SKILLS=true (or 1), or
• Self::with_generated_registration for programmatic control, which an embedded host can set without touching process environment.

Returns

Ok(None) when registration is not enabled — this is a normal, successful outcome, not a failure. Ok(Some(skill)) when it is.

Errors

Propagates validation and storage failures, but only on the enabled path — the disabled path cannot fail because it does nothing.

pub fn generated_registration_enabled(&self) -> bool

Is registration of generated skills currently enabled?

Explicit override wins; otherwise the environment decides; otherwise false.

pub fn with_generated_registration(self, enabled: bool) -> Self

Set generated-skill registration explicitly, overriding the environment.

For embedded hosts that decide this per-session rather than per-process — a mobile app cannot usefully set an env var on itself.

pub async fn toggle(&self, skill_id: &str, enabled: bool) -> bool

Enable or disable a skill. Returns false when no such skill exists.

This is the supported way to “remove” a pack builtin. Deletion is refused at the database by a trigger, so disabling is not a soft alternative to deleting — it is the only option.

pub async fn query(&self, query: &str) -> Vec<Skill>

Skills matching a natural-language query, best first.

Uses vector matching when an embedding backend is configured and falls back to keyword matching otherwise — an embedded host with no embedder still gets useful results rather than an empty list.

Trait Implementations

impl Clone for SkillsApi

fn clone(&self) -> SkillsApi

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SkillsApi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.