Managed Skills

What a managed skill is#

A managed skill is a SKILL.md file plus its helper files, imported from a GitHub repo into this workspace. Import records the repo, path, and the resolved commit so every run uses the same bytes. At run time the files are written into the workspace's sandbox at /workspace/.skills/<slug>/, and the sandbox agent reads SKILL.md off disk and decides for itself when to use it.

This is distinct from the platform skill registry: there is no server-side router for managed skills. They behave the way a local Claude Code or Codex session reads ~/.claude/skills/, by finding SKILL.md files and matching them to the task. Each skill is scoped to one workspace (business profile).

Discover#

List the SKILL.md files a repo exposes at a given ref, without importing anything.

Each candidate returns path_in_repo, slug, name, and description.

stimulir skills discover tosi-n/agentic-frame --ref main

from stimulir import StimulirClient

client = StimulirClient()

found = client.skills.discover(
    "tosi-n", "agentic-frame",
    workspace_id="<workspace-id>",
    ref="main",
)
for s in found:
    print(s["slug"], s["path_in_repo"])

Import (pinned to a commit)#

Import selected skill paths into the workspace. The chosen ref is resolved to a commit and the skill's files are stored against it, so the sandbox always materializes the exact version you imported.

Each imported skill returns id, slug, name, description, path_in_repo, and enabled.

stimulir skills import tosi-n/agentic-frame \
  --path skills/evidence-clip \
  --path skills/clip-capture \
  --ref main

client.skills.import_(
    "tosi-n", "agentic-frame",
    ["skills/evidence-clip", "skills/clip-capture"],
    workspace_id="<workspace-id>",
    ref="main",
)

List#

List the skills imported into the active workspace.

stimulir skills list

for s in client.skills.list(workspace_id="<workspace-id>"):
    print(s["slug"], s["name"], "enabled" if s["enabled"] else "disabled")

How a skill runs in the sandbox#

When a run starts, the workspace's imported skills are written into its sandbox before the prompt executes, one mkdir plus a file write per file, landing at /workspace/.skills/<slug>/. The agent then discovers the SKILL.md and applies it if the task calls for it. A skill that was never imported into the workspace simply isn't on disk, so it can't run.

A skill can also declare pip dependencies (from its pyproject); those are read and handed to the prompt so the run can self-provision them. See the Sandbox page for how the code-runtime session is created and where /workspace lives.

Required secrets and the Vault#

Some skills need extra third-party API keys, for example a research skill that calls Serper. A skill declares these as required_secrets, and matching keys from the workspace's Vault are decrypted and merged into the sandbox environment before the agent runs, so the skill's own code can authenticate from inside the sandbox.

Store each key (e.g. SERPER_API_KEY) in the workspace Vault first. Store the raw provider key, these are injected directly into the sandbox env, never routed through the gateway. Missing keys are skipped, so a partially-configured Vault still runs what it can. See the Vault page to add and manage secrets.