remoteSkills

Startup provisioning of remote Agent-Skill sources for a Mastra workspace.

A RemoteSkillSource names WHERE a SKILL.md tree comes from - the AITOOLS_SOURCE constant, a GitHub owner/repo, any git / GitLab URL, or a direct download URL - and optional per-source policy. provisionRemoteSkills materializes every source into a local SKILL.md tree at app boot and returns the directories to hand Mastra as extra skill scan paths.

Resolution per source, in order:

1. the AITOOLS_SOURCE constant ("aitools"): Databricks’ own skill set, read straight from the public repo the databricks aitools CLI sources from. No CLI, no Databricks auth - which is what makes it usable inside a Databricks App container, where the CLI is not installed;
2. the OPTIONAL skills npm CLI (peer dep): if installed, each source is copied into a staging dir with skills add <source> --agent <dir> --copy, which understands every source format the ecosystem does (GitHub shorthand, git URLs, archive/download URLs);
3. otherwise a plain fetch of the source URL (built with net.urlBuilder), writing the downloaded SKILL.md to a staging dir.

A source that resolves through neither path fails app startup, unless the source (or the top-level call) sets failOnError: false, in which case it is logged and skipped so one bad source never takes the app down.

Every provisioned tree carries a METADATA_FILE recording when each source was last downloaded, and a source is only re-downloaded once that record is older than DEFAULT_REFRESH_TTL_MS (seven days). This runs at app BOOT, so without it a container that restarts a dozen times an hour re-pulls the whole AI Tools set a dozen times for content that changes rarely. The record travels WITH the tree rather than in process memory, so the reuse survives a restart - which is the only way it helps a Databricks App at all. Pass refreshTtlMs: 0 to download on every boot.

The default destination is the Databricks workspace Assistant skills tree (/Workspace/.assistant/skills, the same tree a “save this as a skill” action writes to), so provisioned skills persist across restarts and are discovered by the built-in Assistant-skills mount. Pass userEmail (or an explicit databricksBasePath) to target /Users/<email>/.assistant/skills instead. When no Databricks client is resolvable at startup - or the resolved identity cannot WRITE the destination, which is the normal case for a Databricks App service principal against the admin-owned shared tree (see openWritableWorkspace) - the tree is written under localFS.tmpFS and returned as an extra local skill path for the current process. Storage location degrades; the skills themselves do not.

Interfaces

• ProvisionedRemoteSkills
• ProvisionRemoteSkillsOptions
• RemoteSkillCacheEntry
• RemoteSkillsMetadata
• RemoteSkillSourceOptions

Type Aliases

• AiToolsSource
• RemoteSkillsOption
• RemoteSkillSource

Variables

• AITOOLS_SOURCE

Functions

• normalizeRemoteSkillsOption
• provisionRemoteSkills